prosody-modules
default
mod_http_oauth2/README.md

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

Software / code / prosody-modules

Annotate

mod_http_oauth2/README.md @ 6261:8c9eb4b6d02f draft default tip

Merge updates
author Trần H. Trung <xmpp:trần.h.trung@trung.fun>
date Sun, 18 May 2025 20:52:00 +0700
parent 6245:ea58d2893afb
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
5667
23f336cec200 mod_http_oauth2: Tweak wording in README to point out that this is an AS
Kim Alvefur <zash@zash.se>
parents: 5665
diff changeset
14 (OIDC)](https://openid.net/connect/) Authorization Server on top of
5315
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)
5703
b43c989fb69c mod_http_oauth2: Implement introspection endpoint
Kim Alvefur <zash@zash.se>
parents: 5667
diff changeset
54 - [RFC 7662: OAuth 2.0 Token Introspection](https://www.rfc-editor.org/rfc/rfc7662)
5596
7040d0772758 mod_http_oauth2: Implement RFC 8628 Device Authorization Grant
Kim Alvefur <zash@zash.se>
parents: 5592
diff changeset
55 - [RFC 8628: OAuth 2.0 Device Authorization Grant](https://www.rfc-editor.org/rfc/rfc8628)
5592
59acf7f540c1 mod_http_oauth2: Mention support for RFC 9207
Kim Alvefur <zash@zash.se>
parents: 5562
diff changeset
56 - [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
57 - [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
58 - [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) (_partial, e.g. missing JWKS_)
5652
f3b7e05c74a9 mod_http_oauth2: Remove duplicated word in README introduced in 734788d8bfc3
Kim Alvefur <zash@zash.se>
parents: 5624
diff changeset
59 - [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
60
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
61 ## Configuration
3903
cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only)
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
62
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
63 ### Interface
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
64
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
65 The module presents a web page to users to allow them to authenticate when
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
66 a client requests access. Built-in pages are provided, but you may also theme
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
67 or entirely override them.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
68
5545
fcef6263acdb mod_http_oauth2: Use code spans for some config options in README
Kim Alvefur <zash@zash.se>
parents: 5521
diff changeset
69 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
70 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
71
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
72 ```lua
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
73 site_name = "My XMPP Server"
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 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
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
76 To provide custom templates, specify the path to the template directory:
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
77
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
78 ```lua
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
79 oauth2_template_path = "/etc/prosody/custom-oauth2-templates"
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 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
5547
d4a2997deae9 mod_http_oauth2: Make CSP configurable
Kim Alvefur <zash@zash.se>
parents: 5546
diff changeset
82 If you know what features your templates use use you can adjust the
d4a2997deae9 mod_http_oauth2: Make CSP configurable
Kim Alvefur <zash@zash.se>
parents: 5546
diff changeset
83 `Content-Security-Policy` header to only allow what is needed:
d4a2997deae9 mod_http_oauth2: Make CSP configurable
Kim Alvefur <zash@zash.se>
parents: 5546
diff changeset
84
d4a2997deae9 mod_http_oauth2: Make CSP configurable
Kim Alvefur <zash@zash.se>
parents: 5546
diff changeset
85 ```lua
d4a2997deae9 mod_http_oauth2: Make CSP configurable
Kim Alvefur <zash@zash.se>
parents: 5546
diff changeset
86 oauth2_security_policy = "default-src 'self'" -- this is the default
d4a2997deae9 mod_http_oauth2: Make CSP configurable
Kim Alvefur <zash@zash.se>
parents: 5546
diff changeset
87 ```
d4a2997deae9 mod_http_oauth2: Make CSP configurable
Kim Alvefur <zash@zash.se>
parents: 5546
diff changeset
88
6240
ab14e7ecb82f mod_http_oauth2: Allow JIDs as username for password grant
magicfelix <felix@felix-zauberer.de>
parents: 6003
diff changeset
89 For the Resource Owner Password Grant the `username` is expected to be the only
ab14e7ecb82f mod_http_oauth2: Allow JIDs as username for password grant
magicfelix <felix@felix-zauberer.de>
parents: 6003
diff changeset
90 localpart by default. If the OAuth client includes the domainpart in the
ab14e7ecb82f mod_http_oauth2: Allow JIDs as username for password grant
magicfelix <felix@felix-zauberer.de>
parents: 6003
diff changeset
91 `username` it submits (e.g. user@example.org instead of just user), set this to
ab14e7ecb82f mod_http_oauth2: Allow JIDs as username for password grant
magicfelix <felix@felix-zauberer.de>
parents: 6003
diff changeset
92 `true`. Note that this requires all clients to follow this format.
ab14e7ecb82f mod_http_oauth2: Allow JIDs as username for password grant
magicfelix <felix@felix-zauberer.de>
parents: 6003
diff changeset
93
ab14e7ecb82f mod_http_oauth2: Allow JIDs as username for password grant
magicfelix <felix@felix-zauberer.de>
parents: 6003
diff changeset
94 ```lua
ab14e7ecb82f mod_http_oauth2: Allow JIDs as username for password grant
magicfelix <felix@felix-zauberer.de>
parents: 6003
diff changeset
95 oauth2_expect_username_jid = false
ab14e7ecb82f mod_http_oauth2: Allow JIDs as username for password grant
magicfelix <felix@felix-zauberer.de>
parents: 6003
diff changeset
96 ```
ab14e7ecb82f mod_http_oauth2: Allow JIDs as username for password grant
magicfelix <felix@felix-zauberer.de>
parents: 6003
diff changeset
97
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
98 ### Token parameters
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
99
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
100 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
101 The defaults are recommended.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
102
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
103 ```lua
5624
d8622797e315 mod_http_oauth2: Shorten default token validity periods
Kim Alvefur <zash@zash.se>
parents: 5622
diff changeset
104 oauth2_access_token_ttl = 3600 -- one hour
d8622797e315 mod_http_oauth2: Shorten default token validity periods
Kim Alvefur <zash@zash.se>
parents: 5622
diff changeset
105 oauth2_refresh_token_ttl = 604800 -- one week
5313
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
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
108 ### Dynamic client registration
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
109
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
110 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
111 client registration.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
112
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
113 Dynamic client registration can be enabled by configuring a JWT key. Algorithm
5882
761142ee0ff2 mod_http_oauth2: Reflect changes to defaults etc
Kim Alvefur <zash@zash.se>
parents: 5739
diff changeset
114 defaults to *HS256*, lifetime defaults to forever.
5197
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4923
diff changeset
115
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4923
diff changeset
116 ```lua
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4923
diff changeset
117 oauth2_registration_key = "securely generated JWT key here"
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4923
diff changeset
118 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
119 oauth2_registration_ttl = nil -- unlimited by default
5197
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4923
diff changeset
120 ```
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4923
diff changeset
121
5493
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
122 Registering a client is described in
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
123 [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
124
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
125 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
126 are enforced:
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
127
5506
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
128 `client_name`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
129 : **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
130
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
131 `client_uri`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
132 : **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
133
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
134 `redirect_uris`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
135
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
136 : **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
137 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
138
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
139 `application_type`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
140
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
141 : 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
142 `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
143
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
144 `web` *(default)*
5562
734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements
Kim Alvefur <zash@zash.se>
parents: 5561
diff changeset
145 : 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
146 `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
147 `client_uri`.
734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements
Kim Alvefur <zash@zash.se>
parents: 5561
diff changeset
148
734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements
Kim Alvefur <zash@zash.se>
parents: 5561
diff changeset
149 `native`
734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements
Kim Alvefur <zash@zash.se>
parents: 5561
diff changeset
150 : 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
151 match one of:
734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements
Kim Alvefur <zash@zash.se>
parents: 5561
diff changeset
152
734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements
Kim Alvefur <zash@zash.se>
parents: 5561
diff changeset
153 - 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
154 `http://[::1]`
734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements
Kim Alvefur <zash@zash.se>
parents: 5561
diff changeset
155 - 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
156 - 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
157
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
158 `tos_uri`, `policy_uri`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements
Kim Alvefur <zash@zash.se>
parents: 5505
diff changeset
159 : 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
160 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
161 as the `client_uri`.
5493
cae3bb3dd45f mod_http_oauth2: Document client registration requirements
Kim Alvefur <zash@zash.se>
parents: 5467
diff changeset
162
5561
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
163 #### Registration Examples
5494
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
164
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
165 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
166 client to an endpoint:
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
167
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
168 ``` bash
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
169 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
170 -H Content-Type:application/json \
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
171 -H Accept:application/json \
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
172 --data '
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
173 {
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
174 "client_name" : "My Application",
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
175 "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
176 "redirect_uris" : [
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
177 "https://app.example.com/redirect"
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
178 ]
1bcf755c7bae mod_http_oauth2: Add an example of client registration
Kim Alvefur <zash@zash.se>
parents: 5493
diff changeset
179 }
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
5561
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
183 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
184
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
185 ``` bash
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
186 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
187 -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
188 -H Accept:application/json \
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
189 --data '
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
190 {
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
191 "application_type" : "native",
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
192 "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
193 "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
194 "contacts" : [
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
195 "support@example.org"
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
196 ],
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
197 "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
198 "redirect_uris" : [
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
199 "http://localhost:8080/redirect",
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
200 "org.example.app:/redirect"
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
201 ],
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
202 "scope" : "xmpp",
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
203 "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
204 "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
205 "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
206 }
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example
Kim Alvefur <zash@zash.se>
parents: 5547
diff changeset
207 '
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
5313
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
210 ### Supported flows
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status
Matthew Wild <mwild1@gmail.com>
parents: 5212
diff changeset
211
5521
ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults
Kim Alvefur <zash@zash.se>
parents: 5520
diff changeset
212 - Authorization Code grant, optionally with Proof Key for Code Exchange
5620
a9682cad0e67 mod_http_oauth2: Mention Device flow in list of flows in README
Kim Alvefur <zash@zash.se>
parents: 5596
diff changeset
213 - Device Authorization Grant
5882
761142ee0ff2 mod_http_oauth2: Reflect changes to defaults etc
Kim Alvefur <zash@zash.se>
parents: 5739
diff changeset
214 - Resource owner password grant *(disabled by default)*
5521
ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults
Kim Alvefur <zash@zash.se>
parents: 5520
diff changeset
215 - 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
216 - Refresh Token grants
ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults
Kim Alvefur <zash@zash.se>
parents: 5520
diff changeset
217
5197
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4923
diff changeset
218 Various flows can be disabled and enabled with
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4923
diff changeset
219 `allowed_oauth2_grant_types` and `allowed_oauth2_response_types`:
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4923
diff changeset
220
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4923
diff changeset
221 ```lua
5521
ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults
Kim Alvefur <zash@zash.se>
parents: 5520
diff changeset
222 -- These examples reflect the defaults
5197
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4923
diff changeset
223 allowed_oauth2_grant_types = {
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4923
diff changeset
224 "authorization_code"; -- authorization code grant
5621
7565298aa197 mod_http_oauth2: Allow a shorter form of the device grant in config
Kim Alvefur <zash@zash.se>
parents: 5620
diff changeset
225 "device_code";
5882
761142ee0ff2 mod_http_oauth2: Reflect changes to defaults etc
Kim Alvefur <zash@zash.se>
parents: 5739
diff changeset
226 -- "password"; -- resource owner password grant disabled by default
5197
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4923
diff changeset
227 }
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4923
diff changeset
228
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4923
diff changeset
229 allowed_oauth2_response_types = {
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4923
diff changeset
230 "code"; -- authorization code flow
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4923
diff changeset
231 -- "token"; -- implicit flow disabled by default
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4923
diff changeset
232 }
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4923
diff changeset
233 ```
164a9875935b mod_http_oauth2/README: Document config options
Kim Alvefur <zash@zash.se>
parents: 4923
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
5739
426c42c11f89 mod_http_oauth2: Make defaults more secure
Kim Alvefur <zash@zash.se>
parents: 5703
diff changeset
236 required by default but can be made optional:
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
5739
426c42c11f89 mod_http_oauth2: Make defaults more secure
Kim Alvefur <zash@zash.se>
parents: 5703
diff changeset
239 oauth2_require_code_challenge = false -- default is true
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 = {
5739
426c42c11f89 mod_http_oauth2: Make defaults more secure
Kim Alvefur <zash@zash.se>
parents: 5703
diff changeset
247 -- "plain"; -- insecure but backwards-compatible
5384
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.