Diff

--- a/mod_http_oauth2/README.markdown	Fri May 26 02:15:45 2023 +0700
+++ b/mod_http_oauth2/README.markdown	Sun Jul 09 01:31:29 2023 +0700
@@ -1,12 +1,12 @@
 ---
 labels:
 - Stage-Alpha
-summary: 'OAuth2 API'
 rockspec:
   build:
     copy_directories:
     - html
-...
+summary: OAuth 2.0 Authorization Server API
+---
 
 ## Introduction
 
@@ -18,9 +18,10 @@
 third-party applications limited access to your account, without sharing your
 password with them.
 
-With this module deployed, software that supports OAuth can obtain "access
-tokens" from Prosody which can then be used to connect to XMPP accounts using
-the 'OAUTHBEARER' SASL mechanism or via non-XMPP interfaces such as [mod_rest].
+With this module deployed, software that supports OAuth can obtain
+"access tokens" from Prosody which can then be used to connect to XMPP
+accounts using the [OAUTHBEARER SASL mechanism][rfc7628] or via non-XMPP
+interfaces such as [mod_rest].
 
 Although this module has been around for some time, it has recently been
 significantly extended and largely rewritten to support OAuth/OIDC more fully.
@@ -36,9 +37,10 @@
 -   [example shell script for mod_rest](https://hg.prosody.im/prosody-modules/file/tip/mod_rest/example/rest.sh)
 -   *(we need you!)*
 
-Support for OAUTHBEARER has been added to the Lua XMPP library, [verse](https://code.matthewwild.co.uk/verse).
-If you know of additional implementations, or are motivated to work on one,
-please let us know! We'd be happy to help (e.g. by providing a test server).
+Support for [OAUTHBEARER][rfc7628] has been added to the Lua XMPP
+library, [verse](https://code.matthewwild.co.uk/verse).  If you know of
+additional implementations, or are motivated to work on one, please let
+us know! We'd be happy to help (e.g. by providing a test server).
 
 ## Standards support
 
@@ -49,6 +51,7 @@
 - [RFC 7591: OAuth 2.0 Dynamic Client Registration](https://www.rfc-editor.org/rfc/rfc7591.html)
 - [RFC 7628: A Set of Simple Authentication and Security Layer (SASL) Mechanisms for OAuth](https://www.rfc-editor.org/rfc/rfc7628)
 - [RFC 7636: Proof Key for Code Exchange by OAuth Public Clients](https://www.rfc-editor.org/rfc/rfc7636)
+- [RFC 9207: OAuth 2.0 Authorization Server Issuer Identification](https://www.rfc-editor.org/rfc/rfc9207.html)
 - [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)
 - [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) (_partial, e.g. missing JWKS_)
 - [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) 
@@ -61,7 +64,7 @@
 a client requests access. Built-in pages are provided, but you may also theme
 or entirely override them.
 
-This module honours the 'site_name' configuration option that is also used by
+This module honours the `site_name` configuration option that is also used by
 a number of other modules:
 
 ```lua
@@ -75,7 +78,7 @@
 ```
 
 Some templates support additional variables, that can be provided by the
-'oauth2_template_style' option:
+`oauth2_template_style` option:
 
 ```lua
 oauth2_template_style = {
@@ -83,6 +86,13 @@
 }
 ```
 
+If you know what features your templates use use you can adjust the
+`Content-Security-Policy` header to only allow what is needed:
+
+```lua
+oauth2_security_policy = "default-src 'self'" -- this is the default
+```
+
 ### Token parameters
 
 The following options configure the lifetime of tokens issued by the module.
@@ -107,12 +117,109 @@
 oauth2_registration_ttl = nil -- unlimited by default
 ```
 
+Registering a client is described in
+[RFC7591](https://www.rfc-editor.org/rfc/rfc7591.html).
+
+In addition to the requirements in the RFC, the following requirements
+are enforced:
+
+`client_name`
+:   **MUST** be present, is shown to users in consent screen.
+
+`client_uri`
+:   **MUST** be present and **MUST** be a `https://` URL.
+
+`redirect_uris`
+
+:   **MUST** contain at least one valid URI. Different rules apply
+    depending on the value of `application_type`, see below.
+
+`application_type`
+
+:   Optional, defaults to `web`. Determines further restrictions for
+    `redirect_uris`. The following values are supported:
+
+    `web` *(default)*
+    :   For web clients. With this, `redirect_uris` **MUST** be
+        `https://` URIs and **MUST** use the same hostname part as the
+        `client_uri`.
+
+    `native`
+
+    `native`
+
+    :   For native e.g. desktop clients etc. `redirect_uris` **MUST**
+        match one of:
+
+        -   Loopback HTTP URI, e.g. `http://127.0.0.1/` or
+            `http://[::1]`
+        -   Application-specific scheme, e.g. `com.example.app:/`
+        -   The special OOB URI `urn:ietf:wg:oauth:2.0:oob`
+
+`tos_uri`, `policy_uri`
+:   Informative URLs pointing to Terms of Service and Service Policy
+    document **MUST** use the same scheme (i.e. `https://`) and hostname
+    as the `client_uri`.
+
+#### Registration Examples
+
+In short registration works by POST-ing a JSON structure describing your
+client to an endpoint:
+
+``` bash
+curl -sSf https://xmpp.example.net/oauth2/register \
+    -H Content-Type:application/json \
+    -H Accept:application/json \
+    --data '
+{
+   "client_name" : "My Application",
+   "client_uri" : "https://app.example.com/",
+   "redirect_uris" : [
+      "https://app.example.com/redirect"
+   ]
+}
+'
+```
+
+Another example with more fields:
+
+``` bash
+curl -sSf https://xmpp.example.net/oauth2/register \
+    -H Content-Type:application/json \
+    -H Accept:application/json \
+    --data '
+{
+   "application_type" : "native",
+   "client_name" : "Desktop Chat App",
+   "client_uri" : "https://app.example.org/",
+   "contacts" : [
+      "support@example.org"
+   ],
+   "policy_uri" : "https://app.example.org/about/privacy",
+   "redirect_uris" : [
+      "http://localhost:8080/redirect",
+      "org.example.app:/redirect"
+   ],
+   "scope" : "xmpp",
+   "software_id" : "32a0a8f3-4016-5478-905a-c373156eca73",
+   "software_version" : "3.4.1",
+   "tos_uri" : "https://app.example.org/about/terms"
+}
+'
+```
+
 ### Supported flows
 
+-   Authorization Code grant, optionally with Proof Key for Code Exchange
+-   Resource owner password grant
+-   Implicit flow *(disabled by default)*
+-   Refresh Token grants
+
 Various flows can be disabled and enabled with
 `allowed_oauth2_grant_types` and `allowed_oauth2_response_types`:
 
 ```lua
+-- These examples reflect the defaults
 allowed_oauth2_grant_types = {
 	"authorization_code"; -- authorization code grant
 	"password"; -- resource owner password grant
@@ -124,16 +231,17 @@
 }
 ```
 
-The [Proof Key for Code Exchange][RFC 7636] mitigation method can be
-made required:
+The [Proof Key for Code Exchange][RFC 7636] mitigation method is
+optional by default but can be made required:
 
 ```lua
-oauth2_require_code_challenge = true
+oauth2_require_code_challenge = true -- default is false
 ```
 
 Further, individual challenge methods can be enabled or disabled:
 
 ```lua
+-- These reflects the default
 allowed_oauth2_code_challenge_methods = {
     "plain"; -- the insecure one
     "S256";
@@ -148,6 +256,7 @@
 ```lua
 oauth2_terms_url = "https://example.com/terms-of-service.html"
 oauth2_policy_url = "https://example.com/service-policy.pdf"
+-- These are unset by default
 ```
 
 ## Deployment notes
@@ -157,7 +266,7 @@
 This module does not provide an interface for users to manage what they have
 granted access to their account! (e.g. to view and revoke clients they have
 previously authorized). It is recommended to join this module with
-mod_client_management to provide such access. However, at the time of writing,
+[mod_client_management] to provide such access. However, at the time of writing,
 no XMPP clients currently support the protocol used by that module. We plan to
 work on additional interfaces in the future.