Control CoreDocs

SSO with SAML 2.0 and OIDC

Audience: Administrators, Identity Engineers
Time: ~25 min per IdP
Prerequisites: Super Administrator access; corporate IdP admin rights; HTTPS ingress to the Control Plane

Configure enterprise single sign-on so operators authenticate through your identity provider (Entra ID, Okta, Google Workspace, Auth0, PingID, or any SAML 2.0 / OIDC-compliant IdP).

Overview

Control Core supports OIDC Authorization Code + PKCE (S256) and SAML 2.0 SP-initiated flows. After successful federation, the Control Plane issues its own session JWT (RS256 by default) bound to a server-side session record.

Assertion hardening (v3.4) rejects weak algorithms and stale tokens before user records are created or updated.

Configure OIDC

  1. In your IdP, register the Control Plane as an OIDC client.
  2. Set redirect URI to your Control Plane origin plus /auth/sso/callback (for example https://controlplane.example.com/auth/sso/callback).
  3. In the Control Plane, open Settings → Users → SSO and choose Generic OIDC (or a vendor template).
  4. Provide Client ID, Client Secret, Issuer URL, and Redirect URI.
  5. Map IdP groups to Control Core roles using Role claim (default roles) or a JSON role map.

Verification: Sign out, choose Sign in with SSO, complete the IdP login, and confirm you land on the Control Plane home with the expected role.

Troubleshooting: If SSO returns 401 or invalid token, verify issuer and audience match IdP configuration, the IdP signing keys are reachable (JWKS URI), and system clocks are synchronized (skew tolerance 120 seconds). If the callback succeeds but role is wrong, review role mapping under SSO settings.

OIDC hardening (automatic)

The Control Plane verifies ID token signatures against the IdP JWKS, enforces issuer/audience/exp/nonce, and rejects tokens whose clock skew exceeds 120s or validity window exceeds 300s.

Environment overrides (optional):

  • OIDC_MAX_CLOCK_SKEW_SECONDS (default 120)
  • OIDC_MAX_ASSERTION_LIFESPAN_SECONDS (default 300)

Configure SAML 2.0

  1. In your IdP, create a SAML application for the Control Plane.
  2. Set Entity ID and ACS URL from the Control Plane SSO wizard.
  3. Upload the IdP signing certificate to the Control Plane (SAML certificate field).
  4. Enable signed assertions and responses in the IdP (RSA-SHA256 or ECDSA-SHA256).

Verification: Initiate SSO from the login page; confirm a user row appears under Settings → Users with source saml.

Troubleshooting: SHA-1 signature rejected — reconfigure the IdP to RSA-SHA256. Assertion lifespan errors — shorten IdP assertion lifetime to ≤ 300 seconds. Dual signature errors — enable signing on both SAML Response and Assertion per IdP documentation.

JIT attribute mapping

SAML attributes map into Control Core user profiles for authorization context:

IdP attribute (examples)Control Core field
role / WS-Federation role claimPlatform role mapping
departmentUser department
clearance_level / clearanceClearance attribute (for controls reading subject context)
email, displayNameProfile fields

Security recommendations

  • Restrict SSO to managed devices where possible.
  • Prefer OIDC + PKCE for cloud-native IdPs; use SAML when the IdP requires it.
  • After SSO cutover, disable password login for non-break-glass accounts under Authentication Methods.

Next steps