Skip to content
DashboardWebsite

Quick Start: SSO & SCIM

Just want to do it in the dashboard? See the guide: Turn on single sign-on for the org.

This page explains how org admins connect an identity provider for single sign-on (SSO) and configure SCIM provisioning for users and groups. SSO and SCIM are separate from the password and invitation flow in Authentication.

  • Use SSO when an organization wants its identity provider (Entra ID, Okta, Google, …) to handle login.
  • Use SCIM when it also wants the identity provider to manage users and groups.

Each organization can connect one identity provider over OIDC or SAML 2.0. Members then sign in without a password. In the dashboard: Organization → Access → SSO. An org admin can also configure SSO through the API. Both protocols follow the same account rules, domains and roles. Only the setup differs.

protocol is fixed when the connection is created. To switch, delete the connection and create a new one.

In the dashboard: Organization → Access → SSO. You can also create an OIDC connection through the API:

Terminal window
curl -X POST http://localhost:8000/v1/orgs/{org_id}/sso \
-H "X-API-Key: change-me-to-a-strong-secret" \
-H "Content-Type: application/json" \
-d '{
"display_name": "Acme Corp",
"issuer": "https://login.microsoftonline.com/{tenant-id}/v2.0",
"client_id": "<app-registration-client-id>",
"client_secret": "<app-registration-client-secret>",
"default_role": "member",
"allowed_domains": ["acme.com"]
}'

In Entra ID:

  1. Register an application.
  2. Grant it the openid, email, and profile scopes.
  3. Set its redirect URI to {your-api-base-url}/auth/sso/callback.

Use SAML when your IdP does not support OIDC, as with ADFS and some Okta and Ping setups. SAML needs the deployment’s public URL: an operator sets server.public_base_url. Without it, the SAML endpoints answer 503.

In the dashboard: Organization → Access → SSO. You can also create a SAML connection through the API by providing the IdP’s metadata XML:

Terminal window
curl -X POST http://localhost:8000/v1/orgs/{org_id}/sso \
-H "X-API-Key: change-me-to-a-strong-secret" \
-H "Content-Type: application/json" \
-d "$(jq -n --rawfile xml idp-metadata.xml '{
protocol: "saml",
display_name: "Acme ADFS",
idp_metadata_xml: $xml,
default_role: "member",
allowed_domains: ["acme.com"]
}')"

Instead of the metadata, you can pass idp_entity_id, idp_sso_url (the HTTP-Redirect sign-in URL) and idp_certificates (PEM).

The response’s service_provider holds what the IdP needs:

IdP fieldValue
Entity ID / Identifier / Audienceservice_provider.entity_id: {your-api-base-url}/auth/sso/saml/{org_id}/metadata
ACS URL / Reply URL (HTTP-POST)service_provider.acs_url: {your-api-base-url}/auth/sso/saml/{org_id}/acs
SP metadata URLservice_provider.metadata_url, if the IdP can import it

In the IdP:

  1. NameID. Send a persistent identifier: the stable key the account is linked to. An email address also works, but if it changes, the member needs to link their account again.
  2. Email. Send it as NameID in the emailAddress format or as an attribute. The server reads the attributes ADFS, Entra ID and Okta send by default (http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, urn:oid:0.9.2342.19200300.100.1.3, email, mail). For any other name, set email_attribute.
  3. Signing. Sign the assertion or the response with SHA-256. SHA-1 signatures are refused.
  4. Encryption. Turn assertion encryption off. Encrypted assertions are not supported yet. The connection is still over TLS.

Not supported:

  • IdP-initiated sign-in. A response that answers no request is refused, because nothing ties it to the browser that receives it. For a tile in the Okta or Entra app launcher, create a bookmark tile that points at {your-api-base-url}/auth/sso/{org_id}/start.
  • Single Logout and signed AuthnRequests.

Certificate rotation. In the dashboard: Organization → Access → SSO. You can also call GET /v1/orgs/{org_id}/sso to see each certificate’s expires_at. Before the IdP switches to a new certificate, PATCH the connection with both certificates in idp_certificates, or with the new metadata. Remove the old certificate once the IdP has switched.

Members sign in in one of two ways:

  • From the login page. Enter an email address and select Continue with SSO. The dashboard calls POST /v1/auth/sso/discover, which finds the org from a verified domain in allowed_domains. The dashboard then redirects to GET /v1/auth/sso/{org_id}/start.
  • With a direct link. GET /v1/auth/sso/{org_id}/start skips the discovery step. Orgs can share this link with their members.

In both cases, the browser goes to the IdP to authenticate. An OIDC IdP redirects back to GET /auth/sso/callback. A SAML IdP posts its response to the ACS URL. The server verifies it, then continues at GET /auth/sso/saml/complete in the same browser. The server completes the login and sets the same session cookie as a password login.

