Guides

SAML SSO & SCIM provisioning

Configure SAML 2.0 single sign-on and SCIM 2.0 user/group provisioning for your organization, with IdP group-to-role mapping. Tested with Okta, Microsoft Entra ID and Google Workspace.

Cloud Control supports SAML 2.0 single sign-on and SCIM 2.0 provisioning as a bring-your-own-IdP feature, alongside OIDC. An Org Admin configures both on the Team screen. Group membership in your IdP drives each user's console role.

Tested identity providers

SAML + SCIM are built and tested against Okta, Microsoft Entra ID (Azure AD) and Google Workspace. The signature verification, claim handling and SCIM protocol accommodate the differences between them (see the matrix below).

SAML: what to hand your IdP

Cloud Control is the Service Provider (SP). Give your IdP admin these SP details (they are also shown on the Team screen):

Field	Value
SP entity ID	`https://<your-host>/api/auth/saml/metadata`
ACS URL (HTTP-POST)	`https://<your-host>/api/auth/saml/acs`
NameID format	emailAddress (persistent / unspecified also accepted)
SP metadata	`GET https://<your-host>/api/auth/saml/metadata` — importable directly

SAML: configure the IdP side in Cloud Control

On Team → Single sign-on (SAML 2.0) → Configure, paste your IdP's metadata XML (the fastest path — we extract the entity ID, SSO URL and signing certificate for you), or enter them by hand: the IdP entity ID, the SSO URL (HTTPS), and the X.509 signing certificate (PEM or base64). Optionally set the email and groups attribute names, allowed email domains, and the default role for users whose groups don't map to anything. The certificate is validated when you save.

How assertions are verified

Every assertion's signature is verified with hand-rolled exclusive canonicalization (exc-c14n) + RSA-SHA256 against your configured certificate — no third-party XML library. We accept a signature on the Assertion (Okta's default) or the Response (Entra's default), reject anything unsigned, and guard against XML signature-wrapping. We also check NotBefore/NotOnOrAfter (±3 min clock skew), that the Audience equals our SP entity ID, InResponseTo for SP-initiated logins, and single-use replay by assertion ID.

SCIM: automatic user & group provisioning

On Team → SCIM 2.0 provisioning → Issue token, generate a per-organization bearer token (shown once) and copy the SCIM base URL (https://<your-host>/api/scim/v2). Point your IdP's SCIM connector at that base URL and authenticate with Authorization: Bearer <token>. Users are created/updated/deactivated automatically; pushing a user into an IdP group sets their console role via your mappings.

bash

# The SCIM endpoints your IdP will call (Bearer-authed, application/scim+json):
GET    /api/scim/v2/ServiceProviderConfig
GET    /api/scim/v2/Users?filter=userName eq "user@corp.com"
POST   /api/scim/v2/Users            # provision
PATCH  /api/scim/v2/Users/{id}       # e.g. {"op":"replace","path":"active","value":false} → deprovision
POST   /api/scim/v2/Groups           # push a group
PATCH  /api/scim/v2/Groups/{id}      # add/remove members → role applied

Deprovisioning

Setting a user active:false (Okta's soft-delete) OR issuing a SCIM DELETE deactivates the user: their sessions are killed immediately and they can no longer sign in. It is reversible — active:true reactivates them, keeping the same SCIM id.

Group → role mapping

On Team → IdP group → role mapping, map an IdP group to one of the console roles (Org Admin, SRE · Cloud Admin, Deployer, Viewer). On both SAML login and SCIM provisioning, a user's highest-privilege mapped group wins; users with no mapped group get the SSO default role. The organization Owner and platform admins are never demoted by the IdP.

Entra ID sends group GUIDs

Microsoft Entra ID usually emits group object IDs (GUIDs) in its groups claim rather than names. Map the GUID string directly (paste it as the group name), and set the groups attribute to http://schemas.microsoft.com/ws/2008/06/identity/claims/groups. Okta and Google send group names under groups.

Tested-IdP matrix

IdP	Signs	Groups claim	Notes
Okta	Assertion	`groups` (names)	Import SP metadata; SCIM soft-deletes via `active:false`; `userName eq` de-dup.
Microsoft Entra ID	Response	schema-URL (GUIDs)	Map group object IDs; SCIM uses PATCH and sometimes PUT; email in the emailaddress claim.
Google Workspace	Assertion	`groups` (names)	SAML SSO; SCIM via a supported connector; email from NameID.

Signing in

Members choose Sign in with SSO on the login page and enter their work email (or org slug). Cloud Control routes them to your OIDC or SAML IdP automatically. New users are just-in-time provisioned into your organization with their mapped role.

Limitations (honest)

SP-initiated and IdP-initiated SAML are supported; SAML Single Logout (SLO) and encrypted assertions are not yet.
Signature/digest algorithm is RSA-SHA256 (the Okta/Entra default). SHA-1 is intentionally not accepted.
SCIM filtering supports userName eq and externalId eq (what IdPs use for de-dup); complex filters are not implemented.
One SAML and one OIDC config per organization; email is globally unique across organizations today.