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.).

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 (guests), administrator accounts, and application credentials (app passwords) can sign in using their login/password.
  • Other users can use their local password only if:
    • options.enablePasswordAuth is enabled;
    • a local password is set for the account.
  • This setup preserves emergency administrative access without disabling OIDC authentication.

OpenID Connect (OIDC) authentication​

  • The user starts sign-in via the OIDC button.
  • They are redirected to the IdP to authenticate.
  • 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.

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.