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