Authorization

This page covers authentication and authorization configuration: identity settings, token behaviour, feature flags, MFA, interactive flows, third-party providers, and scope granting rules.

auth

Key	Type	Description	Required Default
issuer	string	The public URL of this authorization server, embedded as the iss claim in every JWT token it issues. Clients use it to verify that a token was issued by the expected server and to discover the OpenID Connect configuration at <issuer>/.well-known/openid-configuration.	YES <urls.root>
identifier-claims	array of string	List of claim identifiers that uniquely identify a person. These claims are used as the login identifier for password authentication and, when user-merging-enabled is true, as the key for merging accounts across authentication methods.	NO []
user-merging-enabled	boolean	When true, accounts that share the same value for any configured identifier-claims are automatically merged across authentication methods (password, third-party providers). When false, each authentication method creates a separate account.	NO false
authorization-code	object	Configuration for the authorization code grant flow. See auth.authorization-code for more details.	NO
token	object	Configuration related to authentication tokens issued by this app. See auth.token for more details.	NO

auth.authorization-code

Key	Type	Description	Required Default
expiration	duration	Maximum duration an authorization attempt is valid before it expires. The end-user must complete the entire authorization flow (sign-in, claims collection, MFA, etc.) within this time.	YES 30m

auth.by-password

Key	Type	Description	Required Default
enabled	boolean	Enable password-based authentication.	NO false

auth.token

Key	Type	Description	Required Default
access-expiration	duration	Amount of time the end-user can be considered authenticated after the access token has been issued.	YES 1h
dpop-required	boolean	When true, all token requests must include a DPoP proof. When false, DPoP is opt-in: clients may send a proof to receive a sender-constrained token, or omit it to receive a bearer token.	NO false
refresh-enabled	boolean	If set to true, this app will issue refresh tokens that can be used to obtain a new access token without the end-user having to go through the authentication flow.	YES true
refresh-expiration	duration	Amount of time the refresh token can be used to obtain an access token after it has been issued. The refresh token will never expire if this key is not present.	NO

features

This section holds configuration related to features that can be enabled or disabled.

Key	Type	Description	Required Default
allow-access-to-client-without-scope	boolean	Allow the end-user to be redirected back to the client application even when none of the requested authorization scopes have been granted	NO false
email-validation	boolean	Enforce the validation of the end-user's emails. A SMTP must be configured (see Mail) to enable this feature.	NO false
grant-unhandled-scopes	boolean	⚠️ UNSAFE - DEVELOPMENT ONLY. Automatically grant ALL grantable scopes requested by the client that are not explicitly granted nor declined by any scope granting rule. When enabled: Any grantable scope not explicitly granted nor declined is automatically granted. When disabled: Grantable scopes not explicitly granted are rejected (secure default). This feature only applies to grantable scopes. Consentable scopes always require end-user consent and client scopes have their own granting rules. To know more about scope granting rules, see this documentation.	NO false

mfa

This section controls multi-factor authentication (MFA). MFA adds an extra verification step after the user has authenticated with their primary method (password or third-party provider).

Key	Type	Description	Required Default
required	boolean	When true, every user must complete MFA before the flow can proceed. When false, users may skip MFA.	NO false
totp.enabled	boolean	Enable TOTP (Time-based One-Time Password, RFC 6238) as an MFA method.	NO false

When mfa.totp.enabled is true, the corresponding flow URLs (mfa, mfa-totp-enroll, mfa-totp-challenge) must be configured in the flows.<id> section. SympAuthy validates this at startup and refuses to start if any required URL is missing.

flows.<id>

This configuration holds the URL where the end-user will be redirected during its authentication. Sympathy already includes a complete authentication flow.

Web

The flow may be completely customized and served by a completely different server than the authorization server.

SympAuthy derives the allowed CORS origins for the Flow API (/api/v1/flow/**) from the URIs declared here. For each URI, the origin (scheme://host:port) is extracted and whitelisted. Requests from any other origin are refused. See the Security documentation for details.

Key	Type	Description	Required Default
error	uri	The URL where the end-user will be redirected if an error occurs during the authentication.	YES /error
mfa	uri	The URL of the MFA router/method-selection page.	NO
mfa-totp-challenge	uri	The URL of the TOTP challenge page.	NO
mfa-totp-enroll	uri	The URL of the TOTP enrollment page.	NO
sign-in	uri	The URL where the end-user will be enabled to sign-in using any supported methods (password or third party providers).	YES /sign-in
sign-up	uri	The URL of the sign-up page. Required when sign-up-enabled or invitation-enabled is true on any audience.	NO

The mfa, mfa-totp-enroll, and mfa-totp-challenge URLs are required when mfa.totp.enabled is true. SympAuthy validates this at startup and fails fast if they are missing.

rules

This section holds the configuration of scope granting rules.

Key	Type	Description	Required Default
user	array of object	Scope granting rules evaluated during authorization_code flows to grant or deny grantable scopes. Expressions evaluate user claims using CLAIM(...) and CLAIM_IS_VERIFIED(...).	NO
client	array of object	Scope granting rules evaluated during client_credentials flows to grant or deny client scopes. Expressions evaluate client attributes using CLIENT(...).	NO

rules.user / rules.client

Both user and client arrays share the same rule structure:

Key	Type	Description	Required Default
scopes	array of string	Scopes affected by this rule. Only requested scopes that appear in this list are granted or denied.	YES
behavior	string	grant to include the scopes in tokens, deny to exclude them.	YES
order	int	Precedence when multiple rules affect the same scope. A matched rule with greater order overrides matched rules of lower order. A matched deny rule always wins over grant rules of same or lower order.	NO 0
expressions	array of string	Conditions that must all evaluate to true for the rule to match.	YES

Example:

rules:
  user:
    - scopes:
        - admin:config:read
        - admin:users:read
        - admin:users:write
      behavior: grant
      order: 0
      expressions:
        - CLAIM("email") = "admin@example.com" && CLAIM_IS_VERIFIED("email")
  client:
    - scopes:
        - users:claims:write
      behavior: grant
      order: 0
      expressions:
        - CLIENT("name") = "backoffice"