Reference
OIDC directory
Short description of this directory.
On this page
Directory
Description
Short description of this directory.
Text. Name in the API: description.
Provider
Issuer URL
The base URL of the OpenID Connect provider (e.g. https://sso.example.com/realms/myrealm). The server will use this URL to automatically discover the provider's endpoints, including the token validation and user info endpoints.
An address (URL). Name in the API: issuerUrl.
Required Audience
The server rejects any token whose aud (audience) claim does not include this value. Set it to the client ID or resource identifier registered for this server in your identity provider, so tokens issued for other applications are not accepted. Required for a new directory; a directory saved before it was required keeps working without one, and logs a warning each time it loads.
Text. Name in the API: requireAudience.
Required Scopes
If set, the server will reject any token that does not include all of the specified scopes. Useful for ensuring that only tokens explicitly granted access to the mail server are accepted.
A list. Each one: text. Default: email, openid. Name in the API: requireScopes.
Opaque Tokens
Opaque Tokens
What to do with a bearer token that is not a JWT. reject refuses it. introspection asks the provider's token introspection endpoint (RFC 7662) with this directory's client credentials, and accepts the token only if it is active, was issued by this provider and carries the required audience. userinfo accepts it whenever the provider's user info endpoint does, which is true of any token the provider issued to any application. When not set: introspection if an introspection endpoint is set, otherwise reject. Directories saved before this setting existed use userinfo.
One of: Reject them (reject), Check them at the introspection endpoint (introspection), Accept them if the user info endpoint does (not recommended) (userinfo). Name in the API: opaqueTokens.
Introspection Endpoint
The provider's token introspection endpoint (RFC 7662). If not set, the endpoint from the provider's discovery document is used when opaque tokens are checked by introspection.
An address (URL). Name in the API: introspectionUrl.
Introspection Client ID
The client ID this server uses to call the introspection endpoint.
Text. Name in the API: introspectionClientId.
Introspection Client Secret
The client secret this server uses to call the introspection endpoint.
Settings of their own: see Secret key optional. Name in the API: introspectionClientSecret.
Claims
Username Claim
The claim name used to retrieve the user's login name from the token or user info response. Common values are preferred_username, email, or sub depending on your provider's configuration. If the claim value is not an email address and usernameDomain is set, the domain will be appended automatically (e.g. john becomes john@example.com). If the claim value already contains an @, it is used as-is. If the claim value is not an email address and no usernameDomain is configured, the server will fall back to the email claim. If neither yields a valid email address, authentication will be rejected.
Text. Default: preferred_username. Name in the API: claimUsername.
Username Domain
The domain name to append to the username when the value of claimUsername does not contain an @ symbol (e.g. setting this to example.com will turn john into john@example.com). If not set, the server will fall back to the email claim when the username claim does not contain a valid email address.
Text. Name in the API: usernameDomain.
Name Claim
The claim name used to retrieve the user's display name from the token or user info response. Common values are name or display_name. If not set, the display name will not be populated.
Text. Default: name. Name in the API: claimName.
Groups Claim
The claim name used to retrieve the user's group memberships from the token or user info response. Common values are groups or roles depending on your provider's configuration. If not set, group information will not be populated. Note that some providers omit group claims from the token to keep its size small and only return them via the user info endpoint, if group information is missing, ensure your provider is configured to include it.
Text. Name in the API: claimGroups.
Tenant
Identifier for the tenant this directory belongs to.
One of your Tenants, chosen from a list. Name in the API: memberTenantId.