SSO / SAML / OIDC¶

By default, users sign in to Cloud Digit with email + password or one of the public SSO providers (Google, GitHub, Microsoft). For larger organizations, you can federate Cloud Digit with your enterprise identity provider, so people sign in with the same corporate credentials they use everywhere else — and your IdP decides who has what role.

Why federate¶

If your org has more than ~20 users or any kind of regulated IAM policy, federate.

Supported protocols¶

High-level flow¶

sequenceDiagram
    participant U as User
    participant CD as Cloud Digit
    participant KC as Keycloak (CD IdP)
    participant IdP as Your IdP
    U->>CD: Visit cloud.<your-domain>
    CD->>KC: Auth required
    KC->>U: Choose sign-in method
    U->>KC: Click "Sign in with <your IdP>"
    KC->>IdP: SAML AuthnRequest / OIDC redirect
    IdP->>U: IdP login (if no SSO cookie)
    U->>IdP: Credentials + IdP MFA
    IdP->>KC: SAML Response / OIDC code (with claims)
    KC->>CD: Issue session
    CD->>U: Cloud Digit Console

The user's experience is one click. Behind it, Cloud Digit's Keycloak validates the assertion from your IdP, maps claims to org membership + role, and issues a session.

Setting up SAML¶

Org settings → Integrations → SSO → SAML → Configure.

SAML configuration page. Cloud Digit shows its SP metadata; you provide the IdP metadata.

What Cloud Digit gives you (Service Provider metadata)¶

Download the SP metadata XML from this page and import it into your IdP.

What you give Cloud Digit (Identity Provider metadata)¶

Paste your IdP's metadata XML (most IdPs publish at https://<idp>/...metadata.xml), or fill in:

• IdP Entity ID (https://login.microsoftonline.com/<tenant-id>/..., etc.)
• SingleSignOnService URL
• SingleLogoutService URL (optional but recommended)
• IdP signing certificate (X.509 PEM)
• NameID attribute — usually email or userPrincipalName

Required claims/attributes Cloud Digit needs the IdP to send:

Role mapping (groups → Cloud Digit roles)¶

In SSO → Group mapping, declare which of your IdP groups map to which Cloud Digit roles:

You pick the IdP-side group names — these are common ones. A user in multiple groups gets the union of permissions.

Just-in-time provisioning¶

Tick JIT provisioning to auto-create the user on first sign-in (with the role decided by their group mapping). Without JIT, you'd have to invite each user manually first; with JIT, your IdP is the source of truth and Cloud Digit follows.

Enforce SSO-only¶

Once SSO is working, tick Enforce SSO to disable email+password sign-in for this org. Users can only enter via your IdP. Bypass-recovery code can be requested via support if you ever lock yourself out.

Setting up OIDC¶

Same page, OIDC tab. The flow is analogous:

Role mapping works the same way (via the groups claim).

SCIM 2.0 provisioning (preview)¶

For organizations that want true bidirectional sync (joiner / mover / leaver flowing from IdP → Cloud Digit automatically):

• SCIM endpoint Cloud Digit exposes: https://api.<your-cloud-digit-domain>/scim/v2/organizations/<org-id>
• Auth — long-lived bearer token issued from SSO → SCIM → Issue token
• Standard SCIM 2.0 endpoints: /Users, /Groups, /Schemas
• Tested against Azure AD, Okta SCIM, OneLogin

When SCIM is configured, suspending a user in your IdP auto-suspends them in Cloud Digit on the next sync (within 60 s for Azure AD, 5 min for Okta default).

Testing SSO¶

After configuring (and before enforcing SSO-only), use the Test SSO button on the SSO page. It opens a new tab pointing at the federation flow but with a debug param — the tab shows you the raw SAML response / OIDC token, the parsed claims, and the resolved Cloud Digit identity, without actually creating a session. Use this to verify group mapping before flipping the enforce switch.

Failure modes & fixes¶

Audit and observability¶

• All SSO-mediated sign-ins appear in the audit log with auth_method: saml or auth_method: oidc
• Group-mapping changes are audited
• Federation health (success rate, last successful test) is in SSO → Health

For deep audit needs (e.g., SAML Response XML inspection), use SIEM — Cloud Digit ships full SAML/OIDC events to the SIEM if you enable that integration.

Related¶

• Users
• Roles & permissions
• Organizations
• SIEM
• Compliance & sovereignty