prosody-modules
f2363e6d9a64
mod_auth_oauth_external/README.md
Software / code / prosody-modules
File
mod_auth_oauth_external/README.md @ 5390:f2363e6d9a64
mod_http_oauth2: Advertise the currently supported id_token signing algorithm
This field is REQUIRED. The algorithm RS256 MUST be included, but isn't
because we don't implement it, as that would require implementing a pile
of additional cryptography and JWT stuff. Instead the id_token is
signed using the client secret, which allows verification by the client,
since it's a shared secret per OpenID Connect Core 1.0 § 10.1 under
Symmetric Signatures.
OpenID Connect Discovery 1.0 has a lot of REQUIRED and MUST clauses that
are not supported here, but that's okay because this is served from the
RFC 8414 OAuth 2.0 Authorization Server Metadata .well-known endpoint!
| author | Kim Alvefur <zash@zash.se> |
|---|---|
| date | Sun, 30 Apr 2023 16:13:40 +0200 |
| parent | 5349:ac9710126e1a |
| child | 5434:92ad8f03f225 |
line wrap: on
line source
--- summary: Authenticate against an external OAuth 2 IdP labels: - Stage-Alpha --- This module provides external authentication via an external [AOuth 2](https://datatracker.ietf.org/doc/html/rfc7628) authorization server and supports the [SASL OAUTHBEARER authentication][rfc7628] mechanism as well as PLAIN for legacy clients (this is all of them). # How it works Clients retrieve tokens somehow, then show them to Prosody, which asks the Authorization server to validate them, returning info about the user back to Prosody. Alternatively for legacy clients, Prosody receives the users username and password and retrieves a token itself, then proceeds as above. # Configuration ## Example ```lua -- authentication = "oauth_external" oauth_external_discovery_url = "https//auth.example.com/auth/realms/TheRealm/.well-known/openid-configuration" oauth_external_token_endpoint = "https//auth.example.com/auth/realms/TheRealm/protocol/openid-connect/token" oauth_external_validation_endpoint = "https//auth.example.com/auth/realms/TheRealm/protocol/openid-connect/userinfo" oauth_external_username_field = "xmpp_username" ``` ## Common `oauth_external_issuer` : Optional URL string representing the Authorization server identity. `oauth_external_discovery_url` : 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. `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` endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) `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 `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. `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. `oauth_external_client_id` : String. Client ID used to identify Prosody during the resource owner password grant. # Compatibility ## Prosody Version Status --------- --------------- trunk works 0.12.x does not work 0.11.x does not work ## Identity Provider Tested with - [KeyCloak](https://www.keycloak.org/) # Future work - Automatically discover endpoints from Discovery URL - Configurable input username mapping (e.g. user → user@host). - [SCRAM over HTTP?!][rfc7804]
