mod_auth_oauth_external

This module provides external authentication via an external OAuth 2 authorization server and supports the SASL OAUTHBEARER authentication 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

-- 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. 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 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

oauth_external_resource_owner_password
Boolean. Defaults to true. Whether to allow the insecure resource owner password grant and SASL PLAIN.
oauth_external_token_endpoint
URL string. OAuth 2 Token Endpoint 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.
oauth_external_client_secret
String. Client secret used to identify Prosody during the resource owner password grant.
oauth_external_scope
String. Defaults to "openid". Included in request for resource owner password grant.

Compatibility

Prosody

Version Status
trunk works
0.12.x OAUTHBEARER will not work, otherwise untested
0.11.x OAUTHBEARER will not work, otherwise untested

Identity Provider

Tested with

Future work


Installation

With the plugin installer in Prosody 0.12 you can use:

sudo prosodyctl install --server=https://modules.prosody.im/rocks/ mod_auth_oauth_external

For earlier versions see the documentation for installing 3rd party modules