Authentication & SSO

Synclet supports multiple authentication methods: email and password for quick setup, OpenID Connect (OIDC) for enterprise single sign-on, and API keys for programmatic access.

Email & Password

Email and password is the default authentication method. When you first access Synclet, you can create an account from the login page.

1. Open the Synclet web UI in your browser.
2. Click Create account.
3. Enter your email address, your name, and choose a password (minimum 8 characters by default — configurable via AUTH_MIN_PASSWORD_LENGTH).
4. Submit the form. You are logged in and can start creating workspaces.

The first user to register is automatically assigned the Admin role on the default workspace.

Single Sign-On (OIDC)

Synclet supports any OpenID Connect identity provider, including Google, Okta, Auth0, Keycloak, and Azure AD. You can configure multiple providers simultaneously.

Configuration

OIDC setup requires two steps: (1) list the providers you want to enable, and (2) set per-provider credentials.

Step 1: Declare providers

Set AUTH_OIDC_PROVIDERS to a comma-separated list of provider slugs, and AUTH_OIDC_CALLBACK_BASE_URL to your public Synclet URL:

AUTH_OIDC_PROVIDERS="google,okta"
AUTH_OIDC_CALLBACK_BASE_URL="https://synclet.example.com"

Step 2: Configure each provider

For each slug listed in AUTH_OIDC_PROVIDERS, set the following environment variables (replace <SLUG> with the uppercase slug):

Variable	Description	Required
AUTH_OIDC_<SLUG>_ISSUER	The OIDC issuer URL	Yes
AUTH_OIDC_<SLUG>_CLIENT_ID	OAuth 2.0 client ID	Yes
AUTH_OIDC_<SLUG>_CLIENT_SECRET	OAuth 2.0 client secret	Yes
AUTH_OIDC_<SLUG>_DISPLAY_NAME	Button label on login page	No (defaults to slug)
AUTH_OIDC_<SLUG>_SCOPES	Comma-separated scopes	No (defaults to openid,profile,email)
AUTH_OIDC_<SLUG>_ALLOWED_DOMAINS	Restrict to email domains	No
AUTH_OIDC_<SLUG>_AUTO_CREATE_USER	Create user on first login	No (defaults to true)
AUTH_OIDC_<SLUG>_DEFAULT_ROLE	Role when the claim matches no mapping: admin, editor or viewer	No (defaults to viewer)
AUTH_OIDC_<SLUG>_ROLE_CLAIM	Claim to use for role mapping	No
AUTH_OIDC_<SLUG>_ROLE_MAP_ADMIN	Claim value → Admin role	No
AUTH_OIDC_<SLUG>_ROLE_MAP_EDITOR	Claim value → Editor role	No
AUTH_OIDC_<SLUG>_ROLE_MAP_VIEWER	Claim value → Viewer role	No
AUTH_OIDC_<SLUG>_ROLE_SYNC	When the claim is applied to an existing member: login or first_login	No (defaults to login)
AUTH_OIDC_<SLUG>_BOUND_CLAIM_<NAME>	Reject the login unless the ID token has claim <NAME> (lowercased, e.g. ..._BOUND_CLAIM_DEPARTMENT checks department) equal to this value. Exact string match; repeat for several claims, all must match	No

The role settings apply in single-workspace mode only; see Role mapping.

Example: Google

AUTH_OIDC_PROVIDERS="google"
AUTH_OIDC_CALLBACK_BASE_URL="https://synclet.example.com"
AUTH_OIDC_GOOGLE_ISSUER="https://accounts.google.com"
AUTH_OIDC_GOOGLE_CLIENT_ID="123456789.apps.googleusercontent.com"
AUTH_OIDC_GOOGLE_CLIENT_SECRET="GOCSPX-xxxxxxxxxxxxxxxx"
AUTH_OIDC_GOOGLE_DISPLAY_NAME="Google"
AUTH_OIDC_GOOGLE_ALLOWED_DOMAINS="yourcompany.com"

Example: Multiple providers (Google + Okta)

AUTH_OIDC_PROVIDERS="google,okta"
AUTH_OIDC_CALLBACK_BASE_URL="https://synclet.example.com"

# Google
AUTH_OIDC_GOOGLE_ISSUER="https://accounts.google.com"
AUTH_OIDC_GOOGLE_CLIENT_ID="123456789.apps.googleusercontent.com"
AUTH_OIDC_GOOGLE_CLIENT_SECRET="GOCSPX-xxxxxxxxxxxxxxxx"

# Okta
AUTH_OIDC_OKTA_ISSUER="https://your-org.okta.com"
AUTH_OIDC_OKTA_CLIENT_ID="0oaXXXXXXXXXXXXXXX"
AUTH_OIDC_OKTA_CLIENT_SECRET="your-client-secret"
AUTH_OIDC_OKTA_DISPLAY_NAME="Company SSO"

When OIDC is configured, a Sign in with … button appears on the login page for each provider. Users who sign in through OIDC for the first time have an account created automatically (unless AUTO_CREATE_USER is set to false).

Role mapping

In single-workspace mode (WORKSPACE_MODE=single, the default), every OIDC login sets the user’s role in the default workspace from a claim of the ID token.

• ROLE_CLAIM names the claim. It may hold a string or a list of strings, such as the groups claim of authentik, Keycloak or Okta.

