author | Kim Alvefur <zash@zash.se> |
Sat, 09 Mar 2024 21:05:00 +0100 | |
changeset 5865 | c20a0c8a54ea |
parent 5503 | 27d220b14d59 |
permissions | -rw-r--r-- |
5348
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 |
|
5865
c20a0c8a54ea
mod_auth_oauth_external: Fix typo
Kim Alvefur <zash@zash.se>
parents:
5503
diff
changeset
|
7 |
This module provides external authentication via an external [OAuth |
5348
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] |
5349
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5348
diff
changeset
|
10 |
mechanism as well as PLAIN for legacy clients (this is all of them). |
5348
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 |
|
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
14 |
Clients retrieve tokens somehow, then show them to Prosody, which asks |
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
15 |
the Authorization server to validate them, returning info about the user |
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
16 |
back to Prosody. |
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
17 |
|
5349
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5348
diff
changeset
|
18 |
Alternatively for legacy clients, Prosody receives the users username |
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5348
diff
changeset
|
19 |
and password and retrieves a token itself, then proceeds as above. |
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5348
diff
changeset
|
20 |
|
5348
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
21 |
# Configuration |
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
22 |
|
5353
ac9710126e1a
mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents:
5352
diff
changeset
|
23 |
## Example |
ac9710126e1a
mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents:
5352
diff
changeset
|
24 |
|
ac9710126e1a
mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents:
5352
diff
changeset
|
25 |
```lua |
ac9710126e1a
mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents:
5352
diff
changeset
|
26 |
-- authentication = "oauth_external" |
ac9710126e1a
mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents:
5352
diff
changeset
|
27 |
|
ac9710126e1a
mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents:
5352
diff
changeset
|
28 |
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:
5352
diff
changeset
|
29 |
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:
5352
diff
changeset
|
30 |
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:
5352
diff
changeset
|
31 |
oauth_external_username_field = "xmpp_username" |
ac9710126e1a
mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents:
5352
diff
changeset
|
32 |
``` |
ac9710126e1a
mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents:
5352
diff
changeset
|
33 |
|
ac9710126e1a
mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents:
5352
diff
changeset
|
34 |
|
ac9710126e1a
mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents:
5352
diff
changeset
|
35 |
## Common |
ac9710126e1a
mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents:
5352
diff
changeset
|
36 |
|
5350
d9bc8712a745
mod_auth_oauth_external: Allow setting identity instead of discovery URL
Kim Alvefur <zash@zash.se>
parents:
5349
diff
changeset
|
37 |
`oauth_external_issuer` |
d9bc8712a745
mod_auth_oauth_external: Allow setting identity instead of discovery URL
Kim Alvefur <zash@zash.se>
parents:
5349
diff
changeset
|
38 |
: 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:
5349
diff
changeset
|
39 |
|
5348
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
40 |
`oauth_external_discovery_url` |
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
41 |
: 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
|
42 |
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
|
43 |
clients discover where they should retrieve access tokens from if |
5350
d9bc8712a745
mod_auth_oauth_external: Allow setting identity instead of discovery URL
Kim Alvefur <zash@zash.se>
parents:
5349
diff
changeset
|
44 |
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:
5349
diff
changeset
|
45 |
set, otherwise empty. |
5348
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
46 |
|
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
47 |
`oauth_external_validation_endpoint` |
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
48 |
: 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
|
49 |
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
|
50 |
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
|
51 |
Commonly the [OpenID `UserInfo` |
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
52 |
endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) |
5438
92ad8f03f225
mod_auth_oauth_external: Work without token validation endpoint
Kim Alvefur <zash@zash.se>
parents:
5353
diff
changeset
|
53 |
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:
5353
diff
changeset
|
54 |
provided there is assumed correct. |
5348
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
55 |
|
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
56 |
`oauth_external_username_field` |
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
57 |
: 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
|
58 |
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
|
59 |
localpart. |
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
60 |
|
5349
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5348
diff
changeset
|
61 |
## For SASL PLAIN |
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5348
diff
changeset
|
62 |
|
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5348
diff
changeset
|
63 |
`oauth_external_resource_owner_password` |
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5348
diff
changeset
|
64 |
: Boolean. Defaults to `true`. Whether to allow the *insecure* |
5352
ff539f34769f
mod_auth_oauth_external: Linkify password grant
Kim Alvefur <zash@zash.se>
parents:
5351
diff
changeset
|
65 |
[resource owner password |
ff539f34769f
mod_auth_oauth_external: Linkify password grant
Kim Alvefur <zash@zash.se>
parents:
5351
diff
changeset
|
66 |
grant](https://oauth.net/2/grant-types/password/) and SASL PLAIN. |
5349
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5348
diff
changeset
|
67 |
|
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5348
diff
changeset
|
68 |
`oauth_external_token_endpoint` |
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5348
diff
changeset
|
69 |
: URL string. OAuth 2 [Token |
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5348
diff
changeset
|
70 |
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:
5348
diff
changeset
|
71 |
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:
5348
diff
changeset
|
72 |
|
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5348
diff
changeset
|
73 |
`oauth_external_client_id` |
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5348
diff
changeset
|
74 |
: 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:
5348
diff
changeset
|
75 |
password grant. |
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5348
diff
changeset
|
76 |
|
5439
b3e7886fea6a
mod_auth_oauth_external: Add setting for client_secret
Kim Alvefur <zash@zash.se>
parents:
5438
diff
changeset
|
77 |
`oauth_external_client_secret` |
b3e7886fea6a
mod_auth_oauth_external: Add setting for client_secret
Kim Alvefur <zash@zash.se>
parents:
5438
diff
changeset
|
78 |
: 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:
5438
diff
changeset
|
79 |
owner password grant. |
b3e7886fea6a
mod_auth_oauth_external: Add setting for client_secret
Kim Alvefur <zash@zash.se>
parents:
5438
diff
changeset
|
80 |
|
5440
e7d99bacd0e8
mod_auth_oauth_external: Make 'scope' configurable in password grant request
Kim Alvefur <zash@zash.se>
parents:
5439
diff
changeset
|
81 |
`oauth_external_scope` |
5503
27d220b14d59
mod_auth_oauth_external: Correct docs about default scope
Kim Alvefur <zash@zash.se>
parents:
5448
diff
changeset
|
82 |
: String. Defaults to `"openid"`. Included in request for resource |
5440
e7d99bacd0e8
mod_auth_oauth_external: Make 'scope' configurable in password grant request
Kim Alvefur <zash@zash.se>
parents:
5439
diff
changeset
|
83 |
owner password grant. |
e7d99bacd0e8
mod_auth_oauth_external: Make 'scope' configurable in password grant request
Kim Alvefur <zash@zash.se>
parents:
5439
diff
changeset
|
84 |
|
5348
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
85 |
# Compatibility |
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
86 |
|
5351
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5350
diff
changeset
|
87 |
## Prosody |
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5350
diff
changeset
|
88 |
|
5348
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
89 |
Version Status |
5448
0c7abc81c243
mod_auth_oauth_external: Update compatibility section with unknowns
Kim Alvefur <zash@zash.se>
parents:
5445
diff
changeset
|
90 |
--------- ----------------------------------------------- |
5348
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
91 |
trunk works |
5448
0c7abc81c243
mod_auth_oauth_external: Update compatibility section with unknowns
Kim Alvefur <zash@zash.se>
parents:
5445
diff
changeset
|
92 |
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:
5445
diff
changeset
|
93 |
0.11.x OAUTHBEARER will not work, otherwise untested |
5351
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5350
diff
changeset
|
94 |
|
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5350
diff
changeset
|
95 |
## Identity Provider |
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5350
diff
changeset
|
96 |
|
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5350
diff
changeset
|
97 |
Tested with |
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5350
diff
changeset
|
98 |
|
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5350
diff
changeset
|
99 |
- [KeyCloak](https://www.keycloak.org/) |
5445
533808db6c18
mod_auth_oauth_external: Add Mastodon to README
Kim Alvefur <zash@zash.se>
parents:
5440
diff
changeset
|
100 |
- [Mastodon](https://joinmastodon.org/) |
5351
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5350
diff
changeset
|
101 |
|
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5350
diff
changeset
|
102 |
# Future work |
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5350
diff
changeset
|
103 |
|
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5350
diff
changeset
|
104 |
- Automatically discover endpoints from Discovery URL |
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5350
diff
changeset
|
105 |
- Configurable input username mapping (e.g. user → user@host). |
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5350
diff
changeset
|
106 |
- [SCRAM over HTTP?!][rfc7804] |