prosody-modules
ff539f34769f
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 @ 5348:ff539f34769f

mod_auth_oauth_external: Linkify password grant
author Kim Alvefur <zash@zash.se>
date Sat, 15 Apr 2023 10:46:04 +0200
parent 5347:a0074038696f
child 5349:ac9710126e1a
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
5346
d9bc8712a745 mod_auth_oauth_external: Allow setting identity instead of discovery URL
Kim Alvefur <zash@zash.se>
parents: 5345
diff changeset
23 `oauth_external_issuer`
d9bc8712a745 mod_auth_oauth_external: Allow setting identity instead of discovery URL
Kim Alvefur <zash@zash.se>
parents: 5345
diff changeset
24 : 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
25
5344
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
26 `oauth_external_discovery_url`
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
27 : 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
28 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
29 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
30 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
31 set, otherwise empty.
5344
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
32
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
33 `oauth_external_validation_endpoint`
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
34 : 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
35 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
36 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
37 Commonly the [OpenID `UserInfo`
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
38 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
39
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
40 `oauth_external_username_field`
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
41 : 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
42 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
43 localpart.
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
44
5345
3390bb2f9f6c mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents: 5344
diff changeset
45 ## For SASL PLAIN
3390bb2f9f6c mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents: 5344
diff changeset
46
3390bb2f9f6c mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents: 5344
diff changeset
47 `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
48 : 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
49 [resource owner password
ff539f34769f mod_auth_oauth_external: Linkify password grant
Kim Alvefur <zash@zash.se>
parents: 5347
diff changeset
50 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
51
3390bb2f9f6c mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents: 5344
diff changeset
52 `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
53 : 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
54 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
55 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
56
3390bb2f9f6c mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents: 5344
diff changeset
57 `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
58 : 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
59 password grant.
3390bb2f9f6c mod_auth_oauth_external: Support PLAIN via resource owner password grant
Kim Alvefur <zash@zash.se>
parents: 5344
diff changeset
60
5344
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
61 # Compatibility
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
62
5347
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
63 ## Prosody
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
64
5344
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
65 Version Status
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
66 --------- ---------------
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
67 trunk works
0a6d2b79a8bf mod_auth_oauth_external: Authenticate against an OAuth 2 provider
Kim Alvefur <zash@zash.se>
parents:
diff changeset
68 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
69 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
70
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
71 ## Identity Provider
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
72
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
73 Tested with
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
74
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
75 - [KeyCloak](https://www.keycloak.org/)
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
76
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
77 # Future work
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
78
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
79 - Automatically discover endpoints from Discovery URL
a0074038696f mod_auth_oauth_external: Some notes in README
Kim Alvefur <zash@zash.se>
parents: 5346
diff changeset
80 - 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
81 - [SCRAM over HTTP?!][rfc7804]