Jiffy

SSO Onboarding — Clerk SAML

Jiffy's enterprise customers authenticate via Clerk native SAML. This doc is the joint playbook for Jiffy staff + the customer's IdP admin.

1. Jiffy staff: create the Clerk enterprise connection

  1. Sign in to jiffylabs.app with a @jiffylabs.ai email.
  2. Open /admin/sso.
  3. Paste the customer's Clerk organization id (e.g., org_abc123...) and click Load. The connections table lists any existing SAML connections for the org.
  4. Click Create connection and fill in:
  • Connection name — human-readable label (e.g., acme-corp-prod).
  • Allowed domain — the customer email domain SAML will accept (e.g., acme.com).
  • IdP metadata URL — preferred. Clerk will fetch and verify.
  • IdP metadata XML — paste the raw XML if the IdP does not publish a metadata URL.
  1. Click Create connection. Jiffy returns three values the customer IdP admin needs:
  • ACS URL — https://clerk.jiffylabs.app/v1/saml/acs/<connection_id>
  • Entity ID — https://clerk.jiffylabs.app/v1/saml/metadata/<connection_id>
  • SP metadata URL — optional; customer IdP can consume this directly.

2. Customer IdP admin: add Jiffy as a SAML app

  1. In the IdP's SAML app console, create a new application.
  2. Paste the ACS URL into the Assertion Consumer Service (ACS) field.
  3. Paste the Entity ID into the Entity ID / Audience field.
  4. Ensure the NameID format is emailAddress and the assertion maps the user's verified email.
  5. Optionally: configure SAML attributes firstName, lastName, groups — Jiffy does not consume groups in this sprint but we reserve the claim for future role mapping.

3. First-login and role seeding

The first user from the customer org to sign in via the new SAML connection is granted admin in org_role per the Sprint 76 seed trigger. Every subsequent user joining the org lands as analyst by default.

Staff can re-key a user's role through a direct SQL update on org_role — a customer-facing RBAC admin UI is deferred to a follow-up sprint.

4. Verification checklist

  • /admin/sso shows the new connection with status = active.
  • A test SSO login from a verified customer email completes Clerk's hosted SAML flow and lands at the customer's org-scoped dashboard.
  • audit_log contains a settings.updated row with resource_type = sso_connection + details.event = sso.provisioned.

5. Rollback

To remove a connection, click through Clerk's backend dashboard or issue DELETE /v1/saml_connections/<id> against Clerk directly. Jiffy's /admin/sso does not yet surface delete UI.

See also: