prosody-modules: mod_http_oauth2/README.markdown annotate

annotate mod_http_oauth2/README.markdown @ 5516:f25df3af02c1

mod_client_management: Include client software version number in listing Should you ever wish to revoke a client by version number, e.g. for security reasons affecting certain versions, then it would be good to at the very least see which version is used. Also includes the OAuth2 software ID, an optional unique identifier that should be the same for all installations of a particular software.

author	Kim Alvefur <zash@zash.se>
date	Sat, 03 Jun 2023 19:21:39 +0200
parents	56803acfa638
children	67448e677706

rev	line source
3903 cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only) Matthew Wild <mwild1@gmail.com> parents: diff changeset	1 ---
cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only) Matthew Wild <mwild1@gmail.com> parents: diff changeset	2 labels:
cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only) Matthew Wild <mwild1@gmail.com> parents: diff changeset	3 - Stage-Alpha
cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only) Matthew Wild <mwild1@gmail.com> parents: diff changeset	4 summary: 'OAuth2 API'
5212 3235b8bd1e55 mod_http_oauth2: Include html templates in package for plugin installer Kim Alvefur <zash@zash.se> parents: 5197 diff changeset	5 rockspec:
3235b8bd1e55 mod_http_oauth2: Include html templates in package for plugin installer Kim Alvefur <zash@zash.se> parents: 5197 diff changeset	6 build:
3235b8bd1e55 mod_http_oauth2: Include html templates in package for plugin installer Kim Alvefur <zash@zash.se> parents: 5197 diff changeset	7 copy_directories:
3235b8bd1e55 mod_http_oauth2: Include html templates in package for plugin installer Kim Alvefur <zash@zash.se> parents: 5197 diff changeset	8 - html
3903 cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only) Matthew Wild <mwild1@gmail.com> parents: diff changeset	9 ...
cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only) Matthew Wild <mwild1@gmail.com> parents: diff changeset	10
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	11 ## Introduction
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	12
5315 8501baa7ef3f mod_http_oauth2/README: Link to OAuth and OIDC sites Kim Alvefur <zash@zash.se> parents: 5313 diff changeset	13 This module implements an [OAuth2](https://oauth.net/2/)/[OpenID Connect
8501baa7ef3f mod_http_oauth2/README: Link to OAuth and OIDC sites Kim Alvefur <zash@zash.se> parents: 5313 diff changeset	14 (OIDC)](https://openid.net/connect/) provider HTTP frontend on top of
8501baa7ef3f mod_http_oauth2/README: Link to OAuth and OIDC sites Kim Alvefur <zash@zash.se> parents: 5313 diff changeset	15 Prosody's usual internal authentication backend.
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	16
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	17 OAuth and OIDC are web standards that allow you to provide clients and
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	18 third-party applications limited access to your account, without sharing your
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	19 password with them.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	20
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	21 With this module deployed, software that supports OAuth can obtain "access
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	22 tokens" from Prosody which can then be used to connect to XMPP accounts using
5316 4fc3277a914d mod_http_oauth2/README: Link to mod_rest Kim Alvefur <zash@zash.se> parents: 5315 diff changeset	23 the 'OAUTHBEARER' SASL mechanism or via non-XMPP interfaces such as [mod_rest].
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	24
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	25 Although this module has been around for some time, it has recently been
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	26 significantly extended and largely rewritten to support OAuth/OIDC more fully.
3903 cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only) Matthew Wild <mwild1@gmail.com> parents: diff changeset	27
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	28 As of April 2023, it should be considered alpha stage. It works, we have
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	29 tested it, but it has not yet seen wider review, testing and deployment. At
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	30 this stage we recommend it for experimental and test deployments only. For
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	31 specific information, see the [deployment notes section](#deployment-notes)
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	32 below.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	33
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	34 Known client implementations:
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	35
5328 dd8616e68cb3 mod_http_oauth2/README: Add rest.sh to known implementations Kim Alvefur <zash@zash.se> parents: 5316 diff changeset	36 - [example shell script for mod_rest](https://hg.prosody.im/prosody-modules/file/tip/mod_rest/example/rest.sh)
dd8616e68cb3 mod_http_oauth2/README: Add rest.sh to known implementations Kim Alvefur <zash@zash.se> parents: 5316 diff changeset	37 - (we need you!)
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	38
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	39 Support for OAUTHBEARER has been added to the Lua XMPP library, [verse](https://code.matthewwild.co.uk/verse).
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	40 If you know of additional implementations, or are motivated to work on one,
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	41 please let us know! We'd be happy to help (e.g. by providing a test server).
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	42
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	43 ## Standards support
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	44
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	45 Notable supported standards:
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	46
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	47 - [RFC 6749: The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749)
5410 644b2f2b9b52 mod_http_oauth2: Link to RFC 7009: OAuth 2.0 Token Revocation Kim Alvefur <zash@zash.se> parents: 5408 diff changeset	48 - [RFC 7009: OAuth 2.0 Token Revocation](https://www.rfc-editor.org/rfc/rfc7009)
5464 2a11f590c5c8 mod_http_oauth2: Split long list line in README Kim Alvefur <zash@zash.se> parents: 5416 diff changeset	49 - [RFC 7591: OAuth 2.0 Dynamic Client Registration](https://www.rfc-editor.org/rfc/rfc7591.html)
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	50 - [RFC 7628: A Set of Simple Authentication and Security Layer (SASL) Mechanisms for OAuth](https://www.rfc-editor.org/rfc/rfc7628)
5383 df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange Kim Alvefur <zash@zash.se> parents: 5328 diff changeset	51 - [RFC 7636: Proof Key for Code Exchange by OAuth Public Clients](https://www.rfc-editor.org/rfc/rfc7636)
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	52 - [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)
5465 66e13e79928b mod_http_oauth2: Note about partial OpenID Discovery implementation Kim Alvefur <zash@zash.se> parents: 5464 diff changeset	53 - [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) (_partial, e.g. missing JWKS_)
5464 2a11f590c5c8 mod_http_oauth2: Split long list line in README Kim Alvefur <zash@zash.se> parents: 5416 diff changeset	54 - [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html)
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	55
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	56 ## Configuration
3903 cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only) Matthew Wild <mwild1@gmail.com> parents: diff changeset	57
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	58 ### Interface
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	59
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	60 The module presents a web page to users to allow them to authenticate when
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	61 a client requests access. Built-in pages are provided, but you may also theme
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	62 or entirely override them.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	63
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	64 This module honours the 'site_name' configuration option that is also used by
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	65 a number of other modules:
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	66
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	67 ```lua
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	68 site_name = "My XMPP Server"
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	69 ```
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	70
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	71 To provide custom templates, specify the path to the template directory:
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	72
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	73 ```lua
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	74 oauth2_template_path = "/etc/prosody/custom-oauth2-templates"
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	75 ```
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	76
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	77 Some templates support additional variables, that can be provided by the
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	78 'oauth2_template_style' option:
3903 cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only) Matthew Wild <mwild1@gmail.com> parents: diff changeset	79
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	80 ```lua
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	81 oauth2_template_style = {
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	82 background_colour = "#ffffff";
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	83 }
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	84 ```
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	85
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	86 ### Token parameters
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	87
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	88 The following options configure the lifetime of tokens issued by the module.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	89 The defaults are recommended.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	90
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	91 ```lua
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	92 oauth2_access_token_ttl = 86400 -- 24 hours
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	93 oauth2_refresh_token_ttl = nil -- unlimited unless revoked by the user
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	94 ```
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	95
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	96 ### Dynamic client registration
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	97
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	98 To allow users to connect any compatible software, you should enable dynamic
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	99 client registration.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	100
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	101 Dynamic client registration can be enabled by configuring a JWT key. Algorithm
5416 2393dbae51ed mod_http_oauth2: Add option for specifying TTL of registered clients Kim Alvefur <zash@zash.se> parents: 5410 diff changeset	102 defaults to HS256 lifetime defaults to forever.
5197 164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	103
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	104 ```lua
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	105 oauth2_registration_key = "securely generated JWT key here"
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	106 oauth2_registration_algorithm = "HS256"
5416 2393dbae51ed mod_http_oauth2: Add option for specifying TTL of registered clients Kim Alvefur <zash@zash.se> parents: 5410 diff changeset	107 oauth2_registration_ttl = nil -- unlimited by default
5197 164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	108 ```
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	109
5493 cae3bb3dd45f mod_http_oauth2: Document client registration requirements Kim Alvefur <zash@zash.se> parents: 5467 diff changeset	110 Registering a client is described in
cae3bb3dd45f mod_http_oauth2: Document client registration requirements Kim Alvefur <zash@zash.se> parents: 5467 diff changeset	111 [RFC7591](https://www.rfc-editor.org/rfc/rfc7591.html).
cae3bb3dd45f mod_http_oauth2: Document client registration requirements Kim Alvefur <zash@zash.se> parents: 5467 diff changeset	112
cae3bb3dd45f mod_http_oauth2: Document client registration requirements Kim Alvefur <zash@zash.se> parents: 5467 diff changeset	113 In addition to the requirements in the RFC, the following requirements
cae3bb3dd45f mod_http_oauth2: Document client registration requirements Kim Alvefur <zash@zash.se> parents: 5467 diff changeset	114 are enforced:
cae3bb3dd45f mod_http_oauth2: Document client registration requirements Kim Alvefur <zash@zash.se> parents: 5467 diff changeset	115
5506 37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	116 `client_name`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	117 : MUST be present, is shown to users in consent screen.
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	118
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	119 `client_uri`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	120 : MUST be present and MUST be a `https://` URL.
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	121
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	122 `redirect_uris`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	123
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	124 : MUST contain at least one valid URI. Different rules apply
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	125 depending on the value of `application_type`:
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	126
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	127 `web`
5507 209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements Kim Alvefur <zash@zash.se> parents: 5506 diff changeset	128 : `redirect_uris` MUST be `https://` URIs and MUST use the
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements Kim Alvefur <zash@zash.se> parents: 5506 diff changeset	129 same hostname part as the `client_uri`.
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements Kim Alvefur <zash@zash.se> parents: 5506 diff changeset	130
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements Kim Alvefur <zash@zash.se> parents: 5506 diff changeset	131 `native`
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements Kim Alvefur <zash@zash.se> parents: 5506 diff changeset	132
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements Kim Alvefur <zash@zash.se> parents: 5506 diff changeset	133 : `redirect_uris` MUST match one of:
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements Kim Alvefur <zash@zash.se> parents: 5506 diff changeset	134
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements Kim Alvefur <zash@zash.se> parents: 5506 diff changeset	135 - Loopback HTTP URI, e.g. `http://127.0.0.1/` or
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements Kim Alvefur <zash@zash.se> parents: 5506 diff changeset	136 `http://[::1]`
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements Kim Alvefur <zash@zash.se> parents: 5506 diff changeset	137 - Application-specific scheme, e.g. `com.example.app:/`
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements Kim Alvefur <zash@zash.se> parents: 5506 diff changeset	138 - The special OOB URI `urn:ietf:wg:oauth:2.0:oob`
5506 37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	139
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	140 `application_type`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	141
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	142 : Optional, defaults to `web`. Determines further restrictions for
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	143 `redirect_uris`. The following values are supported:
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	144
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	145 `web` (default)
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	146 : For web clients.
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	147
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	148 `native`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	149 : For native e.g. desktop clients etc.
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	150
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	151 `tos_uri`, `policy_uri`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	152 : Informative URLs pointing to Terms of Service and Service Policy
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	153 document MUST use the same scheme (i.e. `https://`) and hostname
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	154 as the `client_uri`.
5493 cae3bb3dd45f mod_http_oauth2: Document client registration requirements Kim Alvefur <zash@zash.se> parents: 5467 diff changeset	155
5494 1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	156 #### Registration Example
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	157
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	158 In short registration works by POST-ing a JSON structure describing your
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	159 client to an endpoint:
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	160
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	161 ``` bash
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	162 curl -sSf https://xmpp.example.net/oauth2/register \
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	163 -H Content-Type:application/json \
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	164 -H Accept:application/json \
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	165 --data '
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	166 {
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	167 "client_name" : "My Application",
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	168 "client_uri" : "https://app.example.com/",
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	169 "redirect_uris" : [
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	170 "https://app.example.com/redirect"
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	171 ]
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	172 }
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	173 '
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	174 ```
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	175
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	176 ### Supported flows
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	177
5197 164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	178 Various flows can be disabled and enabled with
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	179 `allowed_oauth2_grant_types` and `allowed_oauth2_response_types`:
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	180
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	181 ```lua
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	182 allowed_oauth2_grant_types = {
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	183 "authorization_code"; -- authorization code grant
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	184 "password"; -- resource owner password grant
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	185 }
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	186
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	187 allowed_oauth2_response_types = {
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	188 "code"; -- authorization code flow
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	189 -- "token"; -- implicit flow disabled by default
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	190 }
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	191 ```
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	192
5383 df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange Kim Alvefur <zash@zash.se> parents: 5328 diff changeset	193 The [Proof Key for Code Exchange][RFC 7636] mitigation method can be
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange Kim Alvefur <zash@zash.se> parents: 5328 diff changeset	194 made required:
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange Kim Alvefur <zash@zash.se> parents: 5328 diff changeset	195
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange Kim Alvefur <zash@zash.se> parents: 5328 diff changeset	196 ```lua
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange Kim Alvefur <zash@zash.se> parents: 5328 diff changeset	197 oauth2_require_code_challenge = true
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange Kim Alvefur <zash@zash.se> parents: 5328 diff changeset	198 ```
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange Kim Alvefur <zash@zash.se> parents: 5328 diff changeset	199
5384 b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	200 Further, individual challenge methods can be enabled or disabled:
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	201
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	202 ```lua
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	203 allowed_oauth2_code_challenge_methods = {
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	204 "plain"; -- the insecure one
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	205 "S256";
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	206 }
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	207 ```
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	208
5408 3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata Kim Alvefur <zash@zash.se> parents: 5384 diff changeset	209 ### Policy documents
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata Kim Alvefur <zash@zash.se> parents: 5384 diff changeset	210
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata Kim Alvefur <zash@zash.se> parents: 5384 diff changeset	211 Links to Terms of Service and Service Policy documents can be advertised
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata Kim Alvefur <zash@zash.se> parents: 5384 diff changeset	212 for use by OAuth clients:
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata Kim Alvefur <zash@zash.se> parents: 5384 diff changeset	213
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata Kim Alvefur <zash@zash.se> parents: 5384 diff changeset	214 ```lua
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata Kim Alvefur <zash@zash.se> parents: 5384 diff changeset	215 oauth2_terms_url = "https://example.com/terms-of-service.html"
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata Kim Alvefur <zash@zash.se> parents: 5384 diff changeset	216 oauth2_policy_url = "https://example.com/service-policy.pdf"
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata Kim Alvefur <zash@zash.se> parents: 5384 diff changeset	217 ```
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata Kim Alvefur <zash@zash.se> parents: 5384 diff changeset	218
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	219 ## Deployment notes
3903 cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only) Matthew Wild <mwild1@gmail.com> parents: diff changeset	220
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	221 ### Access management
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	222
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	223 This module does not provide an interface for users to manage what they have
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	224 granted access to their account! (e.g. to view and revoke clients they have
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	225 previously authorized). It is recommended to join this module with
5508 56803acfa638 mod_http_oauth2: Linkify mod_client_management in README Kim Alvefur <zash@zash.se> parents: 5507 diff changeset	226 [mod_client_management] to provide such access. However, at the time of writing,
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	227 no XMPP clients currently support the protocol used by that module. We plan to
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	228 work on additional interfaces in the future.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	229
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	230 ### Scopes
3903 cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only) Matthew Wild <mwild1@gmail.com> parents: diff changeset	231
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	232 OAuth supports "scopes" as a way to grant clients limited access.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	233
5467 1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role Kim Alvefur <zash@zash.se> parents: 5465 diff changeset	234 There are currently no standard scopes defined for XMPP. This is
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role Kim Alvefur <zash@zash.se> parents: 5465 diff changeset	235 something that we intend to change, e.g. by definitions provided in a
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role Kim Alvefur <zash@zash.se> parents: 5465 diff changeset	236 future XEP. This means that clients you authorize currently have to
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role Kim Alvefur <zash@zash.se> parents: 5465 diff changeset	237 choose between unrestricted access to your account (including the
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role Kim Alvefur <zash@zash.se> parents: 5465 diff changeset	238 ability to change your password and lock you out!) and zero access. So,
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role Kim Alvefur <zash@zash.se> parents: 5465 diff changeset	239 for now, while using OAuth clients can prevent leaking your password to
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role Kim Alvefur <zash@zash.se> parents: 5465 diff changeset	240 them, it is not currently suitable for connecting untrusted clients to
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role Kim Alvefur <zash@zash.se> parents: 5465 diff changeset	241 your account.
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role Kim Alvefur <zash@zash.se> parents: 5465 diff changeset	242
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role Kim Alvefur <zash@zash.se> parents: 5465 diff changeset	243 As a first step, the `xmpp` scope is supported, and corresponds to
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role Kim Alvefur <zash@zash.se> parents: 5465 diff changeset	244 whatever permissions the user would have when logged in over XMPP.
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role Kim Alvefur <zash@zash.se> parents: 5465 diff changeset	245
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role Kim Alvefur <zash@zash.se> parents: 5465 diff changeset	246 Further, known Prosody roles can be used as scopes.
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role Kim Alvefur <zash@zash.se> parents: 5465 diff changeset	247
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role Kim Alvefur <zash@zash.se> parents: 5465 diff changeset	248 OpenID scopes such as `openid` and `profile` can be used for "Login
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role Kim Alvefur <zash@zash.se> parents: 5465 diff changeset	249 with XMPP" without granting access to more than limited profile details.
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	250
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	251 ## Compatibility
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	252
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	253 Requires Prosody trunk (April 2023), not compatible with Prosody 0.12 or
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	254 earlier.

Mercurial > prosody-modules

annotate mod_http_oauth2/README.markdown @ 5516:f25df3af02c1