Authentication

Authentication is the process of verifying who a user is. SympAuthy handles this on behalf of your applications so they do not have to manage it themselves.

There are two kinds of authentication depending on who is trying to connect:

• End-user authentication — A person signs into a client application.
• Service account authentication — A non-interactive service authenticates itself to access protected resources.

End-user authentication

When an end-user wants to access a client application, they go through an authentication flow:

1. The client application redirects the user to SympAuthy.
2. The user proves their identity (see authentication methods below).
3. SympAuthy redirects the user back to the client application with proof of successful authentication.

For a detailed walkthrough of each step from the user's perspective, see How an Interactive Flow Works.

Authentication methods

SympAuthy supports two primary ways for an end-user to prove their identity, plus an optional multi-factor authentication step:

Email and password

The user enters the email address and password they registered with. This method must be explicitly enabled in the configuration using the by-mail environment.

Third-party providers

The user authenticates through an external service — such as Google — that SympAuthy trusts. This is often shown to users as a "Sign in with Google" button.

When the user chooses this method:

1. SympAuthy redirects them to the provider's login page.
2. The user authenticates on the provider's side.
3. The provider confirms the authentication to SympAuthy and shares basic user information (name, email, etc.).
4. SympAuthy redirects the user back to the client application.

The user never shares their provider password with SympAuthy or with the client application.

Supported providers

SympAuthy ships with built-in configurations for the following providers, which can be enabled directly from their Micronaut environment:

Provider	Environment
Google	google
Discord	discord

Any other OAuth 2-compatible service can also be configured manually. OpenID Connect (OIDC) providers — such as Google, Microsoft, Auth0, or Keycloak — can be configured with just an issuer URL and client credentials thanks to OIDC Discovery. Other OAuth2 providers require explicit endpoint URLs and claim mappings via the OAuth2 configuration.

For the full list of options, refer to the provider configuration section. For providers with built-in presets, see the well-known providers page.

Account merging

A user may authenticate with multiple methods over time — for example, first with email and password, then later with Google — while using the same email address for both.

When account merging is enabled, SympAuthy recognises that these are the same person and merges the two into a single account. The user ends up with one account regardless of the method they used to sign in. The merging is based on the configured identifier claims — any accounts that share the same value for an identifier claim are treated as the same person.

This behavior is controlled by the auth.user-merging-enabled configuration key. Refer to the configuration section for details.

Multi-factor authentication (MFA)

After proving their identity with one of the methods above, a user can be asked to complete an additional verification step — multi-factor authentication. This adds a second layer of security by requiring something the user has (a device) on top of something they know (a password) or trust (a provider).

TOTP

SympAuthy supports TOTP (Time-based One-Time Password, RFC 6238) as an MFA method. The user registers a TOTP secret with an authenticator app — such as Google Authenticator or Authy — and then enters a 6-digit code generated by that app each time they sign in.

Two configuration keys control MFA behavior:

• mfa.totp.enabled — enables TOTP as an available MFA method.
• mfa.required — when true, every user must complete MFA before the flow can proceed. When false, unenrolled users may skip the step, but users who have already enrolled in an MFA method must complete it.

When a user signs in for the first time after TOTP is enabled, they go through an enrollment screen: they scan a QR code (or enter a secret manually), then confirm the setup by entering a first valid code. On subsequent sign-ins, they are presented with a challenge screen where they simply enter the current code from their authenticator app.

For a step-by-step description of how MFA fits into the authentication flow, see How an Interactive Flow Works. Refer to the configuration section for the full list of MFA options.

Service account authentication

A service account is used by a non-interactive service — such as a background job or a micro-service — that needs to authenticate itself to access protected resources, without any human user involved.

Service accounts authenticate using their client credentials (a client ID and a client secret) and receive a token that grants them the requested access.

For setup details, see the Client page.