Skip to main content

OpenID Connect

This section describes how to configure OpenID Connect (OIDC) authentication in Sync-in.

Sync-in implements the Authorization Code flow, in line with OAuth 2.0 recommendations for web applications.

Configuration lives in environment.yaml, see OIDC section.

Prerequisites​

Before enabling OIDC in Sync-in, an OAuth/OIDC client must be created in your identity provider (IdP).
Labels may vary depending on the provider, but the logic is similar.

Create an application (client)​

  • The provider type must be OpenID Connect.
  • The client type must be Confidential.
  • The application type must be Web.
  • The grant type must be Authorization Code.

This setup provides the client ID (clientId) and the associated secret (clientSecret) that you must copy into the configuration.

Configure redirect URIs​

Redirect URIs must be declared in the IdP.
They allow the IdP to redirect the user back to Sync-in after successful authentication.

Sign-in from a web browser​

For web UI authentication, declare the following URI:

  • https://DOMAIN:PORT/api/auth/oidc/callback
info

This URI corresponds to the redirectUri configuration parameter.
It must end with /api/auth/oidc/callback.

Sign-in from desktop applications​

Desktop applications use the system default browser to perform authentication.
After sign-in, the browser redirects the user to a local URI to pass the authentication result back to the application.

To allow this, declare the following local URIs:

  • http://127.0.0.1:49152/oidc/callback
  • http://127.0.0.1:49153/oidc/callback
  • http://127.0.0.1:49154/oidc/callback

This approach improves compatibility with IdPs and matches authentication mechanisms already deployed in enterprise environments (SSO, MFA, security policies, etc.).

info

When using OIDC, MFA is expected to be enforced by the identity provider. Sync-in does not add a local 2FA challenge after the OIDC callback. Sync-in 2FA remains configurable from the user profile during an OIDC session; enable, reset, and disable flows verify the local Sync-in password.

Configuration​

Minimal example:

auth:
  provider: oidc
  oidc:
    issuerUrl: 'https://auth.example.com/realms/my-realm'
    clientId: 'OIDCClientId'
    clientSecret: 'OIDCClientSecret'
    redirectUri: 'https://sync-in.domain.com/api/auth/oidc/callback'

⚠️ redirectUri must match exactly the URI declared in the IdP.

Authentication flow​

Two authentication methods are available on the Sync-in login screen.

Local authentication​

  • Guest accounts, administrator accounts, and accounts with application passwords can log in using their username and password.
  • For this login path, Sync-in local 2FA applies when it is enabled for the user.
  • Other users can use their local password only if:
    • options.enablePasswordAuth is enabled;
    • they know their local Sync-in password.
  • This setup preserves emergency administrative access without disabling OIDC authentication.

For this break-glass access to be usable, administrator accounts should have a local Sync-in password configured and kept available.

By default, local password authentication for regular OIDC users is disabled. Enable options.enablePasswordAuth only if you intentionally want to allow this fallback.

Users created through OIDC start with an internal random password. They can set a known local password from their profile while authenticated through OIDC. That password can then be used for local password authentication when enabled, and for password-fallback step-up when no TOTP secret is active. It is also required to enable, reset, or disable Sync-in 2FA from an OIDC browser session.

Application passwords​

Generating and revoking application passwords require the usual Sync-in step-up: TOTP when enabled, otherwise local password confirmation.

OpenID Connect (OIDC) authentication​

  • The user starts sign-in via the OIDC button.
  • They are redirected to the IdP to authenticate.
  • MFA, when required, is enforced by the identity provider during this step.
  • After validation, the user is automatically redirected back to Sync-in.
  • Sync-in retrieves user information and synchronizes the local account.
  • If no local account exists and autoCreateUser is enabled, a local account is created with a random password.
  • The administrator role is applied automatically if configured.
  • The storage quota is synchronized from options.storageQuotaClaim when the OIDC profile provides a valid value in bytes. An absent claim value or a claim value of 0 sets unlimited storage.

The OIDC profile must provide an email address. New accounts initialize their local login from preferred_username, then from the email local-part when preferred_username is absent. The login is assigned once and is not renamed on later OIDC logins.

Account binding and synchronization​

Sync-in uses the validated ID token sub claim as the stable external identity and stores it on the local user account. During login, accounts are resolved in this order:

  1. Match the stored external identity against the ID token sub.
  2. Fall back to email only for existing accounts that do not already have an external identity.
  3. Store the unchanged sub on that account after the first successful compatibility match.
  4. Create a new local account when no match exists and autoCreateUser is enabled.

Once an account is bound, email changes at the IdP no longer break login because Sync-in resolves the user by sub. If the derived login is already used during automatic account creation, Sync-in appends a deterministic suffix derived from sub; the raw sub value is not exposed in the login.

Existing users can have their email, first name, last name, role, storage quota, and avatar synchronized from OIDC. The local login, password, and permissions are not synchronized after account creation.

Administrator roles​

If options.adminRoleOrGroup is set, Sync-in checks whether this value is present in the groups or roles claims returned by the IdP. The administrator role is granted if a match is found.

If options.adminRoleOrGroup is not set, existing admin accounts keep their role and cannot be demoted via OIDC.

Availability and errors​

Configuration errors or IdP access errors cause authentication to fail.
If the IdP is unavailable, only local authentication remains possible (see Authentication flow).

Security​

Sync-in automatically uses the PKCE (Proof Key for Code Exchange) mechanism when it is supported by the identity provider and enabled in the configuration through the security.supportPKCE parameter (enabled by default).

PKCE strengthens the Authorization Code flow by adding cryptographic proof during the authorization code exchange, improving security for web and native clients.

This implementation aligns with current OAuth security recommendations.

info

PKCE support may prevent authentication with certain identity providers such as PocketID, in which case it can be disabled.

The security.tokenEndpointAuthMethod option supports client_secret_basic and client_secret_post. Use the value expected by your IdP; client_secret_basic is the default for confidential web clients. The clientSecret field is required in Sync-in configuration.

OIDC discovery and token requests require HTTPS by default. The security.allowInsecureRequests option should only be enabled for local development or trusted legacy providers.

The security.requireVerifiedEmail option is enabled by default. Sync-in requires the UserInfo email_verified claim to be exactly true before account linking or profile synchronization. Disable it only if your IdP does not expose a reliable verified-email claim.

When options.autoSyncAvatar is enabled, Sync-in can synchronize the user avatar from the OIDC picture claim. Avatar downloads from private or internal IP ranges remain blocked unless security.allowPrivateIpAvatarDownload is explicitly enabled.