prosody-modules: mod_http_oauth2/README.markdown annotate

annotate mod_http_oauth2/README.markdown @ 5715:8488ebde5739

mod_http_oauth2: Skip consent screen if requested by client and same scopes already granted This follows the intent behind the OpenID Connect 'prompt' parameter when it does not include the 'consent' keyword, that is the client wishes to skip the consent screen. If the user has already granted the exact same scopes to the exact same client in the past, then one can assume that they may grant it again.

author	Kim Alvefur <zash@zash.se>
date	Tue, 14 Nov 2023 23:03:37 +0100
parents	b43c989fb69c
children	426c42c11f89

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
5644 23f336cec200 mod_http_oauth2: Tweak wording in README to point out that this is an AS Kim Alvefur <zash@zash.se> parents: 5642 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)
5680 b43c989fb69c mod_http_oauth2: Implement introspection endpoint Kim Alvefur <zash@zash.se> parents: 5644 diff changeset	54 - [RFC 7662: OAuth 2.0 Token Introspection](https://www.rfc-editor.org/rfc/rfc7662)
5589 7040d0772758 mod_http_oauth2: Implement RFC 8628 Device Authorization Grant Kim Alvefur <zash@zash.se> parents: 5588 diff changeset	55 - [RFC 8628: OAuth 2.0 Device Authorization Grant](https://www.rfc-editor.org/rfc/rfc8628)
5588 59acf7f540c1 mod_http_oauth2: Mention support for RFC 9207 Kim Alvefur <zash@zash.se> parents: 5562 diff changeset	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_)
5634 f3b7e05c74a9 mod_http_oauth2: Remove duplicated word in README introduced in 734788d8bfc3 Kim Alvefur <zash@zash.se> parents: 5617 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
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	89 ### Token parameters
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 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	92 The defaults are recommended.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	93
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	94 ```lua
5617 d8622797e315 mod_http_oauth2: Shorten default token validity periods Kim Alvefur <zash@zash.se> parents: 5615 diff changeset	95 oauth2_access_token_ttl = 3600 -- one hour
d8622797e315 mod_http_oauth2: Shorten default token validity periods Kim Alvefur <zash@zash.se> parents: 5615 diff changeset	96 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	97 ```
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	98
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	99 ### Dynamic 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 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	102 client registration.
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	103
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	104 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	105 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	106
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	107 ```lua
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	108 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	109 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	110 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	111 ```
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	112
5493 cae3bb3dd45f mod_http_oauth2: Document client registration requirements Kim Alvefur <zash@zash.se> parents: 5467 diff changeset	113 Registering a client is described in
cae3bb3dd45f mod_http_oauth2: Document client registration requirements Kim Alvefur <zash@zash.se> parents: 5467 diff changeset	114 [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	115
cae3bb3dd45f mod_http_oauth2: Document client registration requirements Kim Alvefur <zash@zash.se> parents: 5467 diff changeset	116 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	117 are enforced:
cae3bb3dd45f mod_http_oauth2: Document client registration requirements Kim Alvefur <zash@zash.se> parents: 5467 diff changeset	118
5506 37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	119 `client_name`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	120 : 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	121
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	122 `client_uri`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	123 : 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	124
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	125 `redirect_uris`
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 : 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	128 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	129
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	130 `application_type`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	131
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	132 : 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	133 `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	134
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	135 `web` (default)
5562 734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements Kim Alvefur <zash@zash.se> parents: 5561 diff changeset	136 : 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	137 `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	138 `client_uri`.
734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements Kim Alvefur <zash@zash.se> parents: 5561 diff changeset	139
734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements Kim Alvefur <zash@zash.se> parents: 5561 diff changeset	140 `native`
734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements Kim Alvefur <zash@zash.se> parents: 5561 diff changeset	141 : 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	142 match one of:
734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements Kim Alvefur <zash@zash.se> parents: 5561 diff changeset	143
734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements Kim Alvefur <zash@zash.se> parents: 5561 diff changeset	144 - 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	145 `http://[::1]`
734788d8bfc3 mod_http_oauth2: Rearrange description of redirect URIs requirements Kim Alvefur <zash@zash.se> parents: 5561 diff changeset	146 - 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	147 - 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	148
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	149 `tos_uri`, `policy_uri`
37621c6e5c08 mod_http_oauth2: Restructure description of client metadata requirements Kim Alvefur <zash@zash.se> parents: 5505 diff changeset	150 : 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	151 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	152 as the `client_uri`.
5493 cae3bb3dd45f mod_http_oauth2: Document client registration requirements Kim Alvefur <zash@zash.se> parents: 5467 diff changeset	153
5561 d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example Kim Alvefur <zash@zash.se> parents: 5547 diff changeset	154 #### Registration Examples
5494 1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	155
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	156 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	157 client to an endpoint:
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	158
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	159 ``` bash
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	160 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	161 -H Content-Type:application/json \
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	162 -H Accept:application/json \
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	163 --data '
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 "client_name" : "My Application",
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	166 "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	167 "redirect_uris" : [
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	168 "https://app.example.com/redirect"
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	169 ]
1bcf755c7bae mod_http_oauth2: Add an example of client registration Kim Alvefur <zash@zash.se> parents: 5493 diff changeset	170 }
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
5561 d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example Kim Alvefur <zash@zash.se> parents: 5547 diff changeset	174 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	175
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example Kim Alvefur <zash@zash.se> parents: 5547 diff changeset	176 ``` bash
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example Kim Alvefur <zash@zash.se> parents: 5547 diff changeset	177 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	178 -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	179 -H Accept:application/json \
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example Kim Alvefur <zash@zash.se> parents: 5547 diff changeset	180 --data '
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example Kim Alvefur <zash@zash.se> parents: 5547 diff changeset	181 {
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example Kim Alvefur <zash@zash.se> parents: 5547 diff changeset	182 "application_type" : "native",
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example Kim Alvefur <zash@zash.se> parents: 5547 diff changeset	183 "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	184 "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	185 "contacts" : [
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example Kim Alvefur <zash@zash.se> parents: 5547 diff changeset	186 "support@example.org"
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example Kim Alvefur <zash@zash.se> parents: 5547 diff changeset	187 ],
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example Kim Alvefur <zash@zash.se> parents: 5547 diff changeset	188 "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	189 "redirect_uris" : [
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example Kim Alvefur <zash@zash.se> parents: 5547 diff changeset	190 "http://localhost:8080/redirect",
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example Kim Alvefur <zash@zash.se> parents: 5547 diff changeset	191 "org.example.app:/redirect"
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example Kim Alvefur <zash@zash.se> parents: 5547 diff changeset	192 ],
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example Kim Alvefur <zash@zash.se> parents: 5547 diff changeset	193 "scope" : "xmpp",
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example Kim Alvefur <zash@zash.se> parents: 5547 diff changeset	194 "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	195 "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	196 "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	197 }
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example Kim Alvefur <zash@zash.se> parents: 5547 diff changeset	198 '
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example Kim Alvefur <zash@zash.se> parents: 5547 diff changeset	199 ```
d6ab6f0bd96e mod_http_oauth2: Add a more complete client registration example Kim Alvefur <zash@zash.se> parents: 5547 diff changeset	200
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	201 ### Supported flows
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	202
5521 ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults Kim Alvefur <zash@zash.se> parents: 5520 diff changeset	203 - Authorization Code grant, optionally with Proof Key for Code Exchange
5613 a9682cad0e67 mod_http_oauth2: Mention Device flow in list of flows in README Kim Alvefur <zash@zash.se> parents: 5589 diff changeset	204 - Device Authorization Grant
5615 308b5b117379 mod_http_oauth2: Hint at future deprecation of resource owner password grant Kim Alvefur <zash@zash.se> parents: 5614 diff changeset	205 - Resource owner password grant (likely to be phased out in the future)
5521 ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults Kim Alvefur <zash@zash.se> parents: 5520 diff changeset	206 - 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	207 - Refresh Token grants
ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults Kim Alvefur <zash@zash.se> parents: 5520 diff changeset	208
5197 164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	209 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	210 `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	211
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	212 ```lua
5521 ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults Kim Alvefur <zash@zash.se> parents: 5520 diff changeset	213 -- These examples reflect the defaults
5197 164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	214 allowed_oauth2_grant_types = {
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	215 "authorization_code"; -- authorization code grant
5614 7565298aa197 mod_http_oauth2: Allow a shorter form of the device grant in config Kim Alvefur <zash@zash.se> parents: 5613 diff changeset	216 "device_code";
5197 164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	217 "password"; -- resource owner password grant
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	218 }
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	219
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	220 allowed_oauth2_response_types = {
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	221 "code"; -- authorization code flow
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	222 -- "token"; -- implicit flow disabled by default
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	223 }
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	224 ```
164a9875935b mod_http_oauth2/README: Document config options Kim Alvefur <zash@zash.se> parents: 4924 diff changeset	225
5521 ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults Kim Alvefur <zash@zash.se> parents: 5520 diff changeset	226 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	227 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	228
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange Kim Alvefur <zash@zash.se> parents: 5328 diff changeset	229 ```lua
5521 ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults Kim Alvefur <zash@zash.se> parents: 5520 diff changeset	230 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	231 ```
df11a2cbc7b7 mod_http_oauth2: Implement RFC 7628 Proof Key for Code Exchange Kim Alvefur <zash@zash.se> parents: 5328 diff changeset	232
5384 b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	233 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	234
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	235 ```lua
5521 ef1ae6390742 mod_http_oauth2: Add some words about supported flows and defaults Kim Alvefur <zash@zash.se> parents: 5520 diff changeset	236 -- These reflects the default
5384 b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	237 allowed_oauth2_code_challenge_methods = {
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	238 "plain"; -- the insecure one
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	239 "S256";
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	240 }
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	241 ```
b40f29ec391a mod_http_oauth2: Allow configuring PKCE challenge methods Kim Alvefur <zash@zash.se> parents: 5383 diff changeset	242
5408 3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata Kim Alvefur <zash@zash.se> parents: 5384 diff changeset	243 ### Policy documents
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata Kim Alvefur <zash@zash.se> parents: 5384 diff changeset	244
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata Kim Alvefur <zash@zash.se> parents: 5384 diff changeset	245 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	246 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	247
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata Kim Alvefur <zash@zash.se> parents: 5384 diff changeset	248 ```lua
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata Kim Alvefur <zash@zash.se> parents: 5384 diff changeset	249 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	250 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	251 -- 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	252 ```
3989c57cc551 mod_http_oauth2: Allow configuring links to policy and terms in metadata Kim Alvefur <zash@zash.se> parents: 5384 diff changeset	253
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	254 ## Deployment notes
3903 cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only) Matthew Wild <mwild1@gmail.com> parents: diff changeset	255
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	256 ### Access management
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	257
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	258 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	259 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	260 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	261 [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	262 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	263 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	264
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	265 ### Scopes
3903 cfeb93b80621 mod_http_oauth2: OAuth2 API (work in progress for developers only) Matthew Wild <mwild1@gmail.com> parents: diff changeset	266
5313 80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	267 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	268
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	269 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	270 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	271 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	272 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	273 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	274 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	275 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	276 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	277
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 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	279 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	280
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 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	282
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 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	284 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	285
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	286 ## Compatibility
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	287
80ecba092027 mod_http_oauth2: README: Updated documentation to reflect module status Matthew Wild <mwild1@gmail.com> parents: 5212 diff changeset	288 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	289 earlier.

Mercurial > prosody-modules

annotate mod_http_oauth2/README.markdown @ 5715:8488ebde5739