prosody-modules
1a6cd0bbb7ab
mod_http_oauth2/README.md

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

File

mod_http_oauth2/README.md @ 6110:1a6cd0bbb7ab

mod_compliance_2023: Add 2023 Version of the compliance module, basis is the 2021 Version. diff --git a/mod_compliance_2023/README.md b/mod_compliance_2023/README.md new file mode 100644 --- /dev/null +++ b/mod_compliance_2023/README.md @@ -0,0 +1,22 @@ +--- +summary: XMPP Compliance Suites 2023 self-test +labels: +- Stage-Beta +rockspec: + dependencies: + - mod_cloud_notify + +... + +Compare the list of enabled modules with +[XEP-0479: XMPP Compliance Suites 2023] and produce basic report to the +Prosody log file. + +If installed with the Prosody plugin installer then all modules needed for a green checkmark should be included. (With prosody 0.12 only [mod_cloud_notify] is not included with prosody and we need the community module) + +# Compatibility + + Prosody-Version Status + --------------- ---------------------- + trunk Works as of 2024-12-21 + 0.12 Works diff --git a/mod_compliance_2023/mod_compliance_2023.lua b/mod_compliance_2023/mod_compliance_2023.lua new file mode 100644 --- /dev/null +++ b/mod_compliance_2023/mod_compliance_2023.lua @@ -0,0 +1,79 @@ +-- Copyright (c) 2021 Kim Alvefur +-- +-- This module is MIT licensed. + +local hostmanager = require "core.hostmanager"; + +local array = require "util.array"; +local set = require "util.set"; + +local modules_enabled = module:get_option_inherited_set("modules_enabled"); + +for host in pairs(hostmanager.get_children(module.host)) do + local component = module:context(host):get_option_string("component_module"); + if component then + modules_enabled:add(component); + modules_enabled:include(module:context(host):get_option_set("modules_enabled", {})); + end +end + +local function check(suggested, alternate, ...) + if set.intersection(modules_enabled, set.new({suggested; alternate; ...})):empty() then return suggested; end + return false; +end + +local compliance = { + array {"Server"; check("tls"); check("disco")}; + + array {"Advanced Server"; check("pep", "pep_simple")}; + + array {"Web"; check("bosh"); check("websocket")}; + + -- No Server requirements for Advanced Web + + array {"IM"; check("vcard_legacy", "vcard"); check("carbons"); check("http_file_share", "http_upload")}; + + array { + "Advanced IM"; + check("vcard_legacy", "vcard"); + check("blocklist"); + check("muc"); + check("private"); + check("smacks"); + check("mam"); + check("bookmarks"); + }; + + array {"Mobile"; check("smacks"); check("csi_simple", "csi_battery_saver")}; + + array {"Advanced Mobile"; check("cloud_notify")}; + + array {"A/V Calling"; check("turn_external", "external_services", "turncredentials", "extdisco")}; + +}; + +function check_compliance() + local compliant = true; + for _, suite in ipairs(compliance) do + local section = suite:pop(1); + if module:get_option_boolean("compliance_" .. section:lower():gsub("%A", "_"), true) then + local missing = set.new(suite:filter(function(m) return type(m) == "string" end):map(function(m) return "mod_" .. m end)); + if suite[1] then + if compliant then + compliant = false; + module:log("warn", "Missing some modules for XMPP Compliance 2023"); + end + module:log("info", "%s Compliance: %s", section, missing); + end + end + end + + if compliant then module:log("info", "XMPP Compliance 2023: Compliant ✔️"); end +end + +if prosody.start_time then + check_compliance() +else + module:hook_global("server-started", check_compliance); +end +
author Menel <menel@snikket.de>
date Sun, 22 Dec 2024 16:06:28 +0100
parent 6003:fe081789f7b5
child 6211:750d64c47ec6
line wrap: on
line source

---
labels:
- Stage-Alpha
rockspec:
  build:
    copy_directories:
    - html
summary: OAuth 2.0 Authorization Server API
---

## Introduction

