Mercurial > prosody-modules

view mod_auth_oauth_external/README.md @ 5425:3b30635d215c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_http_oauth2: Support granting zero role-scopes It seems Very Bad that if you uncheck all roles on the consent page, you get the default scopes, which seems the opposite of what you probably intended. Currently, mod_tokenauth will do the same thing, so work is needed there too to allow issuing tokens without roles. A token without a role could be used for OIDC login, and not much else. This seems like a valuable thing to support.
author Kim Alvefur <zash@zash.se>
date Sun, 07 May 2023 19:29:15 +0200
parents ac9710126e1a
children 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]