prosody-modules
75dee6127829
mod_http_oauth2/README.markdown

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Comparison

mod_http_oauth2/README.markdown @ 5856:75dee6127829 draft

Merge upstream
author Trần H. Trung <xmpp:trần.h.trung@trung.fun>
date Tue, 06 Feb 2024 18:32:01 +0700
parent 5739:426c42c11f89
child 5882:761142ee0ff2
comparison
equal deleted inserted replaced
5664:52db2da66680 5856:75dee6127829
9 --- 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.
49 - [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)
50 - [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) 51 - [RFC 7591: OAuth 2.0 Dynamic Client Registration](https://www.rfc-editor.org/rfc/rfc7591.html)
52 - [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)
53 - [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 7662: OAuth 2.0 Token Introspection](https://www.rfc-editor.org/rfc/rfc7662)
54 - [RFC 8628: OAuth 2.0 Device Authorization Grant](https://www.rfc-editor.org/rfc/rfc8628) 55 - [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) 56 - [RFC 9207: OAuth 2.0 Authorization Server Issuer Identification](https://www.rfc-editor.org/rfc/rfc9207.html)
56 - [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) 57 - [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)
57 - [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) (_partial, e.g. missing JWKS_) 58 - [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) (_partial, e.g. missing JWKS_)
58 - [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) 59 - [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html)
74 75
75 To provide custom templates, specify the path to the template directory: 76 To provide custom templates, specify the path to the template directory:
76 77
77 ```lua 78 ```lua
78 oauth2_template_path = "/etc/prosody/custom-oauth2-templates" 79 oauth2_template_path = "/etc/prosody/custom-oauth2-templates"
79 ```
80
81 Some templates support additional variables, that can be provided by the
82 `oauth2_template_style` option:
83
84 ```lua
85 oauth2_template_style = {
86 background_colour = "#ffffff";
87 }
88 ``` 80 ```
89 81
90 If you know what features your templates use use you can adjust the 82 If you know what features your templates use use you can adjust the
91 `Content-Security-Policy` header to only allow what is needed: 83 `Content-Security-Policy` header to only allow what is needed:
92 84
230 -- "token"; -- implicit flow disabled by default 222 -- "token"; -- implicit flow disabled by default
231 } 223 }
232 ``` 224 ```
233 225
234 The [Proof Key for Code Exchange][RFC 7636] mitigation method is 226 The [Proof Key for Code Exchange][RFC 7636] mitigation method is
235 optional by default but can be made required: 227 required by default but can be made optional:
236 228
237 ```lua 229 ```lua
238 oauth2_require_code_challenge = true -- default is false 230 oauth2_require_code_challenge = false -- default is true
239 ``` 231 ```
240 232
241 Further, individual challenge methods can be enabled or disabled: 233 Further, individual challenge methods can be enabled or disabled:
242 234
243 ```lua 235 ```lua
244 -- These reflects the default 236 -- These reflects the default
245 allowed_oauth2_code_challenge_methods = { 237 allowed_oauth2_code_challenge_methods = {
246 "plain"; -- the insecure one 238 -- "plain"; -- insecure but backwards-compatible
247 "S256"; 239 "S256";
248 } 240 }
249 ``` 241 ```
250 242
251 ### Policy documents 243 ### Policy documents