--- a/mod_auth_oauth_external/README.md	Sat May 02 16:13:35 2026 +0200
+++ b/mod_auth_oauth_external/README.md	Sat May 02 16:26:31 2026 +0200
@@ -50,8 +50,7 @@
 oauth_external_resource_owner_password = true
 ```
 
-
-## Common
+## Settings
 
 `oauth_external_issuer`
 :   Optional URL string representing the Authorization server identity.
@@ -60,42 +59,43 @@
 :   Optional URL string pointing to [OAuth 2.0 Authorization Server
     Metadata](https://oauth.net/2/authorization-server-metadata/). Lets
     clients discover where they should retrieve access tokens from if
-    they don't have one yet. Default based on `oauth_external_issuer` is
-    set, otherwise empty.
+    they don't have one yet. Defaults to
+    `issuer_identity + "/.well-known/oauth-authorization-server"` when
+    `oauth_external_issuer` is set, otherwise unset.
 
 `oauth_external_validation_endpoint`
 :   URL string. The token validation endpoint, should validate the token
     and return a JSON structure containing the username of the user
     logging in the field specified by `oauth_external_username_field`.
-    Commonly the [OpenID `UserInfo`
+    Required for SASL OAUTHBEARER. For SASL PLAIN, enables username
+    lookup. Commonly the [OpenID `UserInfo`
     endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)
     If left unset, only `SASL PLAIN` is supported and the username
     provided there is assumed correct.
 
 `oauth_external_username_field`
 :   String. Default is `"preferred_username"`. Field in the JSON
-    structure returned by the validation endpoint that contains the XMPP
-    localpart.
-
-## For SASL PLAIN
+    structure returned by the validation endpoint that to be used as the
+    XMPP localpart.
 
 `oauth_external_resource_owner_password`
-:   Boolean. Defaults to `true`. Whether to allow the *insecure*
-    [resource owner password
-    grant](https://oauth.net/2/grant-types/password/) and SASL PLAIN.
+:   Boolean. Defaults to `true`. Enables SASL PLAIN for legacy XMPP
+    clients via the [resource owner password
+    grant](https://oauth.net/2/grant-types/password/) *(considered
+    insecure)*.
 
 `oauth_external_token_endpoint`
 :   URL string. OAuth 2 [Token
     Endpoint](https://www.rfc-editor.org/rfc/rfc6749#section-3.2) used
-    to retrieve token in order to then retrieve the username.
+    to validate credentials passed via SASL PLAIN.
 
 `oauth_external_client_id`
-:   String. Client ID used to identify Prosody during the resource owner
+:   String. Client ID used to identify Prosody in the resource owner
     password grant.
 
 `oauth_external_client_secret`
-:   String. Client secret used to identify Prosody during the resource
-    owner password grant.
+:   String. Client secret used to identify Prosody in the resource owner
+    password grant.
 
 `oauth_external_scope`
 :   String. Defaults to `"openid"`. Included in request for resource