---
title: Single sign-on and SCIM
description: Connect your organisation to Okta, Microsoft Entra ID, Google Workspace or any OIDC or SAML 2.0 identity provider, map groups to roles, require SSO and provision members with SCIM.
section: cloud
order: 13
audience: [operator]
sources: [docs/cloud-sso.md, services/nodejs-cloud/app/(console)/(shell)/settings/sso, services/nodejs-cloud/lib/sso, services/nodejs-cloud/lib/scim, services/nodejs-cloud/lib/scim/teams.ts, services/nodejs-cloud/components/sso/ScimGroups.tsx, services/nodejs-cloud/components/console/sso.ts, services/nodejs-cloud/components/console/sso-errors.ts]
features: []
---

For the owner of an organisation who wants members to sign in through the company's identity provider (IdP)
and wants the member list to follow the directory. Everything is on one console page, `/settings/sso`
(Settings, Single sign-on). Owners change it (`sso:manage`); admins can look (`sso:read`). Every change and
every SCIM call is in the audit log (`sso.*`, `scim.*`, `member.*`).

Each organisation has one IdP, over OpenID Connect or SAML 2.0. Okta, Google Workspace and Microsoft Entra ID
have guided setups; any standard IdP works with "Another provider".

## Set it up {#setup}

1. **Verify a domain.** Under Email domains, add your email domain, such as `example.com`. The page shows a TXT
   record: host `_venom-challenge.example.com`, value `venom-domain-verification=<token>`. Add it at your DNS
   host, wait a minute and press **Verify**. The cloud makes one DNS lookup when you press it, none otherwise.
   A domain is verified by one organisation at a time; at most 20 domains per organisation.
