prosody-modules
e20901443eae
mod_auth_oauth_external/README.md

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Annotate

mod_auth_oauth_external/README.md @ 6208:e20901443eae draft

Merge
author Trần H. Trung <xmpp:trần.h.trung@trung.fun>
date Mon, 17 Mar 2025 23:42:11 +0700
parent 5885:c20a0c8a54ea
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
5885
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
6208
Trần H. Trung <xmpp:trần.h.trung@trung.fun>
parents: 5885
diff changeset
14 Using OAuth 2.0 in XMPP is explained in [XEP-0493: OAuth Client Login].
Trần H. Trung <xmpp:trần.h.trung@trung.fun>
parents: 5885
diff changeset
15 Clients pass tokens from the Authorization Server to Prosody, which
Trần H. Trung <xmpp:trần.h.trung@trung.fun>
parents: 5885
diff changeset
16 attempts to validate the tokens using the configured validation
Trần H. Trung <xmpp:trần.h.trung@trung.fun>
parents: 5885
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
6208
Trần H. Trung <xmpp:trần.h.trung@trung.fun>
parents: 5885
diff changeset
19 Legacy clients have to use SASL PLAIN, where Prosody receives the users
Trần H. Trung <xmpp:trần.h.trung@trung.fun>
parents: 5885
diff changeset
20 username and password and attempts to validate this using the OAuth 2
Trần H. Trung <xmpp:trần.h.trung@trung.fun>
parents: 5885
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]