OIDC Single Sign-On
Let users sign in to Arcane through your OpenID Connect provider.
Works with any OpenID Connect provider, such as Authentik, Keycloak, Pocket ID, or Azure AD.
Before you start
Section titled “Before you start”- Register an OIDC application with your provider.
- Add
https://<your-arcane-url>/auth/oidc/callbackas its redirect URI. - Copy its client ID, client secret, and issuer URL. Remove any trailing slash from the issuer URL.
Arcane finds the provider’s endpoints from <issuer-url>/.well-known/openid-configuration. If your provider doesn’t publish that page, see Manual endpoints.
Configure OIDC
Section titled “Configure OIDC”- Go to System → Authentication.
- Turn on OIDC Authentication.
- Click Show Configuration.
- Enter the Client ID, Client Secret, and Issuer URL.
- Check that the redirect URI shown on the page matches the one in your provider.
- Click Save.
- Sign out, then click Sign in with … on the login page to check that SSO works.
-
Add these variables to the Arcane service:
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 -
Recreate the container.
In list-form environment: entries, don’t wrap values in quotes. The quotes become part of the value.
Arcane creates an OIDC user the first time someone signs in. You can disable local login so everyone signs in through your provider.
Skip the login screen
Section titled “Skip the login screen”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
Section titled “Map provider groups to roles”A mapping grants a role when a value in the user’s groups claim matches. It can apply globally or to one agent. Arcane re-checks the claim on every login, so removing a user from a provider group removes the role at their next sign-in.
First, get groups into the user’s token:
- Configure your provider to include groups. See the provider notes below.
- Sign in once and decode the ID token, for example with your provider’s token preview or a JWT decoder.
- Find the claim that lists the groups. Note its path, such as
groupsorresource_access.arcane.roles. - If the path isn’t
groups, enter it in Groups Claim in System → Authentication, or setARCANE_OIDC_GROUPS_CLAIM. Use dots for nested claims.
Arcane reads the claim from the userinfo response first, then from the ID token. It accepts a list or a comma- or space-separated string.
Provider notes:
- Microsoft Entra ID: in the app registration, open Token configuration and select Add groups claim. Entra sends group object IDs, not names, so map those IDs.
- Keycloak: in the client’s dedicated scope, add a Group Membership mapper with Token Claim Name
groups. Turn off Full group path to getdocker-adminsinstead of/docker-admins. - Authentik, Authelia, Pocket ID: request the scope that carries groups (
groupsfor Authelia and Pocket ID; Authentik’s defaultprofilescope includes it). The claim isgroups.
Then add mappings with one of these methods:
- Go to System → Authentication.
- Select Create Mapping.
- Set Claim value to the exact string from the claim, such as
docker-admins. - Pick the role it grants.
- Optional: pick one agent to limit the role to it.
- Save. Repeat for each claim value.
-
Create a mapping for each claim value:
Terminal window arcane-cli admin oidc create --claim docker-admins --role role_admin -
Optional: add
--agent <agent-id>to grant the role on one agent only.
The CLI must be signed in first. See CLI Configuration.
-
Set
ARCANE_OIDC_ROLE_MAPPINGSto a JSON array:services:arcane:environment:- 'ARCANE_OIDC_ROLE_MAPPINGS=[{"claimValue":"docker-admins","roleId":"role_admin"}]' -
Optional: add
"environmentId"to an entry to limit it to one agent. -
Recreate the container.
- 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. Leaving it unset keeps them. - Use
ARCANE_OIDC_ROLE_MAPPINGS_FILEto read the list from a Docker secret.
Reference
Section titled “Reference”Environment variables
Section titled “Environment variables”| Variable | What it does |
|---|---|
ARCANE_OIDC_ENABLED |
Turn on OIDC login. Default false. |
ARCANE_OIDC_CLIENT_ID |
Client ID from your provider. |
ARCANE_OIDC_CLIENT_SECRET |
Client secret from your provider. |
ARCANE_OIDC_ISSUER_URL |
Provider issuer URL, such as https://auth.example.com. No trailing slash. |
ARCANE_OIDC_SCOPES |
Scopes to request. Default openid email profile. Add groups for role mappings. |
ARCANE_OIDC_GROUPS_CLAIM |
Claim holding the user’s groups. Default groups. Dotted paths work, such as realm_access.roles. |
ARCANE_OIDC_ROLE_MAPPINGS |
Claim-to-role mappings as a JSON array. Also ARCANE_OIDC_ROLE_MAPPINGS_FILE. |
ARCANE_OIDC_MERGE_ACCOUNTS |
Link OIDC logins to existing local accounts by email. Default false. While on, no one can change a user’s email in Arcane. |
ARCANE_OIDC_AUTO_REDIRECT_TO_PROVIDER |
Send users straight to the provider on login. Default false. |
ARCANE_OIDC_PROVIDER_NAME |
Provider name shown on the login screen. |
ARCANE_OIDC_PROVIDER_LOGO_URL |
Provider logo URL shown on the login screen. |
ARCANE_OIDC_SKIP_TLS_VERIFY |
Skip TLS verification for the provider. Default false. Use with caution. |
Register the exact redirect URI shown under System → Authentication → Redirect URI Configuration. Open that page at the address users sign in with, because the URI follows that address. Arcane builds it from the browser’s Origin header, then X-Forwarded-Host/X-Forwarded-Proto, then Host, and only then ARCANE_APP_URL. Behind a proxy, the forwarded headers decide it. See Reverse proxy.
Manual endpoints
Section titled “Manual endpoints”Set these only if your provider doesn’t support discovery from the issuer URL.
| Variable | Example |
|---|---|
ARCANE_OIDC_AUTHORIZATION_ENDPOINT |
https://provider.com/auth |
ARCANE_OIDC_TOKEN_ENDPOINT |
https://provider.com/token |
ARCANE_OIDC_USERINFO_ENDPOINT |
https://provider.com/userinfo |
ARCANE_OIDC_JWKS_ENDPOINT |
https://provider.com/jwks (token verification keys) |