mod_firewall: Fix to find scripts when installed with plugin installer
Extra resources are stored in a different path by luarocks, not
alongside the code as this code assumed.
Thanks eTaurus
---
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)
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](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.
`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
- [KeyCloak](https://www.keycloak.org/)
- [Mastodon](https://joinmastodon.org/)
# Future work
- Automatically discover endpoints from Discovery URL
- Configurable input username mapping (e.g. user → user@host).
- [SCRAM over HTTP?!][rfc7804]