annotate mod_auth_oauth_external/README.md @ 6319:04c3273cb81f

mod_auth_cyrus: Add empty 'profile' table to SASL handler objects This is for compatibility with Prosody's built-in util.sasl objects. A SASL profile table usually includes methods supported by the backend, which can be used by SASL mechanism handlers to perform operations (such as testing the password). It also optionally contains a 'cb' field with channel binding method handlers. The Cyrus backend doesn't support channel binding, and doesn't have the same concept of auth backend methods (it handles all that internally, and Prosody has no insight or control over it). Thus, we create an empty profile which informs Prosody that the SASL handler does not support any of the auth or channel binding methods. Some features will not work, but they didn't work anyway. This just makes it explicit. This fixes a traceback in mod_sasl2_fast, which expected SASL handlers to always contain a 'profile' field.
author Matthew Wild <mwild1@gmail.com>
date Thu, 04 Sep 2025 10:14:46 +0100
parents cce76628c83a
children 8f65b23a5fd2
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5344
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
1 ---
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
2 summary: Authenticate against an external OAuth 2 IdP
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
3 labels:
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
4 - Stage-Alpha
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
5 ---
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6
5861
c20a0c8a54ea mod_auth_oauth_external: Fix typo
Kim Alvefur <zash@zash.se>
parents: 5499
diff changeset
7 This module provides external authentication via an external [OAuth
5344
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
8 2](https://datatracker.ietf.org/doc/html/rfc7628) authorization server
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
9 and supports the [SASL OAUTHBEARER authentication][rfc7628]
5345
3390bb2f9f6c mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents: 5344
diff changeset
10 mechanism as well as PLAIN for legacy clients (this is all of them).
5344
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
11
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
12 # How it works
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
13
6020
cce76628c83a mod_auth_oauth_external: Reword 'How it works'
Kim Alvefur <zash@zash.se>
parents: 5861
diff changeset
14 Using OAuth 2.0 in XMPP is explained in [XEP-0493: OAuth Client Login].
cce76628c83a mod_auth_oauth_external: Reword 'How it works'
Kim Alvefur <zash@zash.se>
parents: 5861
diff changeset
15 Clients pass tokens from the Authorization Server to Prosody, which
cce76628c83a mod_auth_oauth_external: Reword 'How it works'
Kim Alvefur <zash@zash.se>
parents: 5861
diff changeset
16 attempts to validate the tokens using the configured validation
cce76628c83a mod_auth_oauth_external: Reword 'How it works'
Kim Alvefur <zash@zash.se>
parents: 5861
diff changeset
17 endpoint.
5344
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
18
6020
cce76628c83a mod_auth_oauth_external: Reword 'How it works'
Kim Alvefur <zash@zash.se>
parents: 5861
diff changeset
19 Legacy clients have to use SASL PLAIN, where Prosody receives the users
cce76628c83a mod_auth_oauth_external: Reword 'How it works'
Kim Alvefur <zash@zash.se>
parents: 5861
diff changeset
20 username and password and attempts to validate this using the OAuth 2
cce76628c83a mod_auth_oauth_external: Reword 'How it works'
Kim Alvefur <zash@zash.se>
parents: 5861
diff changeset
21 resource owner password grant.
5345
3390bb2f9f6c mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents: 5344
diff changeset
22
5344
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
23 # Configuration
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
24
5349
ac9710126e1a mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents: 5348
diff changeset
25 ## Example
ac9710126e1a mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents: 5348
diff changeset
26
ac9710126e1a mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents: 5348
diff changeset
27 ```lua
ac9710126e1a mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents: 5348
diff changeset
28 -- authentication = "oauth_external"
ac9710126e1a mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents: 5348
diff changeset
29
ac9710126e1a mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents: 5348
diff changeset
30 oauth_external_discovery_url = "https//auth.example.com/auth/realms/TheRealm/.well-known/openid-configuration"
ac9710126e1a mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents: 5348
diff changeset
31 oauth_external_token_endpoint = "https//auth.example.com/auth/realms/TheRealm/protocol/openid-connect/token"
ac9710126e1a mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents: 5348
diff changeset
32 oauth_external_validation_endpoint = "https//auth.example.com/auth/realms/TheRealm/protocol/openid-connect/userinfo"
ac9710126e1a mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents: 5348
diff changeset
33 oauth_external_username_field = "xmpp_username"
ac9710126e1a mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents: 5348
diff changeset
34 ```
ac9710126e1a mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents: 5348
diff changeset
35
ac9710126e1a mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents: 5348
diff changeset
36
ac9710126e1a mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents: 5348
diff changeset
37 ## Common
ac9710126e1a mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents: 5348
diff changeset
38
5346
d9bc8712a745 mod_auth_oauth_external: Allow setting identity instead of discovery URL
Kim Alvefur <zash@zash.se>
parents: 5345
diff changeset
39 `oauth_external_issuer`
d9bc8712a745 mod_auth_oauth_external: Allow setting identity instead of discovery URL
Kim Alvefur <zash@zash.se>
parents: 5345
diff changeset
40 : Optional URL string representing the Authorization server identity.
d9bc8712a745 mod_auth_oauth_external: Allow setting identity instead of discovery URL
Kim Alvefur <zash@zash.se>
parents: 5345
diff changeset
41
5344
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
42 `oauth_external_discovery_url`
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
43 : Optional URL string pointing to [OAuth 2.0 Authorization Server
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
44 Metadata](https://oauth.net/2/authorization-server-metadata/). Lets
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
45 clients discover where they should retrieve access tokens from if
5346
d9bc8712a745 mod_auth_oauth_external: Allow setting identity instead of discovery URL
Kim Alvefur <zash@zash.se>
parents: 5345
diff changeset
46 they don't have one yet. Default based on `oauth_external_issuer` is
d9bc8712a745 mod_auth_oauth_external: Allow setting identity instead of discovery URL
Kim Alvefur <zash@zash.se>
parents: 5345
diff changeset
47 set, otherwise empty.
5344
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
48
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
49 `oauth_external_validation_endpoint`
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
50 : URL string. The token validation endpoint, should validate the token
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
51 and return a JSON structure containing the username of the user
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
52 logging in the field specified by `oauth_external_username_field`.
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
53 Commonly the [OpenID `UserInfo`
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
54 endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo)
5434
92ad8f03f225 mod_auth_oauth_external: Work without token validation endpoint
Kim Alvefur <zash@zash.se>
parents: 5349
diff changeset
55 If left unset, only `SASL PLAIN` is supported and the username
92ad8f03f225 mod_auth_oauth_external: Work without token validation endpoint
Kim Alvefur <zash@zash.se>
parents: 5349
diff changeset
56 provided there is assumed correct.
5344
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
57
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
58 `oauth_external_username_field`
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
59 : String. Default is `"preferred_username"`. Field in the JSON
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
60 structure returned by the validation endpoint that contains the XMPP
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
61 localpart.
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
62
5345
3390bb2f9f6c mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents: 5344
diff changeset
63 ## For SASL PLAIN
3390bb2f9f6c mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents: 5344
diff changeset
64
3390bb2f9f6c mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents: 5344
diff changeset
65 `oauth_external_resource_owner_password`
3390bb2f9f6c mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents: 5344
diff changeset
66 : Boolean. Defaults to `true`. Whether to allow the *insecure*
5348
ff539f34769f mod_auth_oauth_external: Linkify password grant
Kim Alvefur <zash@zash.se>
parents: 5347
diff changeset
67 [resource owner password
ff539f34769f mod_auth_oauth_external: Linkify password grant
Kim Alvefur <zash@zash.se>
parents: 5347
diff changeset
68 grant](https://oauth.net/2/grant-types/password/) and SASL PLAIN.
5345
3390bb2f9f6c mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents: 5344
diff changeset
69
3390bb2f9f6c mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents: 5344
diff changeset
70 `oauth_external_token_endpoint`
3390bb2f9f6c mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents: 5344
diff changeset
71 : URL string. OAuth 2 [Token
3390bb2f9f6c mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents: 5344
diff changeset
72 Endpoint](https://www.rfc-editor.org/rfc/rfc6749#section-3.2) used
3390bb2f9f6c mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents: 5344
diff changeset
73 to retrieve token in order to then retrieve the username.
3390bb2f9f6c mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents: 5344
diff changeset
74
3390bb2f9f6c mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents: 5344
diff changeset
75 `oauth_external_client_id`
3390bb2f9f6c mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents: 5344
diff changeset
76 : String. Client ID used to identify Prosody during the resource owner
3390bb2f9f6c mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents: 5344
diff changeset
77 password grant.
3390bb2f9f6c mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents: 5344
diff changeset
78
5435
b3e7886fea6a mod_auth_oauth_external: Add setting for client_secret
Kim Alvefur <zash@zash.se>
parents: 5434
diff changeset
79 `oauth_external_client_secret`
b3e7886fea6a mod_auth_oauth_external: Add setting for client_secret
Kim Alvefur <zash@zash.se>
parents: 5434
diff changeset
80 : String. Client secret used to identify Prosody during the resource
b3e7886fea6a mod_auth_oauth_external: Add setting for client_secret
Kim Alvefur <zash@zash.se>
parents: 5434
diff changeset
81 owner password grant.
b3e7886fea6a mod_auth_oauth_external: Add setting for client_secret
Kim Alvefur <zash@zash.se>
parents: 5434
diff changeset
82
5436
e7d99bacd0e8 mod_auth_oauth_external: Make 'scope' configurable in password grant request
Kim Alvefur <zash@zash.se>
parents: 5435
diff changeset
83 `oauth_external_scope`
5499
27d220b14d59 mod_auth_oauth_external: Correct docs about default scope
Kim Alvefur <zash@zash.se>
parents: 5444
diff changeset
84 : String. Defaults to `"openid"`. Included in request for resource
5436
e7d99bacd0e8 mod_auth_oauth_external: Make 'scope' configurable in password grant request
Kim Alvefur <zash@zash.se>
parents: 5435
diff changeset
85 owner password grant.
e7d99bacd0e8 mod_auth_oauth_external: Make 'scope' configurable in password grant request
Kim Alvefur <zash@zash.se>
parents: 5435
diff changeset
86
5344
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
87 # Compatibility
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
88
5347
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
89 ## Prosody
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
90
5344
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
91 Version Status
5444
0c7abc81c243 mod_auth_oauth_external: Update compatibility section with unknowns
Kim Alvefur <zash@zash.se>
parents: 5441
diff changeset
92 --------- -----------------------------------------------
5344
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
93 trunk works
5444
0c7abc81c243 mod_auth_oauth_external: Update compatibility section with unknowns
Kim Alvefur <zash@zash.se>
parents: 5441
diff changeset
94 0.12.x OAUTHBEARER will not work, otherwise untested
0c7abc81c243 mod_auth_oauth_external: Update compatibility section with unknowns
Kim Alvefur <zash@zash.se>
parents: 5441
diff changeset
95 0.11.x OAUTHBEARER will not work, otherwise untested
5347
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
96
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
97 ## Identity Provider
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
98
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
99 Tested with
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
100
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
101 - [KeyCloak](https://www.keycloak.org/)
5441
533808db6c18 mod_auth_oauth_external: Add Mastodon to README
Kim Alvefur <zash@zash.se>
parents: 5436
diff changeset
102 - [Mastodon](https://joinmastodon.org/)
5347
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
103
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
104 # Future work
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
105
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
106 - Automatically discover endpoints from Discovery URL
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
107 - Configurable input username mapping (e.g. user → user@host).
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
108 - [SCRAM over HTTP?!][rfc7804]