• ROLE_MAP_ADMIN, ROLE_MAP_EDITOR and ROLE_MAP_VIEWER name the claim value of each role. They are checked in that order, so a user whose claim matches both the admin and the editor value becomes admin.

• A claim that matches no mapping, or a missing claim, gives DEFAULT_ROLE (viewer when unset). Any value other than admin, editor or viewer stops the server at startup.

• The first member of the default workspace always joins as admin, whatever the claim says.

• A user who signs in through OIDC and is not a member of the default workspace joins it with the mapped role. That includes an existing password user linked by email, and a user an admin removed from the workspace: revoke access in the identity provider instead.

• ROLE_SYNC decides when the claim is applied to a user who is already a member:

  • login (the default) applies it on every login. The identity provider is the source of truth, and a role changed in the Synclet UI is overwritten at the user’s next login.
  • first_login applies it only when the user joins. Later role changes are made in the UI.

  Any other value stops the server at startup. Without ROLE_CLAIM, an existing member’s role is never changed.

• A role changed by a sync is written to the audit log as a member role change by the user logging in.

• A sync never demotes the workspace’s last admin: the role stays admin and the server logs a warning naming the user and the role the claim asked for.

In multi-workspace mode the role settings are ignored: users join workspaces through invitations, and the server logs a warning at startup for each provider that sets ROLE_CLAIM, ROLE_MAP_*, DEFAULT_ROLE or ROLE_SYNC.

Example: authentik groups

authentik puts the names of the user’s groups in the groups claim, a list, when the profile scope is requested.

AUTH_OIDC_PROVIDERS="authentik"
AUTH_OIDC_CALLBACK_BASE_URL="https://synclet.example.com"
AUTH_OIDC_AUTHENTIK_ISSUER="https://auth.example.com/application/o/synclet/"
AUTH_OIDC_AUTHENTIK_CLIENT_ID="synclet"
AUTH_OIDC_AUTHENTIK_CLIENT_SECRET="your-client-secret"
AUTH_OIDC_AUTHENTIK_DISPLAY_NAME="authentik"
AUTH_OIDC_AUTHENTIK_ROLE_CLAIM="groups"
AUTH_OIDC_AUTHENTIK_ROLE_MAP_ADMIN="synclet-admins"
AUTH_OIDC_AUTHENTIK_ROLE_MAP_EDITOR="synclet-editors"
AUTH_OIDC_AUTHENTIK_DEFAULT_ROLE="viewer"
AUTH_OIDC_AUTHENTIK_ROLE_SYNC="login"

A user in synclet-admins becomes admin, a user in synclet-editors editor, and everyone else viewer.

Disabling Registration

Registration is off by default (AUTH_REGISTRATION_ENABLED=false). While no account exists yet, sign-up stays open, so the first person to open a fresh install creates the admin account; after that, new email/password registrations are refused. To let anyone sign up, set:

AUTH_REGISTRATION_ENABLED=true

Existing users and OIDC logins are not affected: users who authenticate through an OIDC provider can still sign in and have accounts created on first login.

API Keys

API keys allow programmatic access to the Synclet API, useful for CI/CD pipelines, scripts, and integrations.

Creating an API Key

1. Navigate to Settings > API Keys in the workspace you want to access.
2. Give the key a descriptive name (e.g., ci-pipeline or terraform).
3. Choose when it expires: never, in 30 days, 90 days, a year, or on a custom date. An expired key gets 401 Unauthorized.
4. Click Create key.
5. Copy the key immediately — it is only shown once.

Using an API Key

The API is ConnectRPC: every call is a POST to /<package>.<Service>/<Method> with a JSON body. Include the key in the Authorization header; the key already carries its workspace:

curl -X POST \
  -H "Authorization: Bearer synclet_sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://synclet.example.com/synclet.publicapi.pipeline.v1.ConnectionService/ListConnections

Revoking an API Key

1. Go to Settings > API Keys.
2. Find the key you want to revoke.
3. Click Revoke and confirm.

Revoked keys stop working immediately. Any automation using the key will begin receiving 401 Unauthorized responses.

Caution

API keys have the same permissions as the role of the user who created them within that workspace. Treat them like passwords — do not commit them to version control.

Session Management

Synclet uses cookie-based sessions for authentication.

• Access token cookie (synclet_at) is short-lived (15 minutes by default, configurable via AUTH_ACCESS_TOKEN_TTL) and sent automatically with every request from the web UI. It is HttpOnly and not accessible to JavaScript.
• Refresh token cookie (synclet_rt) allows the browser to obtain new access tokens without re-entering credentials.
• A metadata cookie (synclet_auth) is readable by JavaScript and contains token expiration timestamps so the frontend can proactively refresh tokens.
• Sessions persist across browser restarts until the refresh token expires (7 days by default, configurable via AUTH_REFRESH_TOKEN_TTL) or is revoked.

To log out, click your avatar in the top-right corner and select Log out. This clears your session cookies and invalidates the refresh token.

Next Steps

• Workspaces & Roles — Learn about multi-tenant workspaces and role-based access.
• Settings & API Keys — Manage workspace settings, members, and API keys.
• Configuration — Full list of environment variables including OIDC and registration settings.