---

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

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

  Version   Status

  --------- ---------------

  trunk     works

  0.12.x    does not work

  0.11.x    does not work