Mercurial > prosody-modules

comparison mod_http_oauth2/README.markdown @ 5650:0eb2d5ea2428

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
merge
author Stephen Paul Weber <singpolyma@singpolyma.net>
date Sat, 06 May 2023 19:40:23 -0500
parents 2393dbae51ed
children 2a11f590c5c8
comparison
equal deleted inserted replaced
5649:2c69577b28c2 5650:0eb2d5ea2428
1 --- 1 ---
2 labels: 2 labels:
3 - Stage-Alpha 3 - Stage-Alpha
4 summary: 'OAuth2 API' 4 summary: 'OAuth2 API'
5 rockspec:
6 build:
7 copy_directories:
8 - html
5 ... 9 ...
6 10
7 Introduction 11 ## Introduction
8 ============
9 12
10 This module is a work-in-progress intended for developers only! 13 This module implements an [OAuth2](https://oauth.net/2/)/[OpenID Connect
14 (OIDC)](https://openid.net/connect/) provider HTTP frontend on top of
15 Prosody's usual internal authentication backend.
11 16
12 Configuration 17 OAuth and OIDC are web standards that allow you to provide clients and
13 ============= 18 third-party applications limited access to your account, without sharing your
19 password with them.
14 20
15 None currently. 21 With this module deployed, software that supports OAuth can obtain "access
22 tokens" from Prosody which can then be used to connect to XMPP accounts using
23 the 'OAUTHBEARER' SASL mechanism or via non-XMPP interfaces such as [mod_rest].
16 24
17 Compatibility 25 Although this module has been around for some time, it has recently been
18 ============= 26 significantly extended and largely rewritten to support OAuth/OIDC more fully.
19 27
20 Requires Prosody 0.12+ or trunk. 28 As of April 2023, it should be considered **alpha** stage. It works, we have
29 tested it, but it has not yet seen wider review, testing and deployment. At
30 this stage we recommend it for experimental and test deployments only. For
31 specific information, see the [deployment notes section](#deployment-notes)
32 below.
33
34 Known client implementations:
35
36 - [example shell script for mod_rest](https://hg.prosody.im/prosody-modules/file/tip/mod_rest/example/rest.sh)
37 - *(we need you!)*
38
39 Support for OAUTHBEARER has been added to the Lua XMPP library, [verse](https://code.matthewwild.co.uk/verse).
40 If you know of additional implementations, or are motivated to work on one,
41 please let us know! We'd be happy to help (e.g. by providing a test server).
42
43 ## Standards support
44
45 Notable supported standards:
46
47 - [RFC 6749: The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749)
48 - [RFC 7009: OAuth 2.0 Token Revocation](https://www.rfc-editor.org/rfc/rfc7009)
49 - [RFC 7628: A Set of Simple Authentication and Security Layer (SASL) Mechanisms for OAuth](https://www.rfc-editor.org/rfc/rfc7628)
50 - [RFC 7636: Proof Key for Code Exchange by OAuth Public Clients](https://www.rfc-editor.org/rfc/rfc7636)
51 - [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)
52 - [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) & [RFC 7591: OAuth 2.0 Dynamic Client Registration](https://www.rfc-editor.org/rfc/rfc7591.html)
53 - [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html)
54
55 ## Configuration
56
57 ### Interface
58
59 The module presents a web page to users to allow them to authenticate when
60 a client requests access. Built-in pages are provided, but you may also theme
61 or entirely override them.
62
63 This module honours the 'site_name' configuration option that is also used by
64 a number of other modules:
65
66 ```lua
67 site_name = "My XMPP Server"
68 ```
69
70 To provide custom templates, specify the path to the template directory:
71
72 ```lua
73 oauth2_template_path = "/etc/prosody/custom-oauth2-templates"
74 ```
75
76 Some templates support additional variables, that can be provided by the
77 'oauth2_template_style' option:
78
79 ```lua
80 oauth2_template_style = {
81 background_colour = "#ffffff";
82 }
83 ```
84
85 ### Token parameters
86
87 The following options configure the lifetime of tokens issued by the module.
88 The defaults are recommended.
89
90 ```lua
91 oauth2_access_token_ttl = 86400 -- 24 hours
92 oauth2_refresh_token_ttl = nil -- unlimited unless revoked by the user
93 ```
94
95 ### Dynamic client registration
96
97 To allow users to connect any compatible software, you should enable dynamic
98 client registration.
99
100 Dynamic client registration can be enabled by configuring a JWT key. Algorithm
101 defaults to *HS256* lifetime defaults to forever.
102
103 ```lua
104 oauth2_registration_key = "securely generated JWT key here"
105 oauth2_registration_algorithm = "HS256"
106 oauth2_registration_ttl = nil -- unlimited by default
107 ```
108
109 ### Supported flows
110
111 Various flows can be disabled and enabled with
112 `allowed_oauth2_grant_types` and `allowed_oauth2_response_types`:
113
114 ```lua
115 allowed_oauth2_grant_types = {
116 "authorization_code"; -- authorization code grant
117 "password"; -- resource owner password grant
118 }
119
120 allowed_oauth2_response_types = {
121 "code"; -- authorization code flow
122 -- "token"; -- implicit flow disabled by default
123 }
124 ```
125
126 The [Proof Key for Code Exchange][RFC 7636] mitigation method can be
127 made required:
128
129 ```lua
130 oauth2_require_code_challenge = true
131 ```
132
133 Further, individual challenge methods can be enabled or disabled:
134
135 ```lua
136 allowed_oauth2_code_challenge_methods = {
137 "plain"; -- the insecure one
138 "S256";
139 }
140 ```
141
142 ### Policy documents
143
144 Links to Terms of Service and Service Policy documents can be advertised
145 for use by OAuth clients:
146
147 ```lua
148 oauth2_terms_url = "https://example.com/terms-of-service.html"
149 oauth2_policy_url = "https://example.com/service-policy.pdf"
150 ```
151
152 ## Deployment notes
153
154 ### Access management
155
156 This module does not provide an interface for users to manage what they have
157 granted access to their account! (e.g. to view and revoke clients they have
158 previously authorized). It is recommended to join this module with
159 mod_client_management to provide such access. However, at the time of writing,
160 no XMPP clients currently support the protocol used by that module. We plan to
161 work on additional interfaces in the future.
162
163 ### Scopes
164
165 OAuth supports "scopes" as a way to grant clients limited access.
166
167 There are currently no standard scopes defined for XMPP. This is something
168 that we intend to change, e.g. by definitions provided in a future XEP. This
169 means that clients you authorize currently have unrestricted access to your
170 account (including the ability to change your password and lock you out!). So,
171 for now, while using OAuth clients can prevent leaking your password to them,
172 it is not currently suitable for connecting untrusted clients to your account.
173
174 ## Compatibility
175
176 Requires Prosody trunk (April 2023), **not** compatible with Prosody 0.12 or
177 earlier.