OIDC Single Sign-On

Let users sign in to Arcane through your OpenID Connect provider.

Let users sign in with their identity provider account (Authentik, Keycloak, Pocket ID, Azure AD, and so on) instead of a local password. Register https://<your-arcane-url>/auth/oidc/callback as a redirect URI in the provider, and get its client ID, client secret, and issuer URL.

Go to System → Authentication.
Enter your provider’s client ID, client secret, and issuer URL.
Copy the redirect URI shown on the page into your provider.
Save and test the connection.

services:
  arcane:
    environment:
      - ARCANE_OIDC_ENABLED=true
      - ARCANE_OIDC_CLIENT_ID=your_arcane_client_id_from_provider
      - ARCANE_OIDC_CLIENT_SECRET=your_super_secret_client_secret_from_provider
      - ARCANE_OIDC_ISSUER_URL=https://auth.example.com
      - ARCANE_OIDC_SCOPES=openid email profile groups
      - ARCANE_OIDC_GROUPS_CLAIM=groups

In list-form environment: entries, don’t wrap values in quotes. The quotes become part of the value.

Arcane discovers the provider’s endpoints from the issuer URL’s .well-known/openid-configuration page. The issuer URL must not end with a trailing slash. Arcane creates an OIDC user on first sign-in. You can disable local login so everyone signs in through your provider.

Turn on Auto Redirect to Provider in System → Authentication, or set ARCANE_OIDC_AUTO_REDIRECT_TO_PROVIDER=true. Users go straight to your provider instead of Arcane’s login page.

If the provider is down or misconfigured, open https://<your-arcane-url>/login/backup. It never redirects, so you can sign in with a local account or passkey and fix OIDC.

Map provider groups to roles

OIDC mappings grant a role when a value in the user’s groups claim matches, globally or in one environment.

Add the groups scope, for example openid email profile groups.
Under System → Authentication, set the Groups Claim if it isn’t groups (Keycloak: realm_access.roles, Azure AD: memberOf).
Under System → Authentication, use Create Mapping for each claim value. Set the Claim value to the exact string from the claim, such as docker-admins, and pick the role it grants.
Terminal window
```
arcane-cli admin oidc create --claim docker-admins --role role_admin
```

Add --environment <env-id> to grant the role in one environment only. Arcane re-checks the claim on every login, so removing a user from a provider group removes the role at their next sign-in.

Manage mappings from the environment

Set ARCANE_OIDC_ROLE_MAPPINGS to a JSON array:

services:
  arcane:
    environment:
      - 'ARCANE_OIDC_ROLE_MAPPINGS=[{"claimValue":"docker-admins","roleId":"role_admin"}]'

Add "environmentId" to an entry to scope it to one environment.
On every startup, Arcane replaces all environment-managed mappings with this list. They’re read-only in the UI.
Set it to [] to remove all environment-managed mappings. Unset leaves them in place.
ARCANE_OIDC_ROLE_MAPPINGS_FILE works for Docker secrets.

Access control settings

System → Authentication → Access control holds defaults that also apply to OIDC users:

Setting	What it does
Default role	Role bound globally to new users and to OIDC users who end a login with no role. No default role leaves them without access. See Default role for new users.
Audit retention days	Days to keep audit events. `0` keeps them forever.
Record permission denials	Records an `authz.denied` event when a request is rejected for a missing permission. See Permission denials.

Reference

Primary Configuration

Variable	Default	Description
`ARCANE_OIDC_ENABLED`	`false`	Enable OIDC login.
`ARCANE_OIDC_CLIENT_ID`	—	Client ID from your OIDC provider.
`ARCANE_OIDC_CLIENT_SECRET`	—	Client secret from your OIDC provider.
`ARCANE_OIDC_ISSUER_URL`	—	Issuer URL of your OIDC provider, such as `https://your-provider.com`. No trailing slash.
`ARCANE_OIDC_SCOPES`	`openid email profile`	Scopes to request. Include the groups claim if you use OIDC group mappings.
`ARCANE_OIDC_MERGE_ACCOUNTS`	`false`	Link OIDC logins to existing local accounts based on email address.
`ARCANE_OIDC_SKIP_TLS_VERIFY`	`false`	Skip TLS verification for the OIDC provider. Use with caution.
`ARCANE_OIDC_AUTO_REDIRECT_TO_PROVIDER`	`false`	Automatically redirect users to the OIDC provider on login.
`ARCANE_OIDC_PROVIDER_NAME`	—	Provider display name shown on the login screen.
`ARCANE_OIDC_PROVIDER_LOGO_URL`	—	Provider logo URL shown on the login screen.
`ARCANE_OIDC_GROUPS_CLAIM`	`groups`	Claim that holds the user’s groups. Supports dotted paths such as `realm_access.roles`.
`ARCANE_OIDC_ROLE_MAPPINGS`	—	OIDC claim→role mappings as a JSON array, for example `[{"claimValue":"docker-admins","roleId":"role_admin"}]`. Reconciled at every startup; rows are read-only in the UI. Supports `ARCANE_OIDC_ROLE_MAPPINGS_FILE` for Docker secrets.

Manual Endpoint Overrides (Advanced)

Use these if your provider doesn’t support discovery via the Issuer URL.

Variable	Description
`ARCANE_OIDC_AUTHORIZATION_ENDPOINT`	Manual authorization URL, such as `https://provider.com/auth`.
`ARCANE_OIDC_TOKEN_ENDPOINT`	Manual token URL, such as `https://provider.com/token`.
`ARCANE_OIDC_USERINFO_ENDPOINT`	Manual userinfo URL, such as `https://provider.com/userinfo`.
`ARCANE_OIDC_JWKS_ENDPOINT`	Manual JWKS URL for token verification, such as `https://provider.com/jwks`.

Arcane Configuration Values

Type	Value	Description
Redirect URI	`{ARCANE_APP_URL}/auth/oidc/callback`	The URL to register with your OIDC provider