Skip to content
Docs menu

Single sign-on and SCIM

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.

View .md

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

  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), 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

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). Someone already in the organisation with the same email is linked to their existing account, so their keys and history stay theirs.

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

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

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

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

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).

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

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.

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

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.