prosody-modules: mod_http_oauth2/README.markdown annotate

annotate mod_http_oauth2/README.markdown @ 5546:ae20da6d377d

mod_http_oauth2: Link to RFC 7628 in README Links are good.

author	Kim Alvefur <zash@zash.se>
date	Sun, 11 Jun 2023 14:03:27 +0200
parents	fcef6263acdb
children	d4a2997deae9

rev	line source
3903 cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only) Matthew Wild <mwild1@gmail.com> parents: diff changeset	1 ---
cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only) Matthew Wild <mwild1@gmail.com> parents: diff changeset	2 labels:
cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only) Matthew Wild <mwild1@gmail.com> parents: diff changeset	3 - Stage-Alpha
5212 3235b8bd1e55 mod_http_oauth2: Include html templates in package for plugin installer Kim Alvefur <zash@zash.se> parents: 5197 diff changeset	4 rockspec:
3235b8bd1e55 mod_http_oauth2: Include html templates in package for plugin installer Kim Alvefur <zash@zash.se> parents: 5197 diff changeset	5 build:
3235b8bd1e55 mod_http_oauth2: Include html templates in package for plugin installer Kim Alvefur <zash@zash.se> parents: 5197 diff changeset	6 copy_directories:
3235b8bd1e55 mod_http_oauth2: Include html templates in package for plugin installer Kim Alvefur <zash@zash.se> parents: 5197 diff changeset	7 - html
5520 67448e677706 mod_http_oauth2/README: Expand summary to include OAuth 2.0 role Kim Alvefur <zash@zash.se> parents: 5508 diff changeset	8 summary: OAuth 2.0 Authorization Server API
67448e677706 mod_http_oauth2/README: Expand summary to include OAuth 2.0 role Kim Alvefur <zash@zash.se> parents: 5508 diff changeset	9 ---
3903 cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only) Matthew Wild <mwild1@gmail.com> parents: diff changeset	10
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	11 ## Introduction
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	12
5315 8501baa7ef3f mod_http_oauth2/README: Link to OAuth and OIDC sites Kim Alvefur <zash@zash.se> parents: 5313 diff changeset	13 This module implements an [OAuth2](https://oauth.net/2/)/[OpenID Connect
8501baa7ef3f mod_http_oauth2/README: Link to OAuth and OIDC sites Kim Alvefur <zash@zash.se> parents: 5313 diff changeset	14 (OIDC)](https://openid.net/connect/) provider HTTP frontend on top of
8501baa7ef3f mod_http_oauth2/README: Link to OAuth and OIDC sites Kim Alvefur <zash@zash.se> parents: 5313 diff changeset	15 Prosody's usual internal authentication backend.
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	16
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	17 OAuth and OIDC are web standards that allow you to provide clients and
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	18 third-party applications limited access to your account, without sharing your
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	19 password with them.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	20
5546 ae20da6d377d mod_http_oauth2: Link to RFC 7628 in README Kim Alvefur <zash@zash.se> parents: 5545 diff changeset	21 With this module deployed, software that supports OAuth can obtain
ae20da6d377d mod_http_oauth2: Link to RFC 7628 in README Kim Alvefur <zash@zash.se> parents: 5545 diff changeset	22 "access tokens" from Prosody which can then be used to connect to XMPP
ae20da6d377d mod_http_oauth2: Link to RFC 7628 in README Kim Alvefur <zash@zash.se> parents: 5545 diff changeset	23 accounts using the [OAUTHBEARER SASL mechanism][rfc7628] or via non-XMPP
ae20da6d377d mod_http_oauth2: Link to RFC 7628 in README Kim Alvefur <zash@zash.se> parents: 5545 diff changeset	24 interfaces such as [mod_rest].
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	25
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	26 Although this module has been around for some time, it has recently been
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	27 significantly extended and largely rewritten to support OAuth/OIDC more fully.
3903 cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only) Matthew Wild <mwild1@gmail.com> parents: diff changeset	28
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	29 As of April 2023, it should be considered alpha stage. It works, we have
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	30 tested it, but it has not yet seen wider review, testing and deployment. At
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	31 this stage we recommend it for experimental and test deployments only. For
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	32 specific information, see the [deployment notes section](#deployment-notes)
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	33 below.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	34
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	35 Known client implementations:
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	36
5328 dd8616e68cb3 mod_http_oauth2/README: Add rest.sh to known implementations Kim Alvefur <zash@zash.se> parents: 5316 diff changeset	37 - [example shell script for mod_rest](https://hg.prosody.im/prosody-modules/file/tip/mod_rest/example/rest.sh)
dd8616e68cb3 mod_http_oauth2/README: Add rest.sh to known implementations Kim Alvefur <zash@zash.se> parents: 5316 diff changeset	38 - (we need you!)
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	39
5546 ae20da6d377d mod_http_oauth2: Link to RFC 7628 in README Kim Alvefur <zash@zash.se> parents: 5545 diff changeset	40 Support for [OAUTHBEARER][rfc7628] has been added to the Lua XMPP
ae20da6d377d mod_http_oauth2: Link to RFC 7628 in README Kim Alvefur <zash@zash.se> parents: 5545 diff changeset	41 library, [verse](https://code.matthewwild.co.uk/verse). If you know of
ae20da6d377d mod_http_oauth2: Link to RFC 7628 in README Kim Alvefur <zash@zash.se> parents: 5545 diff changeset	42 additional implementations, or are motivated to work on one, please let
ae20da6d377d mod_http_oauth2: Link to RFC 7628 in README Kim Alvefur <zash@zash.se> parents: 5545 diff changeset	43 us know! We'd be happy to help (e.g. by providing a test server).
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	44
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	45 ## Standards support
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	46
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	47 Notable supported standards:
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	48
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	49 - [RFC 6749: The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749)
5410 644b2f2b9b52 mod_http_oauth2: Link to RFC 7009: OAuth 2.0 Token Revocation Kim Alvefur <zash@zash.se> parents: 5408 diff changeset	50 - [RFC 7009: OAuth 2.0 Token Revocation](https://www.rfc-editor.org/rfc/rfc7009)
5464 2a11f590c5c8 mod_http_oauth2: Split long list line in README Kim Alvefur <zash@zash.se> parents: 5416 diff changeset	51 - [RFC 7591: OAuth 2.0 Dynamic Client Registration](https://www.rfc-editor.org/rfc/rfc7591.html)
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	52 - [RFC 7628: A Set of Simple Authentication and Security Layer (SASL) Mechanisms for OAuth](https://www.rfc-editor.org/rfc/rfc7628)
5383 df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange Kim Alvefur <zash@zash.se> parents: 5328 diff changeset	53 - [RFC 7636: Proof Key for Code Exchange by OAuth Public Clients](https://www.rfc-editor.org/rfc/rfc7636)
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	54 - [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	55 - [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	56 - [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	57
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	58 ## Configuration
3903 cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only) Matthew Wild <mwild1@gmail.com> parents: diff changeset	59
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	60 ### Interface
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	61
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	62 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	63 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	64 or entirely override them.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	65
5545 fcef6263acdb mod_http_oauth2: Use code spans for some config options in README Kim Alvefur <zash@zash.se> parents: 5521 diff changeset	66 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	67 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	68
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	69 ```lua
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	70 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	71 ```
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 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	74
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	75 ```lua
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	76 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	77 ```
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	78
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	79 Some templates support additional variables, that can be provided by the
5545 fcef6263acdb mod_http_oauth2: Use code spans for some config options in README Kim Alvefur <zash@zash.se> parents: 5521 diff changeset	80 `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	81
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	82 ```lua
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	83 oauth2_template_style = {
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	84 background_colour = "#ffffff";
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 ```
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 ### Token parameters
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	89
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	90 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	91 The defaults are recommended.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	92
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	93 ```lua
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	94 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	95 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	96 ```
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 ### Dynamic client registration
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 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	101 client registration.
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 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	104 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	105
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	106 ```lua
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	107 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	108 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	109 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	110 ```
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	111
5493 cae3bb3dd45f mod_http_oauth2: Document client registration requirements Kim Alvefur <zash@zash.se> parents: 5467 diff changeset	112 Registering a client is described in
cae3bb3dd45f mod_http_oauth2: Document client registration requirements Kim Alvefur <zash@zash.se> parents: 5467 diff changeset	113 [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	114
cae3bb3dd45f mod_http_oauth2: Document client registration requirements Kim Alvefur <zash@zash.se> parents: 5467 diff changeset	115 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	116 are enforced:
cae3bb3dd45f mod_http_oauth2: Document client registration requirements Kim Alvefur <zash@zash.se> parents: 5467 diff changeset	117
5506 37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	118 `client_name`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	119 : 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	120
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	121 `client_uri`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	122 : 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	123
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	124 `redirect_uris`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	125
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	126 : 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	127 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	128
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	129 `web`
5507 209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements Kim Alvefur <zash@zash.se> parents: 5506 diff changeset	130 : `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	131 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	132
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements Kim Alvefur <zash@zash.se> parents: 5506 diff changeset	133 `native`
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 : `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	136
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements Kim Alvefur <zash@zash.se> parents: 5506 diff changeset	137 - 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	138 `http://[::1]`
209299fd81e1 mod_http_oauth2: Fix messed up section about redirect_uris requirements Kim Alvefur <zash@zash.se> parents: 5506 diff changeset	139 - 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	140 - 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	141
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	142 `application_type`
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 : 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	145 `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	146
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	147 `web` (default)
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	148 : For web clients.
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	149
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	150 `native`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	151 : 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	152
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	153 `tos_uri`, `policy_uri`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	154 : 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	155 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	156 as the `client_uri`.
5493 cae3bb3dd45f mod_http_oauth2: Document client registration requirements Kim Alvefur <zash@zash.se> parents: 5467 diff changeset	157
5494 1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	158 #### Registration Example
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	159
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	160 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	161 client to an endpoint:
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	162
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	163 ``` bash
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	164 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	165 -H Content-Type:application/json \
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	166 -H Accept:application/json \
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	167 --data '
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	168 {
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	169 "client_name" : "My Application",
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	170 "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	171 "redirect_uris" : [
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	172 "https://app.example.com/redirect"
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 '
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	176 ```
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	177
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	178 ### Supported flows
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	179
5521 ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults Kim Alvefur <zash@zash.se> parents: 5520 diff changeset	180 - Authorization Code grant, optionally with Proof Key for Code Exchange
ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults Kim Alvefur <zash@zash.se> parents: 5520 diff changeset	181 - Resource owner password grant
ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults Kim Alvefur <zash@zash.se> parents: 5520 diff changeset	182 - 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	183 - Refresh Token grants
ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults Kim Alvefur <zash@zash.se> parents: 5520 diff changeset	184
5197 164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	185 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	186 `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	187
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	188 ```lua
5521 ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults Kim Alvefur <zash@zash.se> parents: 5520 diff changeset	189 -- These examples reflect the defaults
5197 164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	190 allowed_oauth2_grant_types = {
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	191 "authorization_code"; -- authorization code grant
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	192 "password"; -- resource owner password grant
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	193 }
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	194
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	195 allowed_oauth2_response_types = {
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	196 "code"; -- authorization code flow
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	197 -- "token"; -- implicit flow disabled by default
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	198 }
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	199 ```
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	200
5521 ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults Kim Alvefur <zash@zash.se> parents: 5520 diff changeset	201 The [Proof Key for Code Exchange][RFC 7636] mitigation method is
ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults Kim Alvefur <zash@zash.se> parents: 5520 diff changeset	202 optional by default but can be made required:
5383 df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange Kim Alvefur <zash@zash.se> parents: 5328 diff changeset	203
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange Kim Alvefur <zash@zash.se> parents: 5328 diff changeset	204 ```lua
5521 ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults Kim Alvefur <zash@zash.se> parents: 5520 diff changeset	205 oauth2_require_code_challenge = true -- default is false
5383 df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange Kim Alvefur <zash@zash.se> parents: 5328 diff changeset	206 ```
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange Kim Alvefur <zash@zash.se> parents: 5328 diff changeset	207
5384 b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	208 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	209
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	210 ```lua
5521 ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults Kim Alvefur <zash@zash.se> parents: 5520 diff changeset	211 -- These reflects the default
5384 b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	212 allowed_oauth2_code_challenge_methods = {
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	213 "plain"; -- the insecure one
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	214 "S256";
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	215 }
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	216 ```
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	217
5408 3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata Kim Alvefur <zash@zash.se> parents: 5384 diff changeset	218 ### Policy documents
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata Kim Alvefur <zash@zash.se> parents: 5384 diff changeset	219
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata Kim Alvefur <zash@zash.se> parents: 5384 diff changeset	220 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	221 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	222
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata Kim Alvefur <zash@zash.se> parents: 5384 diff changeset	223 ```lua
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata Kim Alvefur <zash@zash.se> parents: 5384 diff changeset	224 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	225 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	226 -- 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	227 ```
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata Kim Alvefur <zash@zash.se> parents: 5384 diff changeset	228
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	229 ## Deployment notes
3903 cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only) Matthew Wild <mwild1@gmail.com> parents: diff changeset	230
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	231 ### Access management
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	232
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	233 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	234 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	235 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	236 [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	237 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	238 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	239
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	240 ### Scopes
3903 cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only) Matthew Wild <mwild1@gmail.com> parents: diff changeset	241
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	242 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	243
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	244 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	245 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	246 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	247 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	248 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	249 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	250 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	251 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	252
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role Kim Alvefur <zash@zash.se> parents: 5465 diff changeset	253 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	254 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	255
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role Kim Alvefur <zash@zash.se> parents: 5465 diff changeset	256 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	257
1c78a97a1091 mod_http_oauth2: Add a special "xmpp" scope that grants the users' default role Kim Alvefur <zash@zash.se> parents: 5465 diff changeset	258 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	259 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	260
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	261 ## Compatibility
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	262
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	263 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	264 earlier.

Mercurial > prosody-modules

annotate mod_http_oauth2/README.markdown @ 5546:ae20da6d377d