Mercurial > prosody-modules

comparison mod_auth_oauth_external/README.md @ 6527:6f2f21b00233

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_auth_oauth_external: Expand descriptions of settings
author Kim Alvefur <zash@zash.se>
date Sat, 02 May 2026 16:26:31 +0200
parents d454eae0d8ef
children
comparison
equal deleted inserted replaced
6526:1216f6befbe7 6527:6f2f21b00233
48 oauth_external_username_field = "username" 48 oauth_external_username_field = "username"
49 oauth_external_scope = "read:accounts" 49 oauth_external_scope = "read:accounts"
50 oauth_external_resource_owner_password = true 50 oauth_external_resource_owner_password = true
51 ``` 51 ```
52 52
53 53 ## Settings
54 ## Common
55 54
56 `oauth_external_issuer` 55 `oauth_external_issuer`
57 : Optional URL string representing the Authorization server identity. 56 : Optional URL string representing the Authorization server identity.
58 57
59 `oauth_external_discovery_url` 58 `oauth_external_discovery_url`
60 : Optional URL string pointing to [OAuth 2.0 Authorization Server 59 : Optional URL string pointing to [OAuth 2.0 Authorization Server
61 Metadata](https://oauth.net/2/authorization-server-metadata/). Lets 60 Metadata](https://oauth.net/2/authorization-server-metadata/). Lets
62 clients discover where they should retrieve access tokens from if 61 clients discover where they should retrieve access tokens from if
63 they don't have one yet. Default based on `oauth_external_issuer` is 62 they don't have one yet. Defaults to
64 set, otherwise empty. 63 `issuer_identity + "/.well-known/oauth-authorization-server"` when
64 `oauth_external_issuer` is set, otherwise unset.
65 65
66 `oauth_external_validation_endpoint` 66 `oauth_external_validation_endpoint`
67 : URL string. The token validation endpoint, should validate the token 67 : URL string. The token validation endpoint, should validate the token
68 and return a JSON structure containing the username of the user 68 and return a JSON structure containing the username of the user
69 logging in the field specified by `oauth_external_username_field`. 69 logging in the field specified by `oauth_external_username_field`.
70 Commonly the [OpenID `UserInfo` 70 Required for SASL OAUTHBEARER. For SASL PLAIN, enables username
71 lookup. Commonly the [OpenID `UserInfo`
71 endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) 72 endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)
72 If left unset, only `SASL PLAIN` is supported and the username 73 If left unset, only `SASL PLAIN` is supported and the username
73 provided there is assumed correct. 74 provided there is assumed correct.
74 75
75 `oauth_external_username_field` 76 `oauth_external_username_field`
76 : String. Default is `"preferred_username"`. Field in the JSON 77 : String. Default is `"preferred_username"`. Field in the JSON
77 structure returned by the validation endpoint that contains the XMPP 78 structure returned by the validation endpoint that to be used as the
78 localpart. 79 XMPP localpart.
79
80 ## For SASL PLAIN
81 80
82 `oauth_external_resource_owner_password` 81 `oauth_external_resource_owner_password`
83 : Boolean. Defaults to `true`. Whether to allow the *insecure* 82 : Boolean. Defaults to `true`. Enables SASL PLAIN for legacy XMPP
84 [resource owner password 83 clients via the [resource owner password
85 grant](https://oauth.net/2/grant-types/password/) and SASL PLAIN. 84 grant](https://oauth.net/2/grant-types/password/) *(considered
85 insecure)*.
86 86
87 `oauth_external_token_endpoint` 87 `oauth_external_token_endpoint`
88 : URL string. OAuth 2 [Token 88 : URL string. OAuth 2 [Token
89 Endpoint](https://www.rfc-editor.org/rfc/rfc6749#section-3.2) used 89 Endpoint](https://www.rfc-editor.org/rfc/rfc6749#section-3.2) used
90 to retrieve token in order to then retrieve the username. 90 to validate credentials passed via SASL PLAIN.
91 91
92 `oauth_external_client_id` 92 `oauth_external_client_id`
93 : String. Client ID used to identify Prosody during the resource owner 93 : String. Client ID used to identify Prosody in the resource owner
94 password grant. 94 password grant.
95 95
96 `oauth_external_client_secret` 96 `oauth_external_client_secret`
97 : String. Client secret used to identify Prosody during the resource 97 : String. Client secret used to identify Prosody in the resource owner
98 owner password grant. 98 password grant.
99 99
100 `oauth_external_scope` 100 `oauth_external_scope`
101 : String. Defaults to `"openid"`. Included in request for resource 101 : String. Defaults to `"openid"`. Included in request for resource
102 owner password grant. 102 owner password grant.
103 103