Guides

Enable SSO

Let an enterprise tenant sign in with their own identity provider over OIDC, and route their users by email domain. SAML 2.0 and SCIM provisioning are on the roadmap.

Preview

Drop-in components and the SDKs are in development and available to design partners. Samples are illustrative of the planned API.

Single sign-on connects an organisation to its own identity provider (IdP) such as Okta, Entra ID or Google Workspace. Enterprise SSO over OIDC is live today; SAML 2.0 is on the roadmap. A connection belongs to one organisation, so each tenant manages its own login while your application sees the same OrthID session and actor model throughout.

1. Create the connection

Create an OIDC SSO connection on the organisation. You supply the issuer, client ID and client secret from the tenant’s IdP, and the domains whose users route to it. OrthID returns the redirect values to hand back to the IdP admin.

scripts/create-sso-oidc.ts

import { orthid } from "@orthid/sdk";

// OIDC connection for an organisation.
const connection = await orthid.sso.createConnection({
  organizationId: "org_clinic_42",
  protocol: "oidc",
  name: "Entra ID (Acme Health)",
  oidc: {
    issuer: "https://login.microsoftonline.com/<tenant-id>/v2.0",
    clientId: process.env.ACME_OIDC_CLIENT_ID,
    clientSecret: process.env.ACME_OIDC_CLIENT_SECRET,
    scopes: ["openid", "email", "profile"],
  },
  // Domains whose users are routed to this connection.
  domains: ["acmehealth.com"],
});

SAML 2.0 is on the roadmap

OrthID’s enterprise SSO is live over OIDC. SAML 2.0 connections, with IdP metadata and attribute mapping, are planned and available to design partners. If your tenant’s IdP is SAML-only today, talk to us about the design-partner programme.

2. Route users by domain

The domains on a connection drive domain-based routing. When a user enters an email whose domain matches a verified connection, the hosted <SignIn/>skips the password step and sends them straight to their IdP. A domain must be verified by the organisation before it routes traffic, which stops one tenant from claiming another tenant’s users.

scripts/verify-domain.ts

import { orthid } from "@orthid/sdk";

// Begin verification: returns a DNS TXT record to publish.
const { txtRecord } = await orthid.sso.startDomainVerification({
  organizationId: "org_clinic_42",
  domain: "acmehealth.com",
});
// txtRecord -> "orthid-verify=8c1f...": add it to the domain's DNS.

// Once the record is live, confirm it.
await orthid.sso.verifyDomain({
  organizationId: "org_clinic_42",
  domain: "acmehealth.com",
});

Verified domains only

Only verified domains route to a connection. Until the DNS record is confirmed, users at that domain keep their existing login. This is what makes domain-based routing safe in a multi-tenant deployment.

3. Provision with SCIM (roadmap)

SCIM provisioning is planned, not yet shipping. The intent is to keep your tenant’s directory and OrthID in sync: when the IdP creates, updates or deactivates a user, OrthID would mirror the change, so a deprovisioned employee loses access without a manual step. The planned shape enables SCIM on a connection to get a base URL and a bearer token to paste into the IdP. Until SCIM lands, use email invitations or direct provisioning to manage membership.

SCIM provisioning is on the roadmap

Automatic directory sync over SCIM is in development and available to design partners. The snippet below is illustrative of the planned API, not a live endpoint.

scripts/enable-scim.ts (planned)

import { orthid } from "@orthid/sdk";

// Planned API: enable SCIM on an existing connection.
const scim = await orthid.sso.enableScim({
  connectionId: connection.id,
});

// Configure these in the IdP's provisioning settings.
console.log(scim.baseUrl);
console.log(scim.token);   // bearer token, shown once

Next steps

Invite members to add people who are not yet in the IdP, or to seed the first admins.
Add MFA as a second factor for users who sign in without an enterprise IdP.