This module implements an [OAuth2](https://oauth.net/2/)/[OpenID Connect
(OIDC)](https://openid.net/connect/) Authorization Server 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][rfc7628] 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.

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:

-   [example shell script for mod_rest](https://hg.prosody.im/prosody-modules/file/tip/mod_rest/example/rest.sh)
-   *(we need you!)*

Support for [OAUTHBEARER][rfc7628] 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 7009: OAuth 2.0 Token Revocation](https://www.rfc-editor.org/rfc/rfc7009)
- [RFC 7591: OAuth 2.0 Dynamic Client Registration](https://www.rfc-editor.org/rfc/rfc7591.html)
- [RFC 7628: A Set of Simple Authentication and Security Layer (SASL) Mechanisms for OAuth](https://www.rfc-editor.org/rfc/rfc7628)
- [RFC 7636: Proof Key for Code Exchange by OAuth Public Clients](https://www.rfc-editor.org/rfc/rfc7636)
- [RFC 7662: OAuth 2.0 Token Introspection](https://www.rfc-editor.org/rfc/rfc7662)
- [RFC 8628: OAuth 2.0 Device Authorization Grant](https://www.rfc-editor.org/rfc/rfc8628)
- [RFC 9207: OAuth 2.0 Authorization Server Issuer Identification](https://www.rfc-editor.org/rfc/rfc9207.html)
- [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)
- [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html) (_partial, e.g. missing JWKS_)
- [OpenID Connect Dynamic Client Registration 1.0](https://openid.net/specs/openid-connect-registration-1_0.html)

## 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"
```

If you know what features your templates use use you can adjust the
`Content-Security-Policy` header to only allow what is needed:

```lua
oauth2_security_policy = "default-src 'self'" -- this is the default
```

### Token parameters

The following options configure the lifetime of tokens issued by the module.
The defaults are recommended.

```lua
oauth2_access_token_ttl = 3600 -- one hour
oauth2_refresh_token_ttl = 604800 -- one week
```

### 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*, lifetime defaults to forever.

```lua
oauth2_registration_key = "securely generated JWT key here"
oauth2_registration_algorithm = "HS256"
oauth2_registration_ttl = nil -- unlimited by default
```

Registering a client is described in
[RFC7591](https://www.rfc-editor.org/rfc/rfc7591.html).

In addition to the requirements in the RFC, the following requirements
are enforced:

`client_name`
:   **MUST** be present, is shown to users in consent screen.

`client_uri`
:   **MUST** be present and **MUST** be a `https://` URL.

`redirect_uris`

:   **MUST** contain at least one valid URI. Different rules apply
    depending on the value of `application_type`, see below.

`application_type`

:   Optional, defaults to `web`. Determines further restrictions for
    `redirect_uris`. The following values are supported:

    `web` *(default)*
    :   For web clients. With this, `redirect_uris` **MUST** be
        `https://` URIs and **MUST** use the same hostname part as the
        `client_uri`.

    `native`
    :   For native e.g. desktop clients etc. `redirect_uris` **MUST**
        match one of:

        -   Loopback HTTP URI, e.g. `http://127.0.0.1/` or
            `http://[::1]`
        -   Application-specific scheme, e.g. `com.example.app:/`
        -   The special OOB URI `urn:ietf:wg:oauth:2.0:oob`

`tos_uri`, `policy_uri`
:   Informative URLs pointing to Terms of Service and Service Policy
    document **MUST** use the same scheme (i.e. `https://`) and hostname
    as the `client_uri`.

#### Registration Examples

In short registration works by POST-ing a JSON structure describing your
client to an endpoint:

``` bash
curl -sSf https://xmpp.example.net/oauth2/register \
    -H Content-Type:application/json \
    -H Accept:application/json \
    --data '
{
   "client_name" : "My Application",
   "client_uri" : "https://app.example.com/",
   "redirect_uris" : [
      "https://app.example.com/redirect"
   ]
}
'
```

Another example with more fields:

``` bash
curl -sSf https://xmpp.example.net/oauth2/register \
    -H Content-Type:application/json \
    -H Accept:application/json \
    --data '
{
   "application_type" : "native",
   "client_name" : "Desktop Chat App",
   "client_uri" : "https://app.example.org/",
   "contacts" : [
      "support@example.org"
   ],
   "policy_uri" : "https://app.example.org/about/privacy",
   "redirect_uris" : [
      "http://localhost:8080/redirect",
      "org.example.app:/redirect"
   ],
   "scope" : "xmpp",
   "software_id" : "32a0a8f3-4016-5478-905a-c373156eca73",
   "software_version" : "3.4.1",
   "tos_uri" : "https://app.example.org/about/terms"
}
'
```

### Supported flows

-   Authorization Code grant, optionally with Proof Key for Code Exchange
-   Device Authorization Grant
-   Resource owner password grant *(disabled by default)*
-   Implicit flow *(disabled by default)*
-   Refresh Token grants

Various flows can be disabled and enabled with
`allowed_oauth2_grant_types` and `allowed_oauth2_response_types`:

```lua
-- These examples reflect the defaults
allowed_oauth2_grant_types = {
	"authorization_code"; -- authorization code grant
	"device_code";
	-- "password"; -- resource owner password grant disabled by default
}

allowed_oauth2_response_types = {
	"code"; -- authorization code flow
    -- "token"; -- implicit flow disabled by default
}
```

The [Proof Key for Code Exchange][RFC 7636] mitigation method is
required by default but can be made optional:

```lua
oauth2_require_code_challenge = false -- default is true
```

Further, individual challenge methods can be enabled or disabled:

```lua
-- These reflects the default
allowed_oauth2_code_challenge_methods = {
    -- "plain"; -- insecure but backwards-compatible
    "S256";
}
```

### Policy documents

Links to Terms of Service and Service Policy documents can be advertised
for use by OAuth clients:

```lua
oauth2_terms_url = "https://example.com/terms-of-service.html"
oauth2_policy_url = "https://example.com/service-policy.pdf"
-- These are unset by default
```

## Deployment notes

### 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

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 to
choose between unrestricted access to your account (including the
ability to change your password and lock you out!) and zero access. 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.

As a first step, the `xmpp` scope is supported, and corresponds to
whatever permissions the user would have when logged in over XMPP.

Further, known Prosody roles can be used as scopes.

OpenID scopes such as `openid` and `profile` can be used for "Login
with XMPP" without granting access to more than limited profile details.

## Compatibility

Requires Prosody trunk (April 2023), **not** compatible with Prosody 0.12 or
earlier.