prosody-modules
24316a399978
mod_http_oauth2/README.md

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

Software / code / prosody-modules

Annotate

mod_http_oauth2/README.md @ 6210:24316a399978 draft

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