API guides

Single sign-on & SCIM

Bring your own identity provider: OIDC or SAML 2.0, verified domains, enforcement, SCIM.

The API isn’t switched on in this environment yet. Everything below is accurate; the examples come from the published contract rather than a live read.

What it is

An organization can sign in through its own identity provider — OpenID Connect (Entra ID, Okta, Google Workspace and others) or SAML 2.0 — prove the domains it owns, create accounts on first sign-in, require single sign-on for every address on those domains, trust the provider's second factor, and let the provider manage members through SCIM 2.0. Everything lives in Settings → Security → Single sign-on and is for organization administrators; every change asks for a fresh second factor and is written to the security log.

A provider starts as a draft. Test it with your own account, then activate it. One provider is active at a time, and its address (the slug) cannot change once it has been active — your identity provider knows it.

The values your identity provider needs

Rivet shows these for each provider; copy them from there. Their shape:

  • OIDC redirect URI: https://<rivet-api>/api/id/auth/sso/<slug>/callback
  • SAML entity ID (audience): https://<rivet-api>/api/id/auth/saml/<slug>/metadata — also the SP metadata document, which you can import.
  • SAML ACS (reply) URL: https://<rivet-api>/api/id/auth/saml/<slug>/acs
  • SCIM base URL: https://<rivet-api>/scim/v2, bearer = a SCIM token from the panel.

Microsoft Entra ID

OIDC. Register an app (Web platform) with the redirect URI above; create a client secret. In Rivet: issuer https://login.microsoftonline.com/<tenant-id>/v2.0, the application (client) ID and the secret. Add the optional claims email, given_name, family_name; for group-to-role mapping add the groups claim (group IDs arrive — map those IDs, or use SCIM groups by name). Entra asserts MFA through amr containing mfa.

SAML. Create an enterprise application (non-gallery). Identifier = the entity ID above, Reply URL = the ACS. Under SAML signing, choose Sign SAML response and assertion with SHA-256 — Rivet requires both signatures. Download the signing certificate (Base64) and paste it into Rivet. The default claim names (emailaddress, givenname, surname, groups) are Rivet's SAML defaults, so the attribute map can stay blank. To trust Entra's MFA, Rivet reads the authnmethodsreferences claim for multipleauthn.

Okta

OIDC. Create an OIDC web application with the redirect URI above and the authorization-code grant. Issuer = your org's issuer (or an authorization server's issuer), plus client ID and secret. Include email, profile and, for mapping, a groups claim. Okta asserts MFA through amr.

SAML. Create a SAML 2.0 app: Single sign-on URL = the ACS, Audience URI = the entity ID, Name ID format EmailAddress, and add the attribute statements email, firstName, lastName and a group attribute groups — Rivet recognises these short names without a custom map. Set the response AND the assertion to signed, SHA-256. Paste the X.509 certificate into Rivet.

Attribute mapping and roles

  • Rivet reads email, first and last name, and groups. The defaults are the standard OIDC claims and Entra's SAML claim URIs, with Okta's short names as fallbacks; override any of them per provider.
  • Roles are admin or member. A group-to-role line such as Rivet Admins=admin is a ceiling: a sign-in can never grant more than its groups map to. A member-mapped group demotes an admin; the organization's last admin is never demoted.
  • Accounts created on first sign-in get the provider's default role unless a group maps one, and only for addresses on a verified domain.

Verified domains

Claim a domain and publish the TXT record Rivet shows at _rivet-verify.<domain> with the value rivet-verify=<token>, then verify. Only verified domains can be required to use single sign-on, create accounts on first sign-in, or be provisioned through SCIM. Rivet re-checks every verified domain daily; two consecutive misses revoke the claim, single sign-on stops being required for that domain until it is verified again, and the organization's admins are notified.

Requiring single sign-on, and break-glass

Requiring single sign-on needs an active provider, a verified domain and at least one break-glass account — a member who keeps password sign-in but must have an authenticator app or a passkey (never a texted or emailed code). The switch names anything still missing. Once required, the sign-in page asks for the address first and sends every address on your verified domains straight to your identity provider; the password field never appears. Break-glass sign-ins always meet Rivet's own second factor and are written to the security log.

Trusting your provider's second factor

When trusted (the default while single sign-on is required), a sign-in whose assertion carries an accepted MFA context — an OIDC amr value such as mfa, otp or hwk, or a SAML authentication-context class for a second factor, or Entra's multipleauthn — counts as Rivet's second factor. Without one, Rivet's own check still runs; a sign-in is never refused for it.

SCIM 2.0 provisioning

Create a SCIM token in the panel (it is shown once) and give your identity provider the base URL and the token. Rivet implements ServiceProviderConfig, Schemas, ResourceTypes, Users (filter by userName or externalId, PATCH per RFC 7644, PUT, DELETE) and Groups. A provisioned address must be on a verified domain. Deactivating a member (active: false or DELETE) ends their sessions everywhere and removes them from the roster; their data is kept. Group names map to roles exactly as the provider's group-to-role lines say, and membership pushed by SCIM is authoritative for that role.

Everything the identity provider does through SCIM is on the security log with the token as the actor, and every token can be revoked from the panel at once.