SAML SSO

OpenPhn supports SAML 2.0 single sign-on for tenants on the Pro and Scale tiers, federated through WorkOS. Once configured, members signing in with your corporate email domain are routed to your identity provider — no password required.

How it works

1. Owner sets up the connection in Settings → SSO. We create a WorkOS organization for your tenant and return a one-time admin portal link.
2. You upload IdP metadata in the WorkOS admin portal (Okta XML, Azure AD federation metadata, etc.). WorkOS handles the SAML protocol details.
3. Members sign in by email. The Login page detects their domain and shows a "Sign in with SSO" button. Clicking it redirects to your IdP, then back to OpenPhn with a fresh session.

New users (matching your claimed email domain) are JIT-provisioned with the member role on first SSO login. Existing users with the same email are attached to your tenant.

Configuring with Okta

1. In Okta, create a new SAML 2.0 application. Copy the SP Entity ID and ACS URL from the WorkOS admin portal into your Okta application configuration.
2. Set the Name ID format to EmailAddress.
3. Attribute statements: map email to user.email, firstName to user.firstName, lastName to user.lastName.
4. Save and download your Okta application's metadata XML.
5. Upload the XML in the WorkOS admin portal, click "Activate Connection".
6. Your Settings → SSO page in OpenPhn will show "Active" within a few seconds.

Configuring with Azure AD (Microsoft Entra ID)

1. In Entra ID, register a new Enterprise Application → "Non-gallery application" → SAML SSO.
2. Copy the Identifier (Entity ID) and Reply URL (ACS URL) from the WorkOS admin portal into the Entra Basic SAML Configuration section.
3. User attributes & claims: ensure emailaddress is the unique identifier (Name ID).
4. Download the Federation Metadata XML from the SAML Signing Certificate section.
5. Upload the XML in the WorkOS admin portal, click "Activate Connection".
6. Settings → SSO will flip to "Active" within a few seconds.

Configuring with Google Workspace

1. In the Google Admin Console: Apps → Web and mobile apps → Add custom SAML app.
2. Copy the SSO URL, Entity ID, and Certificate from the Google Admin Console into the WorkOS admin portal.
3. Attribute mapping: email → "Primary email", first_name → "First name", last_name → "Last name".
4. Activate the app for your users in Google Admin.
5. Click "Activate Connection" in the WorkOS admin portal.

Require SSO

When SSO is active, you can enforce it in Settings → SSO by toggling Require SSO. This rejects password login for all members EXCEPT Owners.

The Owner break-glass exists so a misconfigured IdP never locks out the billing contact. If your Owner can't sign in via SSO, they can always password-login — and from there, disable the Require SSO toggle to restore access for everyone else.

What gets audited

Every SSO event is appended to the tamper-evident audit chain (see /v1/admin/audit/verify):

• sso.connection_created — Owner clicks "Set up SSO"
• sso.connection_activated — WorkOS confirms IdP setup completed
• sso.connection_deleted — Owner disables the connection
• auth.sso_login — successful SSO login (with is_jit flag for first-time users)
• auth.sso_login_failed — captured assertion didn't match the claimed email domain (potential attack)

Limitations (as of launch)

• One IdP per tenant. Multi-IdP per tenant is on the roadmap; ask if you need it.
• No SCIM directory sync. JIT-on-login is the only provisioning path. Deprovisioning happens manually via Settings → Team. SCIM is on the roadmap for the Scale tier.
• One email domain per tenant. If your team uses multiple domains, contact us — we can configure additional domain claims server-side.

Tier availability