Software /
code /
prosody-modules
Changeset
5313:80ecba092027
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 (21 months ago) |
parents | 5312:22e6b9f09439 |
children | 5314:7c123d3285de |
files | mod_http_oauth2/README.markdown |
diffstat | 1 files changed, 109 insertions(+), 9 deletions(-) [+] |
line wrap: on
line diff
--- a/mod_http_oauth2/README.markdown Thu Apr 06 16:10:27 2023 +0100 +++ b/mod_http_oauth2/README.markdown Thu Apr 06 17:24:16 2023 +0100 @@ -8,15 +8,92 @@ - html ... -Introduction -============ +## Introduction + +This module implements an OAuth2/OpenID Connect (OIDC) provider HTTP frontend +on top of Prosody's usual internal authentication backend. + +OAuth and OIDC are web standards that allow you to provide clients and +third-party applications limited access to your account, without sharing your +password with them. + +With this module deployed, software that supports OAuth can obtain "access +tokens" from Prosody which can then be used to connect to XMPP accounts using +the 'OAUTHBEARER' SASL mechanism or via non-XMPP interfaces such as mod_rest. + +Although this module has been around for some time, it has recently been +significantly extended and largely rewritten to support OAuth/OIDC more fully. -This module is a work-in-progress intended for developers only! +As of April 2023, it should be considered **alpha** stage. It works, we have +tested it, but it has not yet seen wider review, testing and deployment. At +this stage we recommend it for experimental and test deployments only. For +specific information, see the [deployment notes section](#deployment-notes) +below. + +Known client implementations: + +- *(we need you!)* + +Support for OAUTHBEARER has been added to the Lua XMPP library, [verse](https://code.matthewwild.co.uk/verse). +If you know of additional implementations, or are motivated to work on one, +please let us know! We'd be happy to help (e.g. by providing a test server). + +## Standards support + +Notable supported standards: + +- [RFC 6749: The OAuth 2.0 Authorization Framework](https://www.rfc-editor.org/rfc/rfc6749) +- [RFC 7628: A Set of Simple Authentication and Security Layer (SASL) Mechanisms for OAuth](https://www.rfc-editor.org/rfc/rfc7628) +- [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html) +- [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) +- [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) + +## Configuration -Configuration -============= +### Interface + +The module presents a web page to users to allow them to authenticate when +a client requests access. Built-in pages are provided, but you may also theme +or entirely override them. + +This module honours the 'site_name' configuration option that is also used by +a number of other modules: + +```lua +site_name = "My XMPP Server" +``` + +To provide custom templates, specify the path to the template directory: + +```lua +oauth2_template_path = "/etc/prosody/custom-oauth2-templates" +``` + +Some templates support additional variables, that can be provided by the +'oauth2_template_style' option: -Dynamic client registration enabled by configuring a JWT key. Algorithm +```lua +oauth2_template_style = { + background_colour = "#ffffff"; +} +``` + +### Token parameters + +The following options configure the lifetime of tokens issued by the module. +The defaults are recommended. + +```lua +oauth2_access_token_ttl = 86400 -- 24 hours +oauth2_refresh_token_ttl = nil -- unlimited unless revoked by the user +``` + +### Dynamic client registration + +To allow users to connect any compatible software, you should enable dynamic +client registration. + +Dynamic client registration can be enabled by configuring a JWT key. Algorithm defaults to *HS256*. ```lua @@ -25,6 +102,8 @@ oauth2_registration_options = { default_ttl = 60 * 60 * 24 * 90 } ``` +### Supported flows + Various flows can be disabled and enabled with `allowed_oauth2_grant_types` and `allowed_oauth2_response_types`: @@ -40,8 +119,29 @@ } ``` +## Deployment notes -Compatibility -============= +### Access management + +This module does not provide an interface for users to manage what they have +granted access to their account! (e.g. to view and revoke clients they have +previously authorized). It is recommended to join this module with +mod_client_management to provide such access. However, at the time of writing, +no XMPP clients currently support the protocol used by that module. We plan to +work on additional interfaces in the future. + +### Scopes -Requires Prosody 0.12+ or trunk. +OAuth supports "scopes" as a way to grant clients limited access. + +There are currently no standard scopes defined for XMPP. This is something +that we intend to change, e.g. by definitions provided in a future XEP. This +means that clients you authorize currently have unrestricted access to your +account (including the ability to change your password and lock you out!). So, +for now, while using OAuth clients can prevent leaking your password to them, +it is not currently suitable for connecting untrusted clients to your account. + +## Compatibility + +Requires Prosody trunk (April 2023), **not** compatible with Prosody 0.12 or +earlier.