Software /
code /
prosody-modules
Annotate
mod_auth_oauth_external/README.md @ 5450:d2594bbf7c36
mod_http_oauth2: Scope FIXMEs
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Thu, 11 May 2023 21:43:23 +0200 |
parent | 5444:0c7abc81c243 |
child | 5499:27d220b14d59 |
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 |
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
7 This module provides external authentication via an external [AOuth |
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 |
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 |
5345
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5344
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:
5344
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:
5344
diff
changeset
|
20 |
5344
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 |
5349
ac9710126e1a
mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents:
5348
diff
changeset
|
23 ## Example |
ac9710126e1a
mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents:
5348
diff
changeset
|
24 |
ac9710126e1a
mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents:
5348
diff
changeset
|
25 ```lua |
ac9710126e1a
mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents:
5348
diff
changeset
|
26 -- authentication = "oauth_external" |
ac9710126e1a
mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents:
5348
diff
changeset
|
27 |
ac9710126e1a
mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents:
5348
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:
5348
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:
5348
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:
5348
diff
changeset
|
31 oauth_external_username_field = "xmpp_username" |
ac9710126e1a
mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents:
5348
diff
changeset
|
32 ``` |
ac9710126e1a
mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents:
5348
diff
changeset
|
33 |
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 ## Common |
ac9710126e1a
mod_auth_oauth_external: Add configuration example
Kim Alvefur <zash@zash.se>
parents:
5348
diff
changeset
|
36 |
5346
d9bc8712a745
mod_auth_oauth_external: Allow setting identity instead of discovery URL
Kim Alvefur <zash@zash.se>
parents:
5345
diff
changeset
|
37 `oauth_external_issuer` |
d9bc8712a745
mod_auth_oauth_external: Allow setting identity instead of discovery URL
Kim Alvefur <zash@zash.se>
parents:
5345
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:
5345
diff
changeset
|
39 |
5344
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 |
5346
d9bc8712a745
mod_auth_oauth_external: Allow setting identity instead of discovery URL
Kim Alvefur <zash@zash.se>
parents:
5345
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:
5345
diff
changeset
|
45 set, otherwise empty. |
5344
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) |
5434
92ad8f03f225
mod_auth_oauth_external: Work without token validation endpoint
Kim Alvefur <zash@zash.se>
parents:
5349
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:
5349
diff
changeset
|
54 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
|
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 |
5345
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5344
diff
changeset
|
61 ## For SASL PLAIN |
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5344
diff
changeset
|
62 |
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5344
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:
5344
diff
changeset
|
64 : 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
|
65 [resource owner password |
ff539f34769f
mod_auth_oauth_external: Linkify password grant
Kim Alvefur <zash@zash.se>
parents:
5347
diff
changeset
|
66 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
|
67 |
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5344
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:
5344
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:
5344
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:
5344
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:
5344
diff
changeset
|
72 |
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5344
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:
5344
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:
5344
diff
changeset
|
75 password grant. |
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5344
diff
changeset
|
76 |
5435
b3e7886fea6a
mod_auth_oauth_external: Add setting for client_secret
Kim Alvefur <zash@zash.se>
parents:
5434
diff
changeset
|
77 `oauth_external_client_secret` |
b3e7886fea6a
mod_auth_oauth_external: Add setting for client_secret
Kim Alvefur <zash@zash.se>
parents:
5434
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:
5434
diff
changeset
|
79 owner password grant. |
b3e7886fea6a
mod_auth_oauth_external: Add setting for client_secret
Kim Alvefur <zash@zash.se>
parents:
5434
diff
changeset
|
80 |
5436
e7d99bacd0e8
mod_auth_oauth_external: Make 'scope' configurable in password grant request
Kim Alvefur <zash@zash.se>
parents:
5435
diff
changeset
|
81 `oauth_external_scope` |
e7d99bacd0e8
mod_auth_oauth_external: Make 'scope' configurable in password grant request
Kim Alvefur <zash@zash.se>
parents:
5435
diff
changeset
|
82 : String. Defaults to `"oauth"`. Included in request for resource |
e7d99bacd0e8
mod_auth_oauth_external: Make 'scope' configurable in password grant request
Kim Alvefur <zash@zash.se>
parents:
5435
diff
changeset
|
83 owner password grant. |
e7d99bacd0e8
mod_auth_oauth_external: Make 'scope' configurable in password grant request
Kim Alvefur <zash@zash.se>
parents:
5435
diff
changeset
|
84 |
5344
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 |
5347
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5346
diff
changeset
|
87 ## Prosody |
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5346
diff
changeset
|
88 |
5344
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
89 Version Status |
5444
0c7abc81c243
mod_auth_oauth_external: Update compatibility section with unknowns
Kim Alvefur <zash@zash.se>
parents:
5441
diff
changeset
|
90 --------- ----------------------------------------------- |
5344
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
91 trunk works |
5444
0c7abc81c243
mod_auth_oauth_external: Update compatibility section with unknowns
Kim Alvefur <zash@zash.se>
parents:
5441
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:
5441
diff
changeset
|
93 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
|
94 |
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5346
diff
changeset
|
95 ## Identity Provider |
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 Tested with |
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 - [KeyCloak](https://www.keycloak.org/) |
5441
533808db6c18
mod_auth_oauth_external: Add Mastodon to README
Kim Alvefur <zash@zash.se>
parents:
5436
diff
changeset
|
100 - [Mastodon](https://joinmastodon.org/) |
5347
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5346
diff
changeset
|
101 |
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5346
diff
changeset
|
102 # Future work |
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 - Automatically discover endpoints from Discovery URL |
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5346
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:
5346
diff
changeset
|
106 - [SCRAM over HTTP?!][rfc7804] |