The server finds the account by the IdP’s identity, never by email. For OIDC, that is the iss and sub claims. For SAML, it is the IdP’s entity id and the NameID:

  • Known identity. The server signs in the account linked to it, even if the email has changed at the IdP.
  • New identity, new email. The server creates an account, links the identity, and adds the account to the org with default_role.
  • New identity, email already has an account. The server does not sign it in. The login page asks the user to sign in with their password first. The dashboard then sends them back through the IdP to link the two. After that link, SSO alone signs them in. The password keeps working.
  • Account provisioned by SCIM. An account with no password and no linked identity, already a member of this org, is linked on its first SSO login.

If the account has its own TOTP enabled, the user still enters a code after the IdP.

In the dashboard: Organization → Access → SSO. Signed-in members can also link from a direct link: GET /v1/auth/sso/{org_id}/link. It refuses an account that is not a member of the org, and a request started from another site.

default_role cannot be owner. As with invitation links, an automatically granted role never gives full ownership.

allowed_domains is optional. When it is set, the server rejects login for any email outside these domains.

A domain does more once you verify it. Verification proves that your org controls the domain’s DNS:

  1. In the dashboard: Organization → Access → SSO. Read domain_verification_record from the page or call GET /v1/orgs/{org_id}/sso. Its value is opentremor-verification=<org_id>.
  2. Publish that value as a TXT record at _opentremor-challenge.<domain>, for example _opentremor-challenge.acme.com.
  3. In the dashboard, select Verify next to the domain, or call POST /v1/orgs/{org_id}/sso/domains/{domain}/verify.

A verified domain sends the login page’s Continue with SSO box to your connection, and no other organization can verify it. Other organizations can list a domain, but until they verify it, it gives them none of this.

A verified domain also overrides the platform’s Google / Microsoft sign-in buttons, if the deployment offers them. When an address in that domain selects Continue with Google, the server sends it to the org’s SSO connection instead. Members cannot bypass the org’s identity provider with a personal account on the same address.

An SSO session meets the organization’s require 2FA policy. The IdP handles the second factor. TOTP enrollment is only available to password accounts.

In the dashboard: Organization → Access → SSO → Sign-in methods. To make SSO the only way into the organization, set the org’s sign-in methods to ["sso"] once the connection is enabled.

SSO handles authentication: how a member signs in. SCIM 2.0 handles the user lifecycle: the IdP pushes users and groups into an org on its own schedule, even if nobody signs in. Entra ID and any other SCIM-compliant IdP are supported.

SSO and SCIM are independent. An org can use either, both, or neither.

In the dashboard: Organization → Access → SSO → SCIM. Enable SCIM there to receive a tenant URL and bearer token. The token is shown once. You can also enable SCIM through the API:

Terminal window
curl -X POST http://localhost:8000/v1/orgs/{org_id}/scim \
-H "X-API-Key: change-me-to-a-strong-secret" \
-H "Content-Type: application/json" \
-d '{
"default_role": "member",
"group_role_mappings": [
{"pattern": "^admin", "role": "admin"}
]
}'
# → {"token": "..."}
# Copy the token now. It is not shown again.

In Entra ID:

  1. Open the Enterprise Application and select Provisioning.
  2. Set the mode to Automatic.
  3. Set Tenant URL to the base_url from GET /v1/orgs/{org_id}/scim, for example https://your-api/scim/v2/{org_id}.
  4. Set Secret Token to the token above.
  5. Assign users and groups to the application.

Entra provisions them on its own cycle, about every 40 minutes. Use Provision on demand to provision immediately.

SCIM objects map to OpenTremor as follows:

  • Users. A SCIM User with the email of an existing account adds that account to the org. It never links an identity or signs anyone in. If no account exists, SCIM creates one with no password; the member’s first SSO login links it. PATCH .../Users/{id} with {"active": false} deactivates the org membership. Entra sends this when you unassign a user. active: true reactivates the membership.
  • Groups. A SCIM Group maps 1:1 to a Team. Creating, renaming, or deleting a group does the same to the Team. Group membership syncs to Team membership.
  • Group → role mapping. group_role_mappings is an ordered list of {pattern, role} rules. Each pattern is a regular expression matched against the user’s SCIM group names. The first matching rule wins. If no rule matches, default_role applies. Neither role nor default_role can be owner.

Teams normally have no effect on access control. Group → role mapping is a deliberate exception, with limits:

  • Only SCIM group-membership changes recalculate the role. Team changes in the dashboard do not.
  • The mapping never applies to a member who is owner. SCIM cannot demote or remove the org’s owner.

In the dashboard: Organization → Access → SSO → SCIM. You can rotate or revoke the token there. The SCIM bearer token is not a regular API key (/auth/keys). It authorizes only /scim/v2/{org_id}/*. You can also rotate it (POST /v1/orgs/{org_id}/scim/rotate-token) or revoke it (DELETE /v1/orgs/{org_id}/scim) without affecting SSO.