Skip to content

OIDC Login

Requires the Enterprise Edition.

What it does

Native OpenID Connect (OIDC) client built into CMDBsyncer. Lets users sign in directly against their corporate identity provider — Azure AD / Entra ID, Okta, Keycloak, Google Workspace, Auth0, or any OIDC-compliant IdP — without running mod_auth_openidc or mod_auth_mellon on a reverse proxy in front.

Complements the two existing Enterprise auth features:

Feature When to use
Remote User SSO Your reverse proxy already authenticates users and sets REMOTE_USER.
LDAP Login Direct bind against LDAP / Active Directory.
OIDC Login Native OIDC against a cloud or on-prem IdP, no proxy needed.

Ideal for Docker / Kubernetes deployments, where the reverse-proxy approach either isn't available or shouldn't be the auth boundary.

Configuration

Everything except the group-to-role table is configured in the web UI — no local_config.py editing needed.

1. Create the Account

Accounts → New, type OIDC identity provider:

Field Value
name entra-id
address https://login.microsoftonline.com/<tenant>/v2.0 (issuer)
username <app-registration-id> (client id)
password <client-secret>

The address is the base of the discovery document, not the /.well-known/openid-configuration URL itself.

2. Apply the "OIDC / SSO login" preset

Config → Local Config → Quick configurations → OIDC / SSO login. Fill in the fields and press Apply preset:

Key Meaning
OIDC_LOGIN Master toggle.
OIDC_ACCOUNT Name of the Account from step 1.
OIDC_SCOPES Scopes to request, space separated. openid is always included.
OIDC_EMAIL_CLAIM Claim holding the email — the local user is matched on it.
OIDC_NAME_CLAIM Claim used for the display name on auto-create.
OIDC_GROUPS_CLAIM Claim carrying the user's groups.
OIDC_REQUIRED_GROUP Optional gate — only members of this group may log in.
OIDC_AUTO_CREATE Create a local user on first successful login.
OIDC_ADMIN_GROUP Members of this group become global admins.
OIDC_DEFAULT_ROLES Roles every accepted user receives, comma separated.

The preset also shows the redirect URI of this installation. Register it at the identity provider exactly as printed — a mismatch is the single most common reason an OIDC login fails.

3. Restart and log in

The OIDC keys take effect after a service restart. The login page then shows a Sign in with SSO button.

Editing local_config.py directly

The same settings can be written by hand; the preset only produces this:

config = {
    'OIDC_LOGIN': True,
    'OIDC_ACCOUNT': 'entra-id',

    'OIDC_SCOPES': 'openid email profile groups',

    # Which claim holds the user's email address and display name
    'OIDC_EMAIL_CLAIM': 'email',
    'OIDC_NAME_CLAIM': 'name',

    # Group-based authorisation
    'OIDC_GROUPS_CLAIM': 'groups',
    'OIDC_REQUIRED_GROUP': 'cmdbsyncer-users',   # optional gate
    'OIDC_AUTO_CREATE': True,
    'OIDC_ADMIN_GROUP': 'cmdbsyncer-admins',
    'OIDC_DEFAULT_ROLES': 'host, log',
}

For mappings that go beyond "admins" and "everyone", add the nested OIDC_ROLE_MAPPING dict — it cannot be written from the UI:

config = {
    'OIDC_ROLE_MAPPING': {
        'cmdbsyncer-admins': {'global_admin': True},
        'cmdbsyncer-ops':    {'roles': ['host', 'log']},
        'cmdbsyncer-api':    {'api_roles': ['all']},
    },
}

OIDC_ADMIN_GROUP and OIDC_DEFAULT_ROLES are merged into that dict, so both forms can be used together.

Provider-specific notes

Azure AD / Entra ID

  • Account address (issuer): https://login.microsoftonline.com/<tenant>/v2.0
  • Create an App Registration, add a Web platform redirect URI https://<syncer>/oidc/callback, generate a client secret.
  • To expose group claims, configure Token configuration → Add groups claim; with the v2 endpoint Azure emits group object IDs — use those IDs (not display names) as OIDC_ROLE_MAPPING keys.

Keycloak

  • Account address (issuer): https://keycloak.example.com/realms/<realm>
  • Create a client of type OpenID Connect, confidential, with the redirect URI set; copy the client secret.
  • Map groups to a groups claim in Client scopes → groups.

Okta

  • Account address (issuer): https://<yourorg>.okta.com or https://<yourorg>.okta.com/oauth2/default
  • Configure a Web application, add the redirect URI, copy the client secret.
  • Include groups in the ID token via the Groups claim setting.

Google Workspace

  • Account address (issuer): https://accounts.google.com
  • No group claim by default — OIDC_ROLE_MAPPING won't apply. Assign roles manually via the UI, or proxy through Okta/Auth0.

Role mapping

Same union-of-groups semantics as LDAP Login:

  • The user's groups claim is intersected with the keys of OIDC_ROLE_MAPPING — OIDC_ADMIN_GROUP counts as an entry of that table granting global_admin.
  • For each match, roles, api_roles, and global_admin are unioned, plus everything in OIDC_DEFAULT_ROLES.
  • The user's local roles / api_roles / global_admin are replaced by the computed union on every login.

So:

  • Remove a user from cmdbsyncer-admins in your IdP → they lose admin on their next login. No manual sync needed.
  • Do not grant ad-hoc permissions via the CMDBsyncer UI — they get reverted on next login.
  • Leave OIDC_ROLE_MAPPING, OIDC_ADMIN_GROUP and OIDC_DEFAULT_ROLES all empty to opt out of role sync; new users are then created with no roles and you grant them manually.

Routes

Route Purpose
/oidc/login Start the authorization-code flow (redirects to the IdP).
/oidc/callback IdP redirects back here; CMDBsyncer exchanges the code for tokens and logs the user in.

Register https://<your-syncer>/oidc/callback as the allowed redirect URI in the IdP.

Audit trail

Every OIDC login attempt is recorded in the Audit Log (when co-licensed), with metadata.method = 'oidc' and these failure reasons:

  • setup_error — bad issuer / discovery failed
  • token_exchange_failed — code exchange rejected by the IdP
  • no_userinfo — IdP accepted the token but returned no profile
  • no_email_claim — token has no email in the configured claim
  • required_group_missing — user not in OIDC_REQUIRED_GROUP
  • no_local_user_and_autocreate_off — first-time user but OIDC_AUTO_CREATE = False

Troubleshooting

OIDC login is not available, the reason is in the log
The Account or the discovery of the IdP could not be used. The reason is in the Log of the Syncer as OIDC login failed, the login page does not show it because it is open to anybody.

Loop back to /login with no flash message
Check the Flask logs for OIDC client setup failed. Most common cause: wrong issuer URL on the Account (address must be the base of the discovery document, not the discovery URL itself).

token_exchange_failed
- Redirect URI mismatch — must match exactly in the IdP. - Client secret wrong or missing in the Account's password field. - Wrong Account named in OIDC_ACCOUNT, or the Account is disabled.

Groups are empty even though the user is in groups in Azure AD
Azure only emits groups in the ID token when configured — see the Azure-specific notes above. Also verify the token isn't being truncated (large groups → use hasGroups + Graph API lookup instead; not yet built in, open an issue).

Login works but user has no roles
OIDC_ROLE_MAPPING keys must exactly match the values emitted in the groups claim (case-insensitive match is applied). For Azure v2, these are object IDs, not display names.