Overview

OAuth 2.0 (RFC 6749) lets an application act on behalf of a user without ever holding the user’s password. Instead of asking for the password, the application sends the user to an authorization server. The user signs in there and approves the request, and the application receives two tokens in return. The access token is presented to the server on each request, in place of a password. The refresh token is kept by the application and exchanged for a new access token whenever the current one expires, so the user does not have to sign in again. OpenID Connect builds on this exchange and adds a third token, the ID token, which tells the application who signed in.

Stalwart includes an OAuth 2.0 authorization server and an OpenID Connect provider. The tokens it issues are accepted on every protocol it serves: JMAP, IMAP, POP3, SMTP submission, ManageSieve, CalDAV, CardDAV, WebDAV and the management API. Three kinds of application rely on it:

• Mail, calendar and contacts applications use it to sign in without storing a password.
• The WebUI uses it for every sign-in.
• Third-party applications use it to obtain limited access to an account.

The server works without any configuration. Its defaults implement the OAuth Profile for Open Public Clients, a specification that defines how a mail application can obtain tokens from a server it has never been registered with. The PACC discovery document advertises this support to mail clients, so that they can find and use it on their own.

Clients

Every application that requests tokens is an OAuth client, and each client is identified by a client id. Stalwart issues tokens only to clients it can identify. It recognises a client id in one of five forms:

• A dynamically registered client, whose id starts with swc1.. Mail applications obtain such an id from the registration endpoint without any credentials, and the server stores nothing for it.
• A registered client. This is an OAuthClient object that an administrator has created, for example for a third-party web application that authenticates with a client secret.
• A first-party registered client. This is an OAuthClient that a superuser has marked as first party, and its tokens carry the account’s full permissions. A superuser is an administrator outside any tenant who holds the impersonate permission.
• An installed web application, such as the WebUI. The server recognises it from the oauth-client.json document in its bundle.
• A Client ID Metadata Document. This is an https URL that serves a description of the client, and the server accepts it when its policy allows.

Any other client id is refused with invalid_client, so tokens are never issued to an unknown client. OAuth clients describes each kind and how they differ.

User consent

When an application requests access, the user’s browser opens the server’s sign-in page. After the user signs in, the page shows a consent screen for every application except installed web applications such as the WebUI. The screen names the application and the access it requests, and the application receives access only after the user allows it.

Each authorization creates a grant, the server’s record that this user allowed this application. While a grant covers what the application asks for, later sign-ins skip the consent screen. Users review their grants in the Account Manager under Connected Applications, and revoking a grant there signs the application out. Consent and connected applications describes the consent screen and the grants.

Settings

The settings of the authorization server are fields of the OidcProvider singleton (found in the WebUI under Settings › Authentication › OIDC Provider). They cover the token lifetimes, the key that encrypts tokens, the key that signs OpenID Connect ID tokens, and the policy for Client ID Metadata Documents.

Registered clients are OAuthClient objects (found in the WebUI under Management › Directory › OAuth Clients).

A fresh installation generates both keys. No other setting has to change before mail applications or the WebUI can sign in.

External identity providers

Stalwart can also rely on an external OpenID Connect provider, such as a corporate identity platform, for some or all of its domains. The accounts of a domain served by an OpenID Connect directory authenticate at that provider. The provider then acts as the authorization server, and Stalwart only validates the tokens the provider issues.

The two roles are independent of each other. The built-in server keeps serving the domains that use the internal, LDAP or SQL directory, while the external provider serves its own domains.

Stalwart never brokers sign-ins on behalf of an external provider. A native mail application registers with the provider and requests its tokens there, which means that the provider must itself implement the OAuth Profile for Open Public Clients for these applications to work. Most providers do not yet implement it in full. OpenID Connect directory describes the consequences, and the compatibility settings that let web clients such as the WebUI sign in regardless.