Single sign-on with OIDC
Configure bring-your-own OIDC single sign-on for your organization: issuer, client id and secret, default role, email domains, discovery, the login flow and JIT provisioning.
Cloud Control supports bring-your-own OIDC single sign-on. An org admin configures one OIDC identity provider for the organization; members then sign in with their work email and are redirected to your IdP. The whole SSO configuration surface is org-admin only.
Configure your identity provider
Provide these fields to `POST /api/org/sso` (or the SSO section of the console):
| Field | Meaning |
|---|---|
issuer | Your IdP's issuer URL (must be https://). Cloud Control runs OIDC discovery against it. |
clientId | The OIDC client (application) id you registered for Cloud Control. |
clientSecret | The client secret. Sealed in an AES-256-GCM envelope and never returned. |
defaultRole | Role assigned to users provisioned on first login — one of Viewer, Deployer, SRE · Cloud Admin, Org Admin. |
emailDomains | Up to 20 email domains that route to this IdP (for example acme.io). |
On save, Cloud Control performs OIDC discovery against the issuer immediately and stores the resolved authorization, token and JWKS endpoints. A typo'd issuer fails at save time — not at your first user's sign-in. The redirect URI to register at your IdP is https://<your-console-host>/api/auth/oidc/callback.
The login flow
- Start
A user submits their work email (or your org slug) to `POST /api/auth/oidc/start`. Cloud Control matches the email domain (or slug) to an enabled SSO config and returns the IdP authorize URL.
- Authenticate at your IdP
The browser goes to your IdP with state, nonce and PKCE (S256) — all held server-side in a single-use record; only the state's hash is stored.
- Callback
Your IdP redirects back to
/api/auth/oidc/callback. Cloud Control exchanges the code, verifies the RS256 ID token against your JWKS, and checks state and nonce. - Provision and sign in
If the user is new, they are provisioned just-in-time with the organization's
defaultRole; then a session is issued.
Enable, disable and update
SSO is enabled on save. Toggle it later with `PATCH /api/org/sso` ({ enabled: true | false }). To rotate the secret, POST again with a new clientSecret; leave the secret blank to keep the existing envelope while changing other fields. Configuration changes are audited as org.sso_configured, org.sso_enabled and org.sso_disabled.
The client secret is encrypted under CC_DATA_KEY. On Vercel this must be set before an org can save an SSO config; without a keyring the save returns 503. See Environment variables.
Roadmap
OIDC BYO-IdP and SAML 2.0 + SCIM 2.0 provisioning with IdP group-to-role mapping are real today — see SAML SSO & SCIM provisioning.