Single sign-on (SSO)

On Business and Enterprise plans, route your team's CustomerHero sign-ins through your own identity provider. CustomerHero supports both SAML 2.0 and OpenID Connect (OIDC), and on Business+ you can also provision users with SCIM 2.0.

What you get

  • Centralized auth. Removing a user from your IdP removes their CustomerHero access on their next sign-in.
  • Domain-based routing. Anyone signing in with an email at a verified domain is sent through your SSO connection automatically.
  • SCIM provisioning. (Business+) Pre-create accounts and roles from your IdP so new hires never see a "request access" screen.
  • Audit logging. Every sign-in, role change, and SCIM event lands in the org audit log with retention up to 365 days (Business) or unlimited (Enterprise).

Prerequisites

  • A Business or Enterprise plan.
  • An admin role on the CustomerHero org. Only org admins can configure SSO connections.
  • Admin access to your identity provider (Okta, Azure AD / Entra ID, Google Workspace, JumpCloud, OneLogin, or any generic SAML 2.0 / OIDC IdP).
  • One or more verified email domains. CustomerHero verifies domain ownership via DNS TXT before it will route sign-ins.

Setup overview

  1. Verify your domain. From Settings → SSO → Domains, add your email domain and copy the DNS TXT record we generate. Add it to your domain registrar; verification usually takes under a minute.
  2. Create the connection. From Settings → SSO → New connection, pick SAML or OIDC. The page shows the metadata you need to give your IdP — ACS URL, Entity ID, and the attribute mapping for email, given_name, family_name.
  3. Configure your IdP. Create the matching application in your IdP, copy back the metadata URL or signing certificate, and paste it into the CustomerHero connection.
  4. Test before enforcing. Use the Test sign-in button on the connection page. CustomerHero opens a private window through your IdP and shows you the resolved attributes.
  5. Enforce. Toggle Required for this domain once a successful test round-trips. Existing email/password sessions stay valid until they expire — admins can force a global sign-out from the same page if you need an immediate cutover.

SCIM 2.0 (Business+)

SCIM lets your IdP push user lifecycle events to CustomerHero, so you don't rely on lazy provisioning at first sign-in. Under Settings → SSO → SCIM, generate a SCIM token and copy the SCIM endpoint URL. Configure your IdP with both, then map:

  • userName → CustomerHero email (must match a verified domain)
  • name.givenName, name.familyName → display name
  • roles → CustomerHero role (admin or agent). Defaults to agent if unset.

Deactivating a user in your IdP soft-deletes their org membership in CustomerHero — their sessions are revoked immediately and their attribution on past conversations is preserved.

Troubleshooting

The connection page shows the last 20 sign-in attempts with status, IdP-returned attributes, and error message. Common fixes:

  • "Domain not verified". Re-check the DNS TXT record. Some registrars take up to 24h to propagate.
  • "No email in assertion". Your IdP isn't sending the email attribute. Map email (SAML) or include email in the OIDC scopes.
  • "Signature verification failed". The IdP's signing certificate has rotated. Re-import the metadata URL.

Next steps

Manage who has which role inside CustomerHero in the Team & roles guide.