Mercurial > prosody-modules

comparison mod_http_oauth2/README.markdown @ 5313:80ecba092027

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_http_oauth2: README: Updated documentation to reflect module status
author Matthew Wild <mwild1@gmail.com>
date Thu, 06 Apr 2023 17:24:16 +0100
parents 3235b8bd1e55
children 8501baa7ef3f
comparison
equal deleted inserted replaced
5312:22e6b9f09439 5313:80ecba092027
6 build: 6 build:
7 copy_directories: 7 copy_directories:
8 - html 8 - html
9 ... 9 ...
10 10
11 Introduction 11 ## Introduction
12 ============
13 12
14 This module is a work-in-progress intended for developers only! 13 This module implements an OAuth2/OpenID Connect (OIDC) provider HTTP frontend
14 on top of Prosody's usual internal authentication backend.
15 15
16 Configuration 16 OAuth and OIDC are web standards that allow you to provide clients and
17 ============= 17 third-party applications limited access to your account, without sharing your
18 password with them.
18 19
19 Dynamic client registration enabled by configuring a JWT key. Algorithm 20 With this module deployed, software that supports OAuth can obtain "access
21 tokens" from Prosody which can then be used to connect to XMPP accounts using
22 the 'OAUTHBEARER' SASL mechanism or via non-XMPP interfaces such as mod_rest.
23
24 Although this module has been around for some time, it has recently been
25 significantly extended and largely rewritten to support OAuth/OIDC more fully.
26
27 As of April 2023, it should be considered **alpha** stage. It works, we have
28 tested it, but it has not yet seen wider review, testing and deployment. At
29 this stage we recommend it for experimental and test deployments only. For
30 specific information, see the [deployment notes section](#deployment-notes)
31 below.
32
33 Known client implementations:
34
35 - *(we need you!)*
36
37 Support for OAUTHBEARER has been added to the Lua XMPP library, [verse](https://code.matthewwild.co.uk/verse).
38 If you know of additional implementations, or are motivated to work on one,
39 please let us know! We'd be happy to help (e.g. by providing a test server).
40
41 ## Standards support
42
43 Notable supported standards:
44
45 - [RFC 6749: The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749)
46 - [RFC 7628: A Set of Simple Authentication and Security Layer (SASL) Mechanisms for OAuth](https://www.rfc-editor.org/rfc/rfc7628)
47 - [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)
48 - [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html) & [RFC 7591: OAuth 2.0 Dynamic Client Registration](https://www.rfc-editor.org/rfc/rfc7591.html)
49 - [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html)
50
51 ## Configuration
52
53 ### Interface
54
55 The module presents a web page to users to allow them to authenticate when
56 a client requests access. Built-in pages are provided, but you may also theme
57 or entirely override them.
58
59 This module honours the 'site_name' configuration option that is also used by
60 a number of other modules:
61
62 ```lua
63 site_name = "My XMPP Server"
64 ```
65
66 To provide custom templates, specify the path to the template directory:
67
68 ```lua
69 oauth2_template_path = "/etc/prosody/custom-oauth2-templates"
70 ```
71
72 Some templates support additional variables, that can be provided by the
73 'oauth2_template_style' option:
74
75 ```lua
76 oauth2_template_style = {
77 background_colour = "#ffffff";
78 }
79 ```
80
81 ### Token parameters
82
83 The following options configure the lifetime of tokens issued by the module.
84 The defaults are recommended.
85
86 ```lua
87 oauth2_access_token_ttl = 86400 -- 24 hours
88 oauth2_refresh_token_ttl = nil -- unlimited unless revoked by the user
89 ```
90
91 ### Dynamic client registration
92
93 To allow users to connect any compatible software, you should enable dynamic
94 client registration.
95
96 Dynamic client registration can be enabled by configuring a JWT key. Algorithm
20 defaults to *HS256*. 97 defaults to *HS256*.
21 98
22 ```lua 99 ```lua
23 oauth2_registration_key = "securely generated JWT key here" 100 oauth2_registration_key = "securely generated JWT key here"
24 oauth2_registration_algorithm = "HS256" 101 oauth2_registration_algorithm = "HS256"
25 oauth2_registration_options = { default_ttl = 60 * 60 * 24 * 90 } 102 oauth2_registration_options = { default_ttl = 60 * 60 * 24 * 90 }
26 ``` 103 ```
104
105 ### Supported flows
27 106
28 Various flows can be disabled and enabled with 107 Various flows can be disabled and enabled with
29 `allowed_oauth2_grant_types` and `allowed_oauth2_response_types`: 108 `allowed_oauth2_grant_types` and `allowed_oauth2_response_types`:
30 109
31 ```lua 110 ```lua
38 "code"; -- authorization code flow 117 "code"; -- authorization code flow
39 -- "token"; -- implicit flow disabled by default 118 -- "token"; -- implicit flow disabled by default
40 } 119 }
41 ``` 120 ```
42 121
122 ## Deployment notes
43 123
44 Compatibility 124 ### Access management
45 =============
46 125
47 Requires Prosody 0.12+ or trunk. 126 This module does not provide an interface for users to manage what they have
127 granted access to their account! (e.g. to view and revoke clients they have
128 previously authorized). It is recommended to join this module with
129 mod_client_management to provide such access. However, at the time of writing,
130 no XMPP clients currently support the protocol used by that module. We plan to
131 work on additional interfaces in the future.
132
133 ### Scopes
134
135 OAuth supports "scopes" as a way to grant clients limited access.
136
137 There are currently no standard scopes defined for XMPP. This is something
138 that we intend to change, e.g. by definitions provided in a future XEP. This
139 means that clients you authorize currently have unrestricted access to your
140 account (including the ability to change your password and lock you out!). So,
141 for now, while using OAuth clients can prevent leaking your password to them,
142 it is not currently suitable for connecting untrusted clients to your account.
143
144 ## Compatibility
145
146 Requires Prosody trunk (April 2023), **not** compatible with Prosody 0.12 or
147 earlier.