2. **Connect the identity provider.** Pick the IdP and the protocol. The page shows the values to paste into
   the IdP, each with a copy button (see [URLs](#urls)), and the fields to bring back:
   - OIDC: the issuer (`https://…`; its discovery document is `<issuer>/.well-known/openid-configuration`),
     client ID and client secret. The secret is sealed in the vault and never shown again; OIDC needs the
     deployment's `VENOM_VAULT_KEYS`.
   - SAML: the IdP's SSO URL, entity ID and signing certificate, or its metadata XML (pasted or uploaded) or
     metadata URL, which fill whatever fields you leave blank. On an edit, an empty certificate field keeps
     the stored certificates.
3. **Test sign-in.** Press **Test sign-in**. You go to the IdP and come back with the result: the email, name,
   groups and subject the IdP sent, and the role the person would get. A test signs nobody in. If it fails, the
   page says why (wrong audience, clock skew, unsigned assertion).
4. **Enable.** Enabling needs a test that passed on the current settings. Members whose email is at a verified
   domain can then choose "Sign in with SSO" on `/login`. Changing the IdP settings later (a new certificate or
   secret) keeps sign-ins working, and the page asks you to test again.
5. **Provisioning.** Choose what happens at a first sign-in (below).
6. **Require SSO** (optional). Members must then sign in through the IdP; a session from another sign-in ends on
   its next page. Owners keep their usual sign-in, so a broken IdP never locks the organisation out. Needs SSO
   enabled and a verified domain. Turning SSO off lifts it.
7. **SCIM** (optional, Okta and Entra). Create a SCIM token and give the IdP the SCIM base URL and the token.
   From then on the IdP creates, updates and deactivates members.

**Remove the identity provider** stops SSO sign-ins and lifts "Require SSO"; domains and SCIM tokens stay.

## Provisioning settings {#provisioning}

| Setting | Default | What it does |
|---|---|---|
| Just-in-time provisioning | on | someone the IdP signs in with no account becomes a member with the default role |
| Default role | `developer` | `admin`, `developer`, `billing` or `viewer`; never `owner` |
| Group rules | none | up to 50 `{group, role}` rules; the first match wins, at every sign-in. A sign-in with no matching group keeps the role |
| Groups claim | `groups` | the OIDC claim or SAML attribute to read groups from (up to 200 characters). SAML also reads Entra's group claim URI, `memberOf` and `Group` |
| Key policy on deprovisioning | `revoke` | what happens to a removed member's API keys: `revoke`, `pause` or `keep` |

No rule, default or SCIM call ever makes, changes or removes an owner: owners are made in Settings, Members (see
[Organisations, members and roles](/docs/cloud/console-orgs-members.md#change)). Someone already in the organisation with
the same email is linked to their existing account, so their keys and history stay theirs.

## URLs {#urls}

The settings page shows each with your organisation id filled in.

| What | URL |
|---|---|
| An organisation's sign-in link (IdP app tiles, bookmarks) | `https://cloud.usevenom.dev/auth/sso/start?org=<org id>` |
| OIDC redirect URI | `https://cloud.usevenom.dev/auth/sso/oidc/callback` |
| SAML SP entity ID, also the SP metadata | `https://cloud.usevenom.dev/auth/sso/saml/<org id>` |
| SAML ACS URL | `https://cloud.usevenom.dev/auth/sso/saml/<org id>/acs` |
| SCIM base URL | `https://cloud.usevenom.dev/scim/v2` |

On your own deployment, replace the origin with yours. Sign-ins start at Venom (SP-initiated); an IdP-initiated
SAML response that answers no request is refused. For an app tile, point it at the organisation's sign-in link
(Okta: "Initiate login URI"; Entra: "Sign on URL").

## Okta {#okta}

SAML (Applications, Create App Integration, SAML 2.0):

| Okta field | Value |
|---|---|
| Single sign-on URL | the ACS URL; tick "Use this for Recipient URL and Destination URL" |
| Audience URI (SP Entity ID) | the SP entity ID |
| Name ID format, Application username | EmailAddress, Email |
| Attribute Statements | `email` → `user.email` |
| Group Attribute Statements | name `groups`, a filter such as "Starts with" `venom-` |

Leave assertion signing on and encryption off. From "View SAML setup instructions", bring back the IdP Single
Sign-On URL, the Issuer and the X.509 certificate, or use the metadata.

OIDC (Create App Integration, OIDC, Web Application): sign-in redirect URI = the OIDC redirect URI, initiate
login URI = the sign-in link, grant type Authorization Code. Bring back the client ID and secret. The issuer is
`https://<your-okta-domain>` or a custom authorization server's, such as `https://<your-okta-domain>/oauth2/default`.
For groups, set the Groups claim filter (claim name `groups`).

SCIM (General, Provisioning: SCIM; then Provisioning, Integration): connector base URL = the SCIM base URL,
unique identifier `userName`, actions Push New Users, Push Profile Updates, Push Groups, authentication HTTP
Header with the SCIM token as Bearer. Under To App enable Create Users, Update User Attributes and Deactivate
Users.

## Microsoft Entra ID {#entra}

SAML (Enterprise applications, New application, Create your own application, Non-gallery; Single sign-on,
SAML): Identifier = the SP entity ID, Reply URL = the ACS URL, Sign on URL = the sign-in link, and add a group
claim. Bring back the Login URL, the Microsoft Entra Identifier and the Certificate (Base64), or the App
Federation Metadata Url. Groups arrive as object IDs unless you pick a name attribute; write group rules with
what the test sign-in shows.

OIDC (App registrations, New registration): redirect URI on platform Web = the OIDC redirect URI; a new client
secret (copy the Value, not the Secret ID); optional ID token claims `email` and `xms_edov`, and a groups claim.
The issuer is `https://login.microsoftonline.com/<tenant id>/v2.0`, not `common`. Entra sends no
`email_verified`, so Venom reads `xms_edov`; without it sign-ins are refused as unverified.

SCIM (the enterprise application, Provisioning, Automatic): Tenant URL = the SCIM base URL, Secret Token = the
SCIM token. Test Connection, save, turn Provisioning Status on. Entra syncs about every 40 minutes.

## Google Workspace {#google}

SAML (Admin console, Apps, Web and mobile apps, Add custom SAML app): copy Google's SSO URL, Entity ID and
Certificate, then set ACS URL = the ACS URL, Entity ID = the SP entity ID, Name ID format EMAIL, Name ID the
primary email, and optionally map Group membership to `groups`. Turn the app on for everyone or an
organisational unit.

OIDC also works (issuer `https://accounts.google.com`), but Google's ID tokens carry no groups, and only
Workspace accounts of the email's own domain (the `hd` claim) are accepted. Google has no SCIM for custom apps:
use just-in-time provisioning and remove people in Settings, Members.

## SCIM tokens {#scim}

Under SCIM provisioning, **Create token** (name optional, default `SCIM`) shows a `vsc_…` token once. At most 5
live tokens per organisation. **Rotate** makes a new token and revokes the old one at once; **Revoke** ends one.
Tokens are stored as SHA-256 hashes, and the list shows each one's prefix and when it was last used.

The IdP calls the SCIM 2.0 endpoints under `/scim/v2` with `Authorization: Bearer vsc_…`: `/scim/v2/Users`,
`/scim/v2/Groups`, `/scim/v2/ServiceProviderConfig`, `/scim/v2/ResourceTypes` and `/scim/v2/Schemas`. Their
reference is in the cloud API pages of this section (see the [section overview](/docs/cloud.md)).

When SCIM sets a user inactive or deletes it:

- the member is removed; their console sessions end on their next page load;
- their API keys (made by them or by their `venom cloud login`) follow the key policy; other cloud instances
  drop cached keys within 10 seconds;
- CLI logins they approved that were not picked up yet are denied;
- signing in through the IdP is refused while the SCIM user is inactive, even with just-in-time provisioning;
- owners are never deprovisioned by SCIM (409), and SCIM never changes an owner's email.

Setting the user active again makes them a member again, with the role their groups map to. Revoked keys stay
revoked; paused keys stay paused until someone resumes them under API keys.

## Groups and teams {#groups}

Once your IdP pushes groups, **Groups** under SCIM provisioning lists each one with its active and total people and
the role its group rule gives. An owner can pick an org team for a group (or **New team named "…"**) and save: the
team's people then follow the group, and nobody can edit them by hand while it syncs. Deactivating or deleting a user
in the IdP also takes them out of synced teams. Pick **Not synced** to stop; the team keeps its people. The details are
in [Teams from your identity provider](/docs/cloud/teams.md#teams-from-your-identity-provider).

## Security {#security}

- OIDC: authorization code flow with PKCE (S256), `state` and `nonce`; the id_token's signature checked against
  the IdP's JWKS (asymmetric algorithms only), with `iss`, `aud`/`azp`, `exp`, `nbf`, `iat` (two minutes of
  skew) and `email_verified`.
- SAML: signed assertions only (RSA-SHA256 or stronger), verified with the certificate you configured, never
  one inside the message; exactly one assertion, read only from the signed XML; audience, recipient,
  `InResponseTo` and times checked; each assertion accepted once. Encrypted assertions are not supported.
- Each sign-in is bound to the browser that started it and completes once, within 10 minutes.
- An SSO session opens its own organisation only.
- The cloud calls your IdP only for a sign-in, a test, a metadata URL you gave, or a DNS check you pressed, over
  https to public addresses, without redirects.

## Troubleshooting {#troubleshooting}

| Message | Cause and fix |
|---|---|
| OpenID Connect needs the vault | The deployment has no `VENOM_VAULT_KEYS`. Use SAML, or ask the operator. |
| The test sign-in failed | The result card says why. Fix the IdP or the fields, save, test again. |
| No organisation has single sign-on for that email domain. | The domain isn't verified, or SSO isn't enabled. |
| That email's domain is not verified for this organisation. | The IdP sent an email outside your verified domains. |
| Single sign-on is turned off for your organisation. | Enable it, or use another sign-in. |
| Your identity provider signed you in, but you have no account in this organisation and automatic provisioning is off. | Turn on just-in-time provisioning, or invite the person. |
| Your account was deprovisioned by your identity provider. | SCIM set the user inactive. Reactivate them in the IdP. |
| At most 5 live SCIM tokens; revoke one first. | Revoke an unused token. |

## Related

- [Sign in](/docs/cloud/console-sign-in.md)
- [Organisations, members and roles](/docs/cloud/console-orgs-members.md)
- [API keys](/docs/cloud/console-api-keys.md): resume keys paused at deprovisioning.
