Mercurial > prosody-modules

comparison mod_http_oauth2/README.markdown @ 5653:62c6e17a5e9d

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 Mon, 18 Sep 2023 08:24:19 -0500
parents 23f336cec200
children b43c989fb69c
comparison
equal deleted inserted replaced
5652:eade7ff9f52c 5653:62c6e17a5e9d
1 --- 1 ---
2 labels: 2 labels:
3 - Stage-Alpha 3 - Stage-Alpha
4 summary: 'OAuth2 API'
5 rockspec: 4 rockspec:
6 build: 5 build:
7 copy_directories: 6 copy_directories:
8 - html 7 - html
9 ... 8 summary: OAuth 2.0 Authorization Server API
9 ---
10 10
11 ## Introduction 11 ## Introduction
12 12
13 This module implements an [OAuth2](https://oauth.net/2/)/[OpenID Connect 13 This module implements an [OAuth2](https://oauth.net/2/)/[OpenID Connect
14 (OIDC)](https://openid.net/connect/) provider HTTP frontend on top of 14 (OIDC)](https://openid.net/connect/) Authorization Server on top of
15 Prosody's usual internal authentication backend. 15 Prosody's usual internal authentication backend.
16 16
17 OAuth and OIDC are web standards that allow you to provide clients and 17 OAuth and OIDC are web standards that allow you to provide clients and
18 third-party applications limited access to your account, without sharing your 18 third-party applications limited access to your account, without sharing your
19 password with them. 19 password with them.
20 20
21 With this module deployed, software that supports OAuth can obtain "access 21 With this module deployed, software that supports OAuth can obtain
22 tokens" from Prosody which can then be used to connect to XMPP accounts using 22 "access tokens" from Prosody which can then be used to connect to XMPP
23 the 'OAUTHBEARER' SASL mechanism or via non-XMPP interfaces such as [mod_rest]. 23 accounts using the [OAUTHBEARER SASL mechanism][rfc7628] or via non-XMPP
24 interfaces such as [mod_rest].
24 25
25 Although this module has been around for some time, it has recently been 26 Although this module has been around for some time, it has recently been
26 significantly extended and largely rewritten to support OAuth/OIDC more fully. 27 significantly extended and largely rewritten to support OAuth/OIDC more fully.
27 28
28 As of April 2023, it should be considered **alpha** stage. It works, we have 29 As of April 2023, it should be considered **alpha** stage. It works, we have
34 Known client implementations: 35 Known client implementations:
35 36
36 - [example shell script for mod_rest](https://hg.prosody.im/prosody-modules/file/tip/mod_rest/example/rest.sh) 37 - [example shell script for mod_rest](https://hg.prosody.im/prosody-modules/file/tip/mod_rest/example/rest.sh)
37 - *(we need you!)* 38 - *(we need you!)*
38 39
39 Support for OAUTHBEARER has been added to the Lua XMPP library, [verse](https://code.matthewwild.co.uk/verse). 40 Support for [OAUTHBEARER][rfc7628] has been added to the Lua XMPP
40 If you know of additional implementations, or are motivated to work on one, 41 library, [verse](https://code.matthewwild.co.uk/verse). If you know of
41 please let us know! We'd be happy to help (e.g. by providing a test server). 42 additional implementations, or are motivated to work on one, please let
43 us know! We'd be happy to help (e.g. by providing a test server).
42 44
43 ## Standards support 45 ## Standards support
44 46
45 Notable supported standards: 47 Notable supported standards:
46 48
47 - [RFC 6749: The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749) 49 - [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) 50 - [RFC 7009: OAuth 2.0 Token Revocation](https://www.rfc-editor.org/rfc/rfc7009)
51 - [RFC 7591: OAuth 2.0 Dynamic Client Registration](https://www.rfc-editor.org/rfc/rfc7591.html)
49 - [RFC 7628: A Set of Simple Authentication and Security Layer (SASL) Mechanisms for OAuth](https://www.rfc-editor.org/rfc/rfc7628) 52 - [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) 53 - [RFC 7636: Proof Key for Code Exchange by OAuth Public Clients](https://www.rfc-editor.org/rfc/rfc7636)
54 - [RFC 8628: OAuth 2.0 Device Authorization Grant](https://www.rfc-editor.org/rfc/rfc8628)
55 - [RFC 9207: OAuth 2.0 Authorization Server Issuer Identification](https://www.rfc-editor.org/rfc/rfc9207.html)
51 - [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) 56 - [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) 57 - [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) (_partial, e.g. missing JWKS_)
53 - [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) 58 - [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html)
54 59
55 ## Configuration 60 ## Configuration
56 61
57 ### Interface 62 ### Interface
58 63
59 The module presents a web page to users to allow them to authenticate when 64 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 65 a client requests access. Built-in pages are provided, but you may also theme
61 or entirely override them. 66 or entirely override them.
62 67
63 This module honours the 'site_name' configuration option that is also used by 68 This module honours the `site_name` configuration option that is also used by
64 a number of other modules: 69 a number of other modules:
65 70
66 ```lua 71 ```lua
67 site_name = "My XMPP Server" 72 site_name = "My XMPP Server"
68 ``` 73 ```
71 76
72 ```lua 77 ```lua
73 oauth2_template_path = "/etc/prosody/custom-oauth2-templates" 78 oauth2_template_path = "/etc/prosody/custom-oauth2-templates"
74 ``` 79 ```
75 80
76 Some templates support additional variables, that can be provided by the 81 If you know what features your templates use use you can adjust the
77 'oauth2_template_style' option: 82 `Content-Security-Policy` header to only allow what is needed:
78 83
79 ```lua 84 ```lua
80 oauth2_template_style = { 85 oauth2_security_policy = "default-src 'self'" -- this is the default
81 background_colour = "#ffffff";
82 }
83 ``` 86 ```
84 87
85 ### Token parameters 88 ### Token parameters
86 89
87 The following options configure the lifetime of tokens issued by the module. 90 The following options configure the lifetime of tokens issued by the module.
88 The defaults are recommended. 91 The defaults are recommended.
89 92
90 ```lua 93 ```lua
91 oauth2_access_token_ttl = 86400 -- 24 hours 94 oauth2_access_token_ttl = 3600 -- one hour
92 oauth2_refresh_token_ttl = nil -- unlimited unless revoked by the user 95 oauth2_refresh_token_ttl = 604800 -- one week
93 ``` 96 ```
94 97
95 ### Dynamic client registration 98 ### Dynamic client registration
96 99
97 To allow users to connect any compatible software, you should enable dynamic 100 To allow users to connect any compatible software, you should enable dynamic
104 oauth2_registration_key = "securely generated JWT key here" 107 oauth2_registration_key = "securely generated JWT key here"
105 oauth2_registration_algorithm = "HS256" 108 oauth2_registration_algorithm = "HS256"
106 oauth2_registration_ttl = nil -- unlimited by default 109 oauth2_registration_ttl = nil -- unlimited by default
107 ``` 110 ```
108 111
112 Registering a client is described in
113 [RFC7591](https://www.rfc-editor.org/rfc/rfc7591.html).
114
115 In addition to the requirements in the RFC, the following requirements
116 are enforced:
117
118 `client_name`
119 : **MUST** be present, is shown to users in consent screen.
120
121 `client_uri`
122 : **MUST** be present and **MUST** be a `https://` URL.
123
124 `redirect_uris`
125
126 : **MUST** contain at least one valid URI. Different rules apply
127 depending on the value of `application_type`, see below.
128
129 `application_type`
130
131 : Optional, defaults to `web`. Determines further restrictions for
132 `redirect_uris`. The following values are supported:
133
134 `web` *(default)*
135 : For web clients. With this, `redirect_uris` **MUST** be
136 `https://` URIs and **MUST** use the same hostname part as the
137 `client_uri`.
138
139 `native`
140 : For native e.g. desktop clients etc. `redirect_uris` **MUST**
141 match one of:
142
143 - Loopback HTTP URI, e.g. `http://127.0.0.1/` or
144 `http://[::1]`
145 - Application-specific scheme, e.g. `com.example.app:/`
146 - The special OOB URI `urn:ietf:wg:oauth:2.0:oob`
147
148 `tos_uri`, `policy_uri`
149 : Informative URLs pointing to Terms of Service and Service Policy
150 document **MUST** use the same scheme (i.e. `https://`) and hostname
151 as the `client_uri`.
152
153 #### Registration Examples
154
155 In short registration works by POST-ing a JSON structure describing your
156 client to an endpoint:
157
158 ``` bash
159 curl -sSf https://xmpp.example.net/oauth2/register \
160 -H Content-Type:application/json \
161 -H Accept:application/json \
162 --data '
163 {
164 "client_name" : "My Application",
165 "client_uri" : "https://app.example.com/",
166 "redirect_uris" : [
167 "https://app.example.com/redirect"
168 ]
169 }
170 '
171 ```
172
173 Another example with more fields:
174
175 ``` bash
176 curl -sSf https://xmpp.example.net/oauth2/register \
177 -H Content-Type:application/json \
178 -H Accept:application/json \
179 --data '
180 {
181 "application_type" : "native",
182 "client_name" : "Desktop Chat App",
183 "client_uri" : "https://app.example.org/",
184 "contacts" : [
185 "support@example.org"
186 ],
187 "policy_uri" : "https://app.example.org/about/privacy",
188 "redirect_uris" : [
189 "http://localhost:8080/redirect",
190 "org.example.app:/redirect"
191 ],
192 "scope" : "xmpp",
193 "software_id" : "32a0a8f3-4016-5478-905a-c373156eca73",
194 "software_version" : "3.4.1",
195 "tos_uri" : "https://app.example.org/about/terms"
196 }
197 '
198 ```
199
109 ### Supported flows 200 ### Supported flows
201
202 - Authorization Code grant, optionally with Proof Key for Code Exchange
203 - Device Authorization Grant
204 - Resource owner password grant *(likely to be phased out in the future)*
205 - Implicit flow *(disabled by default)*
206 - Refresh Token grants
110 207
111 Various flows can be disabled and enabled with 208 Various flows can be disabled and enabled with
112 `allowed_oauth2_grant_types` and `allowed_oauth2_response_types`: 209 `allowed_oauth2_grant_types` and `allowed_oauth2_response_types`:
113 210
114 ```lua 211 ```lua
212 -- These examples reflect the defaults
115 allowed_oauth2_grant_types = { 213 allowed_oauth2_grant_types = {
116 "authorization_code"; -- authorization code grant 214 "authorization_code"; -- authorization code grant
215 "device_code";
117 "password"; -- resource owner password grant 216 "password"; -- resource owner password grant
118 } 217 }
119 218
120 allowed_oauth2_response_types = { 219 allowed_oauth2_response_types = {
121 "code"; -- authorization code flow 220 "code"; -- authorization code flow
122 -- "token"; -- implicit flow disabled by default 221 -- "token"; -- implicit flow disabled by default
123 } 222 }
124 ``` 223 ```
125 224
126 The [Proof Key for Code Exchange][RFC 7636] mitigation method can be 225 The [Proof Key for Code Exchange][RFC 7636] mitigation method is
127 made required: 226 optional by default but can be made required:
128 227
129 ```lua 228 ```lua
130 oauth2_require_code_challenge = true 229 oauth2_require_code_challenge = true -- default is false
131 ``` 230 ```
132 231
133 Further, individual challenge methods can be enabled or disabled: 232 Further, individual challenge methods can be enabled or disabled:
134 233
135 ```lua 234 ```lua
235 -- These reflects the default
136 allowed_oauth2_code_challenge_methods = { 236 allowed_oauth2_code_challenge_methods = {
137 "plain"; -- the insecure one 237 "plain"; -- the insecure one
138 "S256"; 238 "S256";
139 } 239 }
140 ``` 240 ```
145 for use by OAuth clients: 245 for use by OAuth clients:
146 246
147 ```lua 247 ```lua
148 oauth2_terms_url = "https://example.com/terms-of-service.html" 248 oauth2_terms_url = "https://example.com/terms-of-service.html"
149 oauth2_policy_url = "https://example.com/service-policy.pdf" 249 oauth2_policy_url = "https://example.com/service-policy.pdf"
250 -- These are unset by default
150 ``` 251 ```
151 252
152 ## Deployment notes 253 ## Deployment notes
153 254
154 ### Access management 255 ### Access management
155 256
156 This module does not provide an interface for users to manage what they have 257 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 258 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 259 previously authorized). It is recommended to join this module with
159 mod_client_management to provide such access. However, at the time of writing, 260 [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 261 no XMPP clients currently support the protocol used by that module. We plan to
161 work on additional interfaces in the future. 262 work on additional interfaces in the future.
162 263
163 ### Scopes 264 ### Scopes
164 265
165 OAuth supports "scopes" as a way to grant clients limited access. 266 OAuth supports "scopes" as a way to grant clients limited access.
166 267
167 There are currently no standard scopes defined for XMPP. This is something 268 There are currently no standard scopes defined for XMPP. This is
168 that we intend to change, e.g. by definitions provided in a future XEP. This 269 something that we intend to change, e.g. by definitions provided in a
169 means that clients you authorize currently have unrestricted access to your 270 future XEP. This means that clients you authorize currently have to
170 account (including the ability to change your password and lock you out!). So, 271 choose between unrestricted access to your account (including the
171 for now, while using OAuth clients can prevent leaking your password to them, 272 ability to change your password and lock you out!) and zero access. So,
172 it is not currently suitable for connecting untrusted clients to your account. 273 for now, while using OAuth clients can prevent leaking your password to
274 them, it is not currently suitable for connecting untrusted clients to
275 your account.
276
277 As a first step, the `xmpp` scope is supported, and corresponds to
278 whatever permissions the user would have when logged in over XMPP.
279
280 Further, known Prosody roles can be used as scopes.
281
282 OpenID scopes such as `openid` and `profile` can be used for "Login
283 with XMPP" without granting access to more than limited profile details.
173 284
174 ## Compatibility 285 ## Compatibility
175 286
176 Requires Prosody trunk (April 2023), **not** compatible with Prosody 0.12 or 287 Requires Prosody trunk (April 2023), **not** compatible with Prosody 0.12 or
177 earlier. 288 earlier.