Mercurial > prosody-modules
annotate mod_auth_oauth_external/README.md @ 5401:c8d04ac200fc
mod_http_oauth2: Reject loopback URIs as client_uri
This really should be a proper website with info, https://localhost is
not good enough. Ideally we'd validate that it's got proper DNS and is
actually reachable, but triggering HTTP or even DNS lookups seems like
it would carry abuse potential that would best to avoid.
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Tue, 02 May 2023 16:20:55 +0200 |
parents | ac9710126e1a |
children | 92ad8f03f225 |
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) |
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
53 |
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
54 `oauth_external_username_field` |
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
55 : 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
|
56 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
|
57 localpart. |
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
58 |
5345
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5344
diff
changeset
|
59 ## For SASL PLAIN |
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5344
diff
changeset
|
60 |
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5344
diff
changeset
|
61 `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
|
62 : 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
|
63 [resource owner password |
ff539f34769f
mod_auth_oauth_external: Linkify password grant
Kim Alvefur <zash@zash.se>
parents:
5347
diff
changeset
|
64 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
|
65 |
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5344
diff
changeset
|
66 `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
|
67 : 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
|
68 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
|
69 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
|
70 |
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5344
diff
changeset
|
71 `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
|
72 : 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
|
73 password grant. |
3390bb2f9f6c
mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents:
5344
diff
changeset
|
74 |
5344
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
75 # Compatibility |
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
76 |
5347
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5346
diff
changeset
|
77 ## Prosody |
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5346
diff
changeset
|
78 |
5344
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
79 Version Status |
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
80 --------- --------------- |
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
81 trunk works |
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
82 0.12.x does not work |
0a6d2b79a8bf
mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff
changeset
|
83 0.11.x does not work |
5347
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5346
diff
changeset
|
84 |
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5346
diff
changeset
|
85 ## Identity Provider |
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5346
diff
changeset
|
86 |
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5346
diff
changeset
|
87 Tested with |
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5346
diff
changeset
|
88 |
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5346
diff
changeset
|
89 - [KeyCloak](https://www.keycloak.org/) |
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5346
diff
changeset
|
90 |
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5346
diff
changeset
|
91 # Future work |
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5346
diff
changeset
|
92 |
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5346
diff
changeset
|
93 - Automatically discover endpoints from Discovery URL |
a0074038696f
mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents:
5346
diff
changeset
|
94 - 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
|
95 - [SCRAM over HTTP?!][rfc7804] |