Mercurial > prosody-modules

annotate mod_http_oauth2/README.markdown @ 5608:1893ae742f66

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_http_oauth2: Show errors on device flow user code entry page If the user enters the code incorrectly, having to click back to try again is no fun. Instead, show the error and the code entry form again.
author Kim Alvefur <zash@zash.se>
date Wed, 19 Jul 2023 13:05:47 +0200
parents 7040d0772758
children a9682cad0e67
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
5212
3235b8bd1e55 mod_http_oauth2: Include html templates in package for plugin installer
Kim Alvefur <zash@zash.se>
parents: 5197
diff changeset
4 rockspec:
3235b8bd1e55 mod_http_oauth2: Include html templates in package for plugin installer
Kim Alvefur <zash@zash.se>
parents: 5197
diff changeset
5 build:
3235b8bd1e55 mod_http_oauth2: Include html templates in package for plugin installer
Kim Alvefur <zash@zash.se>
parents: 5197
diff changeset
6 copy_directories:
3235b8bd1e55 mod_http_oauth2: Include html templates in package for plugin installer
Kim Alvefur <zash@zash.se>
parents: 5197
diff changeset
7 - html
5520
67448e677706 mod_http_oauth2/README: Expand summary to include OAuth 2.0 role
Kim Alvefur <zash@zash.se>
parents: 5508
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: 5508
diff changeset
9 ---
3903
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
5546
ae20da6d377d mod_http_oauth2: Link to RFC 7628 in README
Kim Alvefur <zash@zash.se>
parents: 5545
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: 5545
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: 5545
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: 5545
diff changeset
24 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
25
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
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: 5212
diff changeset
27 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
28
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
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: 5212
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: 5212
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: 5212
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: 5212
diff changeset
33 below.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
34
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
35 Known client implementations:
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
36
5328
dd8616e68cb3 mod_http_oauth2/README: Add rest.sh to known implementations
Kim Alvefur <zash@zash.se>
parents: 5316
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: 5316
diff changeset
38 - *(we need you!)*
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
39
5546
ae20da6d377d mod_http_oauth2: Link to RFC 7628 in README
Kim Alvefur <zash@zash.se>
parents: 5545
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: 5545
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: 5545
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: 5545
diff changeset
43 us know! We'd be happy to help (e.g. by providing a test server).
5313
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 ## Standards support
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 Notable supported standards:
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
48
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
49 - [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
50 - [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
51 - [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
52 - [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
53 - [RFC 7636: Proof Key for Code Exchange by OAuth Public Clients](https://www.rfc-editor.org/rfc/rfc7636)
5589
7040d0772758 mod_http_oauth2: Implement RFC 8628 Device Authorization Grant
Kim Alvefur <zash@zash.se>
parents: 5588
diff changeset
54 - [RFC 8628: OAuth 2.0 Device Authorization Grant](https://www.rfc-editor.org/rfc/rfc8628)
5588
59acf7f540c1 mod_http_oauth2: Mention support for RFC 9207
Kim Alvefur <zash@zash.se>
parents: 5562
diff changeset
55 - [RFC 9207: OAuth 2.0 Authorization Server Issuer Identification](https://www.rfc-editor.org/rfc/rfc9207.html)
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
56 - [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
57 - [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
58 - [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
59
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
60 ## Configuration
3903
cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only)
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
61
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
62 ### Interface
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 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
65 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
66 or entirely override them.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
67
5545
fcef6263acdb mod_http_oauth2: Use code spans for some config options in README
Kim Alvefur <zash@zash.se>
parents: 5521
diff changeset
68 This module honours the `site_name` configuration option that is also used by
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
69 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
70
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
71 ```lua
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
72 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
73 ```
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
74
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
75 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
76
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
77 ```lua
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
78 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
79 ```
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
80
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
81 Some templates support additional variables, that can be provided by the
5545
fcef6263acdb mod_http_oauth2: Use code spans for some config options in README
Kim Alvefur <zash@zash.se>
parents: 5521
diff changeset
82 `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
83
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
84 ```lua
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
85 oauth2_template_style = {
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
86 background_colour = "#ffffff";
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 ```
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
89
5547
d4a2997deae9 mod_http_oauth2: Make CSP configurable
Kim Alvefur <zash@zash.se>
parents: 5546
diff changeset
90 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: 5546
diff changeset
91 `Content-Security-Policy` header to only allow what is needed:
d4a2997deae9 mod_http_oauth2: Make CSP configurable
Kim Alvefur <zash@zash.se>
parents: 5546
diff changeset
92
d4a2997deae9 mod_http_oauth2: Make CSP configurable
Kim Alvefur <zash@zash.se>
parents: 5546
diff changeset
93 ```lua
d4a2997deae9 mod_http_oauth2: Make CSP configurable
Kim Alvefur <zash@zash.se>
parents: 5546
diff changeset
94 oauth2_security_policy = "default-src 'self'" -- this is the default
d4a2997deae9 mod_http_oauth2: Make CSP configurable
Kim Alvefur <zash@zash.se>
parents: 5546
diff changeset
95 ```
d4a2997deae9 mod_http_oauth2: Make CSP configurable
Kim Alvefur <zash@zash.se>
parents: 5546
diff changeset
96
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
97 ### Token parameters
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
98
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
99 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
100 The defaults are recommended.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
101
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
102 ```lua
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
103 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
104 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
105 ```
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
106
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
107 ### Dynamic client registration
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
108
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
109 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
110 client registration.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
111
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
112 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
113 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
114
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
115 ```lua
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
116 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
117 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
118 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
119 ```
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
120
5493
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
121 Registering a client is described in
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
122 [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
123
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
124 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
125 are enforced:
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
126
5506
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
127 `client_name`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
128 : **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
129
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
130 `client_uri`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
131 : **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
132
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
133 `redirect_uris`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
134
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
135 : **MUST** contain at least one valid URI. Different rules apply
5562
734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements
Kim Alvefur <zash@zash.se>
parents: 5561
diff changeset
136 depending on the value of `application_type`, see below.
5506
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
137
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
138 `application_type`
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 : 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
141 `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
142
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
143 `web` *(default)*
5562
734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements
Kim Alvefur <zash@zash.se>
parents: 5561
diff changeset
144 : 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: 5561
diff changeset
145 `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: 5561
diff changeset
146 `client_uri`.
734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements
Kim Alvefur <zash@zash.se>
parents: 5561
diff changeset
147
734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements
Kim Alvefur <zash@zash.se>
parents: 5561
diff changeset
148 `native`
5506
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
149
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
150 `native`
5562
734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements
Kim Alvefur <zash@zash.se>
parents: 5561
diff changeset
151
734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements
Kim Alvefur <zash@zash.se>
parents: 5561
diff changeset
152 : 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: 5561
diff changeset
153 match one of:
734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements
Kim Alvefur <zash@zash.se>
parents: 5561
diff changeset
154
734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements
Kim Alvefur <zash@zash.se>
parents: 5561
diff changeset
155 - 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: 5561
diff changeset
156 `http://[::1]`
734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements
Kim Alvefur <zash@zash.se>
parents: 5561
diff changeset
157 - Application-specific scheme, e.g. `com.example.app:/`
734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements
Kim Alvefur <zash@zash.se>
parents: 5561
diff changeset
158 - 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
159
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
160 `tos_uri`, `policy_uri`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
161 : 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
162 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
163 as the `client_uri`.
5493
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
164
5561
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
165 #### Registration Examples
5494
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 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
168 client to an endpoint:
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
169
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
170 ``` bash
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
171 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
172 -H Content-Type:application/json \
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
173 -H Accept:application/json \
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
174 --data '
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
175 {
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
176 "client_name" : "My Application",
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
177 "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
178 "redirect_uris" : [
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
179 "https://app.example.com/redirect"
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
180 ]
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
181 }
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
182 '
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
183 ```
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
184
5561
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
185 Another example with more fields:
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
186
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
187 ``` bash
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
188 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: 5547
diff changeset
189 -H Content-Type:application/json \
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
190 -H Accept:application/json \
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
191 --data '
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
192 {
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
193 "application_type" : "native",
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
194 "client_name" : "Desktop Chat App",
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
195 "client_uri" : "https://app.example.org/",
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
196 "contacts" : [
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
197 "support@example.org"
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
198 ],
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
199 "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: 5547
diff changeset
200 "redirect_uris" : [
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
201 "http://localhost:8080/redirect",
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
202 "org.example.app:/redirect"
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
203 ],
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
204 "scope" : "xmpp",
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
205 "software_id" : "32a0a8f3-4016-5478-905a-c373156eca73",
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
206 "software_version" : "3.4.1",
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
207 "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: 5547
diff changeset
208 }
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
209 '
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
210 ```
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
211
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
212 ### Supported flows
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
213
5521
ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults
Kim Alvefur <zash@zash.se>
parents: 5520
diff changeset
214 - Authorization Code grant, optionally with Proof Key for Code Exchange
ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults
Kim Alvefur <zash@zash.se>
parents: 5520
diff changeset
215 - Resource owner password grant
ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults
Kim Alvefur <zash@zash.se>
parents: 5520
diff changeset
216 - Implicit flow *(disabled by default)*
ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults
Kim Alvefur <zash@zash.se>
parents: 5520
diff changeset
217 - Refresh Token grants
ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults
Kim Alvefur <zash@zash.se>
parents: 5520
diff changeset
218
5197
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
219 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
220 `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
221
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
222 ```lua
5521
ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults
Kim Alvefur <zash@zash.se>
parents: 5520
diff changeset
223 -- These examples reflect the defaults
5197
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
224 allowed_oauth2_grant_types = {
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
225 "authorization_code"; -- authorization code grant
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
226 "password"; -- resource owner password grant
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
227 }
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
228
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
229 allowed_oauth2_response_types = {
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
230 "code"; -- authorization code flow
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
231 -- "token"; -- implicit flow disabled by default
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
232 }
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
233 ```
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4924
diff changeset
234
5521
ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults
Kim Alvefur <zash@zash.se>
parents: 5520
diff changeset
235 The [Proof Key for Code Exchange][RFC 7636] mitigation method is
ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults
Kim Alvefur <zash@zash.se>
parents: 5520
diff changeset
236 optional by default but can be made required:
5383
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange
Kim Alvefur <zash@zash.se>
parents: 5328
diff changeset
237
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange
Kim Alvefur <zash@zash.se>
parents: 5328
diff changeset
238 ```lua
5521
ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults
Kim Alvefur <zash@zash.se>
parents: 5520
diff changeset
239 oauth2_require_code_challenge = true -- default is false
5383
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange
Kim Alvefur <zash@zash.se>
parents: 5328
diff changeset
240 ```
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange
Kim Alvefur <zash@zash.se>
parents: 5328
diff changeset
241
5384
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
242 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
243
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
244 ```lua
5521
ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults
Kim Alvefur <zash@zash.se>
parents: 5520
diff changeset
245 -- These reflects the default
5384
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
246 allowed_oauth2_code_challenge_methods = {
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
247 "plain"; -- the insecure one
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
248 "S256";
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
249 }
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
250 ```
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods
Kim Alvefur <zash@zash.se>
parents: 5383
diff changeset
251
5408
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata
Kim Alvefur <zash@zash.se>
parents: 5384
diff changeset
252 ### Policy documents
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata
Kim Alvefur <zash@zash.se>
parents: 5384
diff changeset
253
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata
Kim Alvefur <zash@zash.se>
parents: 5384
diff changeset
254 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
255 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
256
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata
Kim Alvefur <zash@zash.se>
parents: 5384
diff changeset
257 ```lua
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata
Kim Alvefur <zash@zash.se>
parents: 5384
diff changeset
258 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
259 oauth2_policy_url = "https://example.com/service-policy.pdf"
5521
ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults
Kim Alvefur <zash@zash.se>
parents: 5520
diff changeset
260 -- These are unset by default
5408
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata
Kim Alvefur <zash@zash.se>
parents: 5384
diff changeset
261 ```
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata
Kim Alvefur <zash@zash.se>
parents: 5384
diff changeset
262
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
263 ## Deployment notes
3903
cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only)
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
264
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
265 ### Access management
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
266
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
267 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
268 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
269 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
270 [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
271 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
272 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
273
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
274 ### Scopes
3903
cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only)
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
275
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
276 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
277
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
278 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
279 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
280 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
281 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
282 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
283 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
284 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
285 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
286
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role
Kim Alvefur <zash@zash.se>
parents: 5465
diff changeset
287 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
288 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
289
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role
Kim Alvefur <zash@zash.se>
parents: 5465
diff changeset
290 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
291
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role
Kim Alvefur <zash@zash.se>
parents: 5465
diff changeset
292 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
293 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
294
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
295 ## Compatibility
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
296
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
297 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
298 earlier.