Overview
OAuth (Open Authorization) is an open standard for token-based authentication and authorization between applications and services. It allows third-party applications to act on a user's behalf without holding the user's password, using short-lived access tokens issued by an authorization server.
Authorization Flows
OAuth 2.0 defines several authorization flows designed to accommodate different types of clients and use cases. Each flow provides a secure mechanism for obtaining an access token that grants permission to access resources on behalf of a user.
Tokens
OAuth tokens are the mechanism by which OAuth 2.0 grants access to protected resources. Instead of sending a username and password on every request, clients present tokens issued by the authorization server; each token has a defined scope and lifespan, which bounds what a compromised token can do.
Dynamic Registration
The OAuth Dynamic Client Registration Protocol (RFC 7591) extends OAuth 2.0 so that clients can register with an authorization server without administrator intervention. In a pre-registration model, each client id and secret is created manually; dynamic registration is well suited to environments where many applications or devices need to connect, such as cloud services or IoT deployments.
Interoperability
OAuth is widely used in web-based applications to provide secure, token-based authentication and authorization. In Stalwart, OAuth can be used to access JMAP as well as the WebUI and self-service portal, which are web-based interfaces that natively support OAuth flows. This usage matches the typical OAuth pattern: users authenticate through a browser, and the application exchanges authorization artefacts for access tokens with the OAuth server.
Endpoints
Stalwart exposes several OAuth endpoints that clients use to obtain access tokens, authorize devices, and validate tokens. The endpoint behaviour is governed by the OidcProvider singleton (found in the WebUI under Settings › Authentication › OIDC Provider), which defines token lifetimes, the authorization-code retry limit, and related policy.
OAuth Clients
An OAuth client is an application or service that requests access tokens from the Stalwart OAuth server on behalf of a user. Every client that participates in an OAuth flow is identified by a client id and, for confidential clients, a client secret. Registered clients are stored on the server so that redirect URIs, contact information, and secrets can be validated against a known record before tokens are issued.