Mercurial > prosody-modules

annotate mod_http_oauth2/README.markdown @ 5502:fd4d89a5b8db

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_http_oauth2: Add provisions for dynamically adding simple scopes This lets additional modules define what scopes they might add to the userinfo endpoint, or other things.
author Kim Alvefur <zash@zash.se>
date Thu, 01 Jun 2023 18:16:13 +0200
parents 1bcf755c7bae
children efe9e741f222
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
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
116 - `client_name` and `client_uri` **MUST** be present.
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
117 - `client_uri` **MUST** be a `https://` URL.
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
118 - `redirect_uris` **MUST** contain at least one valid URI.
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
119 - If `application_type` equals `web` (or is not included) then all
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
120 `redirect_uris` **MUST** be `https://` URIs and **MUST** use the
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
121 same hostname part as the `client_uri`.
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
122 - If `application_type` equals `native` then all `redirect_uris`
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
123 **MUST** match one of:
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
124 - Loopback `http://` URI, e.g. `https://127.0.0.1:8080/`
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
125 - Application-specific scheme, e.g. `com.example.app:/`
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
126 - The special OOB URI `urn:ietf:wg:oauth:2.0:oob`
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
127 - Informative URIs such as policy and terms of service **MUST** use
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
128 the same scheme (i.e. `https://`) and hostname as the `client_uri`.
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
129
5494
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
130 #### Registration Example
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
131
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
132 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
133 client to an endpoint:
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
134
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
135 ``` bash
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
136 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
137 -H Content-Type:application/json \
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
138 -H Accept:application/json \
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
139 --data '
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
140 {
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
141 "client_name" : "My Application",
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
142 "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
143 "redirect_uris" : [
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
144 "https://app.example.com/redirect"
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
145 ]
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
146 }
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
147 '
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
148 ```
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
149
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
150 ### Supported flows
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
151
5197
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
152 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
153 `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
154
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
155 ```lua
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
156 allowed_oauth2_grant_types = {
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
157 "authorization_code"; -- authorization code grant
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
158 "password"; -- resource owner password grant
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
159 }
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
160
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
161 allowed_oauth2_response_types = {
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
162 "code"; -- authorization code flow
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
163 -- "token"; -- implicit flow disabled by default
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
164 }
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
165 ```
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
166
5383
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange
Kim Alvefur <zash@zash.se>
parents: 5328
diff changeset
167 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
168 made required:
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange
Kim Alvefur <zash@zash.se>
parents: 5328
diff changeset
169
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange
Kim Alvefur <zash@zash.se>
parents: 5328
diff changeset
170 ```lua
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange
Kim Alvefur <zash@zash.se>
parents: 5328
diff changeset
171 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
172 ```
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange
Kim Alvefur <zash@zash.se>
parents: 5328
diff changeset
173
5384
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
174 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
175
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
176 ```lua
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
177 allowed_oauth2_code_challenge_methods = {
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
178 "plain"; -- the insecure one
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
179 "S256";
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
180 }
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
181 ```
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
182
5408
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata
Kim Alvefur <zash@zash.se>
parents: 5384
diff changeset
183 ### Policy documents
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata
Kim Alvefur <zash@zash.se>
parents: 5384
diff changeset
184
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata
Kim Alvefur <zash@zash.se>
parents: 5384
diff changeset
185 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
186 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
187
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata
Kim Alvefur <zash@zash.se>
parents: 5384
diff changeset
188 ```lua
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata
Kim Alvefur <zash@zash.se>
parents: 5384
diff changeset
189 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
190 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
191 ```
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata
Kim Alvefur <zash@zash.se>
parents: 5384
diff changeset
192
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
193 ## Deployment notes
3903
cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only)
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
194
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
195 ### Access management
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
196
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
197 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
198 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
199 previously authorized). It is recommended to join this module with
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
200 mod_client_management to provide such access. However, at the time of writing,
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
201 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
202 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
203
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
204 ### Scopes
3903
cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only)
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
205
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
206 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
207
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
208 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
209 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
210 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
211 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
212 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
213 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
214 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
215 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
216
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role
Kim Alvefur <zash@zash.se>
parents: 5465
diff changeset
217 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
218 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
219
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role
Kim Alvefur <zash@zash.se>
parents: 5465
diff changeset
220 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
221
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role
Kim Alvefur <zash@zash.se>
parents: 5465
diff changeset
222 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
223 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
224
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
225 ## Compatibility
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
226
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
227 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
228 earlier.