Mercurial > prosody-modules

annotate mod_http_oauth2/README.markdown @ 5511:0860497152af

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_http_oauth2: Record hash of client_id to allow future verification RFC 6819 section 5.2.2.2 states that refresh tokens MUST be bound to the client. In order to do that, we must record something that can definitely tie the client to the grant. Since the full client_id is so large (why we have this client_subset function), a hash is stored instead.
author Kim Alvefur <zash@zash.se>
date Fri, 02 Jun 2023 10:14:16 +0200
parents 56803acfa638
children 67448e677706
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3903
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
cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only)
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
4 summary: 'OAuth2 API'
5212
3235b8bd1e55 mod_http_oauth2: Include html templates in package for plugin installer
Kim Alvefur <zash@zash.se>
parents: 5197
diff changeset
5 rockspec:
3235b8bd1e55 mod_http_oauth2: Include html templates in package for plugin installer
Kim Alvefur <zash@zash.se>
parents: 5197
diff changeset
6 build:
3235b8bd1e55 mod_http_oauth2: Include html templates in package for plugin installer
Kim Alvefur <zash@zash.se>
parents: 5197
diff changeset
7 copy_directories:
3235b8bd1e55 mod_http_oauth2: Include html templates in package for plugin installer
Kim Alvefur <zash@zash.se>
parents: 5197
diff changeset
8 - html
3903
cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only)
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
9 ...
cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only)
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
10
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
11 ## Introduction
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
12
5315
8501baa7ef3f mod_http_oauth2/README: Link to OAuth and OIDC sites
Kim Alvefur <zash@zash.se>
parents: 5313
diff changeset
13 This module implements an [OAuth2](https://oauth.net/2/)/[OpenID Connect
8501baa7ef3f mod_http_oauth2/README: Link to OAuth and OIDC sites
Kim Alvefur <zash@zash.se>
parents: 5313
diff changeset
14 (OIDC)](https://openid.net/connect/) provider HTTP frontend on top of
8501baa7ef3f mod_http_oauth2/README: Link to OAuth and OIDC sites
Kim Alvefur <zash@zash.se>
parents: 5313
diff changeset
15 Prosody's usual internal authentication backend.
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
16
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
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: 5212
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: 5212
diff changeset
19 password with them.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
20
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
21 With this module deployed, software that supports OAuth can obtain "access
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
22 tokens" from Prosody which can then be used to connect to XMPP accounts using
5316
4fc3277a914d mod_http_oauth2/README: Link to mod_rest
Kim Alvefur <zash@zash.se>
parents: 5315
diff changeset
23 the 'OAUTHBEARER' SASL mechanism or via non-XMPP interfaces such as [mod_rest].
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
24
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
25 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: 5212
diff changeset
26 significantly extended and largely rewritten to support OAuth/OIDC more fully.
3903
cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only)
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
27
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
28 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: 5212
diff changeset
29 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: 5212
diff changeset
30 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: 5212
diff changeset
31 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: 5212
diff changeset
32 below.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
33
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
34 Known client implementations:
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
35
5328
dd8616e68cb3 mod_http_oauth2/README: Add rest.sh to known implementations
Kim Alvefur <zash@zash.se>
parents: 5316
diff changeset
36 - [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: 5316
diff changeset
37 - *(we need you!)*
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
38
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
39 Support for OAUTHBEARER has been added to the Lua XMPP library, [verse](https://code.matthewwild.co.uk/verse).
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
40 If you know of additional implementations, or are motivated to work on one,
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
41 please let us know! We'd be happy to help (e.g. by providing a test server).
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
42
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
43 ## Standards support
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
44
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
45 Notable supported standards:
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
46
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
47 - [RFC 6749: The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749)
5410
644b2f2b9b52 mod_http_oauth2: Link to RFC 7009: OAuth 2.0 Token Revocation
Kim Alvefur <zash@zash.se>
parents: 5408
diff changeset
48 - [RFC 7009: OAuth 2.0 Token Revocation](https://www.rfc-editor.org/rfc/rfc7009)
5464
2a11f590c5c8 mod_http_oauth2: Split long list line in README
Kim Alvefur <zash@zash.se>
parents: 5416
diff changeset
49 - [RFC 7591: OAuth 2.0 Dynamic Client Registration](https://www.rfc-editor.org/rfc/rfc7591.html)
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
50 - [RFC 7628: A Set of Simple Authentication and Security Layer (SASL) Mechanisms for OAuth](https://www.rfc-editor.org/rfc/rfc7628)
5383
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange
Kim Alvefur <zash@zash.se>
parents: 5328
diff changeset
51 - [RFC 7636: Proof Key for Code Exchange by OAuth Public Clients](https://www.rfc-editor.org/rfc/rfc7636)
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
52 - [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)
5465
66e13e79928b mod_http_oauth2: Note about partial OpenID Discovery implementation
Kim Alvefur <zash@zash.se>
parents: 5464
diff changeset
53 - [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) (_partial, e.g. missing JWKS_)
5464
2a11f590c5c8 mod_http_oauth2: Split long list line in README
Kim Alvefur <zash@zash.se>
parents: 5416
diff changeset
54 - [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html)
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
55
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
56 ## Configuration
3903
cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only)
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
57
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
58 ### Interface
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
59
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
60 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: 5212
diff changeset
61 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: 5212
diff changeset
62 or entirely override them.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
63
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
64 This module honours the 'site_name' configuration option that is also used by
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
65 a number of other modules:
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
66
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
67 ```lua
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
68 site_name = "My XMPP Server"
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
69 ```
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
70
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
71 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: 5212
diff changeset
72
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
73 ```lua
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
74 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: 5212
diff changeset
75 ```
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
76
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
77 Some templates support additional variables, that can be provided by the
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
78 'oauth2_template_style' option:
3903
cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only)
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
79
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
80 ```lua
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
81 oauth2_template_style = {
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
82 background_colour = "#ffffff";
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
83 }
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
84 ```
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
85
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
86 ### Token parameters
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
87
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
88 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: 5212
diff changeset
89 The defaults are recommended.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
90
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
91 ```lua
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
92 oauth2_access_token_ttl = 86400 -- 24 hours
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
93 oauth2_refresh_token_ttl = nil -- unlimited unless revoked by the user
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
94 ```
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
95
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
96 ### Dynamic client registration
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
97
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
98 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: 5212
diff changeset
99 client registration.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
100
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
101 Dynamic client registration can be enabled by configuring a JWT key. Algorithm
5416
2393dbae51ed mod_http_oauth2: Add option for specifying TTL of registered clients
Kim Alvefur <zash@zash.se>
parents: 5410
diff changeset
102 defaults to *HS256* lifetime defaults to forever.
5197
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
103
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
104 ```lua
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
105 oauth2_registration_key = "securely generated JWT key here"
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
106 oauth2_registration_algorithm = "HS256"
5416
2393dbae51ed mod_http_oauth2: Add option for specifying TTL of registered clients
Kim Alvefur <zash@zash.se>
parents: 5410
diff changeset
107 oauth2_registration_ttl = nil -- unlimited by default
5197
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
108 ```
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
109
5493
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
110 Registering a client is described in
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
111 [RFC7591](https://www.rfc-editor.org/rfc/rfc7591.html).
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
112
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
113 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: 5467
diff changeset
114 are enforced:
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
115
5506
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
116 `client_name`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
117 : **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: 5505
diff changeset
118
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
119 `client_uri`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
120 : **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: 5505
diff changeset
121
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
122 `redirect_uris`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
123
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
124 : **MUST** contain at least one valid URI. Different rules apply
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
125 depending on the value of `application_type`:
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
126
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
127 `web`
5507
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements
Kim Alvefur <zash@zash.se>
parents: 5506
diff changeset
128 : `redirect_uris` **MUST** be `https://` URIs and **MUST** use the
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements
Kim Alvefur <zash@zash.se>
parents: 5506
diff changeset
129 same hostname part as the `client_uri`.
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements
Kim Alvefur <zash@zash.se>
parents: 5506
diff changeset
130
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements
Kim Alvefur <zash@zash.se>
parents: 5506
diff changeset
131 `native`
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements
Kim Alvefur <zash@zash.se>
parents: 5506
diff changeset
132
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements
Kim Alvefur <zash@zash.se>
parents: 5506
diff changeset
133 : `redirect_uris` **MUST** match one of:
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements
Kim Alvefur <zash@zash.se>
parents: 5506
diff changeset
134
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements
Kim Alvefur <zash@zash.se>
parents: 5506
diff changeset
135 - Loopback HTTP URI, e.g. `http://127.0.0.1/` or
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements
Kim Alvefur <zash@zash.se>
parents: 5506
diff changeset
136 `http://[::1]`
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements
Kim Alvefur <zash@zash.se>
parents: 5506
diff changeset
137 - Application-specific scheme, e.g. `com.example.app:/`
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements
Kim Alvefur <zash@zash.se>
parents: 5506
diff changeset
138 - The special OOB URI `urn:ietf:wg:oauth:2.0:oob`
5506
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
139
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
140 `application_type`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
141
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
142 : Optional, defaults to `web`. Determines further restrictions for
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
143 `redirect_uris`. The following values are supported:
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
144
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
145 `web` *(default)*
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
146 : For web clients.
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
147
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
148 `native`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
149 : For native e.g. desktop clients etc.
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
150
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
151 `tos_uri`, `policy_uri`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
152 : 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: 5505
diff changeset
153 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: 5505
diff changeset
154 as the `client_uri`.
5493
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
155
5494
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
156 #### Registration Example
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
157
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
158 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: 5493
diff changeset
159 client to an endpoint:
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
160
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
161 ``` bash
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
162 curl -sSf https://xmpp.example.net/oauth2/register \
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
163 -H Content-Type:application/json \
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
164 -H Accept:application/json \
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
165 --data '
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
166 {
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
167 "client_name" : "My Application",
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
168 "client_uri" : "https://app.example.com/",
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
169 "redirect_uris" : [
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
170 "https://app.example.com/redirect"
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
171 ]
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
172 }
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
173 '
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
174 ```
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
175
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
176 ### Supported flows
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
177
5197
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
178 Various flows can be disabled and enabled with
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
179 `allowed_oauth2_grant_types` and `allowed_oauth2_response_types`:
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
180
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
181 ```lua
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
182 allowed_oauth2_grant_types = {
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
183 "authorization_code"; -- authorization code grant
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
184 "password"; -- resource owner password grant
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
185 }
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
186
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
187 allowed_oauth2_response_types = {
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
188 "code"; -- authorization code flow
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
189 -- "token"; -- implicit flow disabled by default
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
190 }
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
191 ```
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
192
5383
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange
Kim Alvefur <zash@zash.se>
parents: 5328
diff changeset
193 The [Proof Key for Code Exchange][RFC 7636] mitigation method can be
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange
Kim Alvefur <zash@zash.se>
parents: 5328
diff changeset
194 made required:
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange
Kim Alvefur <zash@zash.se>
parents: 5328
diff changeset
195
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange
Kim Alvefur <zash@zash.se>
parents: 5328
diff changeset
196 ```lua
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange
Kim Alvefur <zash@zash.se>
parents: 5328
diff changeset
197 oauth2_require_code_challenge = true
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange
Kim Alvefur <zash@zash.se>
parents: 5328
diff changeset
198 ```
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange
Kim Alvefur <zash@zash.se>
parents: 5328
diff changeset
199
5384
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
200 Further, individual challenge methods can be enabled or disabled:
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
201
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
202 ```lua
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
203 allowed_oauth2_code_challenge_methods = {
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
204 "plain"; -- the insecure one
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
205 "S256";
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
206 }
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
207 ```
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
208
5408
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata
Kim Alvefur <zash@zash.se>
parents: 5384
diff changeset
209 ### Policy documents
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata
Kim Alvefur <zash@zash.se>
parents: 5384
diff changeset
210
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata
Kim Alvefur <zash@zash.se>
parents: 5384
diff changeset
211 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: 5384
diff changeset
212 for use by OAuth clients:
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata
Kim Alvefur <zash@zash.se>
parents: 5384
diff changeset
213
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata
Kim Alvefur <zash@zash.se>
parents: 5384
diff changeset
214 ```lua
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata
Kim Alvefur <zash@zash.se>
parents: 5384
diff changeset
215 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: 5384
diff changeset
216 oauth2_policy_url = "https://example.com/service-policy.pdf"
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata
Kim Alvefur <zash@zash.se>
parents: 5384
diff changeset
217 ```
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata
Kim Alvefur <zash@zash.se>
parents: 5384
diff changeset
218
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
219 ## Deployment notes
3903
cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only)
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
220
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
221 ### Access management
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
222
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
223 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: 5212
diff changeset
224 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: 5212
diff changeset
225 previously authorized). It is recommended to join this module with
5508
56803acfa638 mod_http_oauth2: Linkify mod_client_management in README
Kim Alvefur <zash@zash.se>
parents: 5507
diff changeset
226 [mod_client_management] to provide such access. However, at the time of writing,
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
227 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: 5212
diff changeset
228 work on additional interfaces in the future.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
229
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
230 ### Scopes
3903
cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only)
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
231
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
232 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: 5212
diff changeset
233
5467
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role
Kim Alvefur <zash@zash.se>
parents: 5465
diff changeset
234 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: 5465
diff changeset
235 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: 5465
diff changeset
236 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: 5465
diff changeset
237 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: 5465
diff changeset
238 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: 5465
diff changeset
239 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: 5465
diff changeset
240 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: 5465
diff changeset
241 your account.
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role
Kim Alvefur <zash@zash.se>
parents: 5465
diff changeset
242
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role
Kim Alvefur <zash@zash.se>
parents: 5465
diff changeset
243 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: 5465
diff changeset
244 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: 5465
diff changeset
245
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role
Kim Alvefur <zash@zash.se>
parents: 5465
diff changeset
246 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: 5465
diff changeset
247
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role
Kim Alvefur <zash@zash.se>
parents: 5465
diff changeset
248 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: 5465
diff changeset
249 with XMPP" without granting access to more than limited profile details.
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
250
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
251 ## Compatibility
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
252
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
253 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: 5212
diff changeset
254 earlier.