Mercurial > prosody-modules

annotate mod_auth_oauth_external/README.md @ 5668:ecfd7aece33b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_measure_modules: Report module statuses via OpenMetrics Someone in the chat asked about a health check endpoint, which reminded me of mod_http_status, which provides access to module statuses with full details. After that, this idea came about, which seems natural. As noted in the README, it could be used to monitor that critical modules are in fact loaded correctly. As more modules use the status API, the more useful this module and mod_http_status becomes.
author Kim Alvefur <zash@zash.se>
date Fri, 06 Oct 2023 18:34:39 +0200
parents 27d220b14d59
children 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
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`
5499
27d220b14d59 mod_auth_oauth_external: Correct docs about default scope
Kim Alvefur <zash@zash.se>
parents: 5444
diff changeset
82 : 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
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]