Single Sign-On (SAML)

Single Sign-On lets your team sign in to Churnkey through your own SAML 2.0 identity provider, so access follows the accounts you already manage in Okta, Microsoft Entra ID, Google Workspace, JumpCloud, OneLogin, Auth0, Ping, or any other provider that publishes standard SAML metadata. The settings live in the dashboard on the Team page under Single Sign-On (SAML), where the card is titled Single Sign-On (SAML) with the subtitle "Let your team sign in to Churnkey through your own identity provider."

Two things shape everything else on this page. First, Churnkey support attaches the SAML connection for you — there is no self-serve setup form, so getting started is a message rather than a wizard. Second, once the connection exists, your workspace Owner decides whether SSO is merely available or required, because the lockout risk of requiring it is yours to weigh.

What Churnkey supports

• SAML 2.0, service-provider-initiated. Every sign-in starts from Churnkey — from the login page, a bookmark, or a portal tile that points at your workspace start URL.
• Any provider that publishes standard SAML metadata. You send us the metadata URL or the XML; we read the entity ID, the sign-in URL, and the signing certificate from it.
• One connection per workspace. New metadata replaces the existing connection rather than adding a second one, which is how a rotated certificate gets applied.
• A response has to match a request. Every assertion must correspond to a sign-in Churnkey started, in the same browser, and each request can be used once. This is worth knowing if you are writing up Churnkey for your own security review.

Not supported today:

• Identity-provider-initiated login. An assertion your provider sends us out of the blue is rejected. If you want a tile in your Okta or Entra dashboard, point it at your workspace start URL — see How your team signs in.
• Automatic user provisioning (SCIM). SSO authenticates people; it never creates Churnkey accounts. Everyone still has to be invited to the workspace.
• Group or role mapping. Churnkey roles are set in Churnkey, not read from your directory. See Roles and Permissions.

Who does what

Viewing is genuinely open: every role, Viewer included, can open the tab and copy the service provider values, so the person configuring your identity provider does not need elevated access in Churnkey. Enforcement is deliberately left to your Owner, since Owners keep a way in if the provider goes down.

Getting SSO set up

1. Gather three things. Your identity provider's metadata URL — it must use https, and it must be the final URL, because we do not follow redirects — or the metadata XML itself. The email domains your team signs in with. And confirmation that your assertion carries an email address (see The email address in your assertion); a missing email claim is the most common reason a first test sign-in fails.
2. Message support. On Team → Single Sign-On (SAML) you will see Single sign-on is not configured yet, with the note "Churnkey support sets up the connection for you. Message us with your identity provider's metadata URL or XML, and we will take it from there." and a Message support button that opens a prefilled chat. You can also email [email protected].
3. Test before you require it. Once we confirm the connection is attached, have one person who is already a member of the workspace sign in through your provider end to end. Only after that does your Owner turn Require Single Sign-On on.

Values you give your identity provider

The Churnkey Service Provider Details block on the settings page carries exactly three values, each with a Copy button. These are the same for every workspace:

The values shown on your own dashboard are the authoritative ones — copy them from there if you can, and use the table above if you are building the SAML application before the connection exists.

A few protocol details for the application you create in your provider:

• Churnkey sends its authentication request over HTTP-Redirect and expects the response back as an HTTP-POST to the ACS URL.
• Assertions must be signed. Churnkey can hold more than one signing certificate for a connection at a time, so you can publish the next certificate before you rotate to it and avoid downtime.
• A sign-in must be finished at your provider within 10 minutes of starting at Churnkey, otherwise the request has expired and the person needs to start again.
• Churnkey does not sign its authentication requests, so leave any "require signed authentication requests" option in your provider turned off. Turning it on will break every sign-in.

The email address in your assertion

Churnkey identifies the person by the email address in the assertion, and it reads that address from exactly one of two places:

• the standard claim http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, or
• a claim named exactly email.

Nothing else is read — there is no fallback to the Name ID. The address is lowercased and must contain an @. If neither claim carries a usable address, the person is sent back to the Churnkey login page with the message "Your identity provider did not send an email address, so we could not sign you in. Ask whoever administers it to include the email claim."

The email domains you claim

Your claimed domains are how Churnkey's login page finds your identity provider: someone types their work email, and the domain tells us which workspace — and which provider — to send them to. Two rules follow from that:

• A domain belongs to exactly one workspace. If a domain of yours is already claimed elsewhere, the claim is refused with "That email domain is already claimed by another organization". This happens more often than you would expect, usually because someone at your company created a Churnkey workspace earlier.
• Public mailbox domains cannot be claimed. Domains like gmail.com, outlook.com, yahoo.com and similar are refused with a message of the form "gmail.com" is a public email provider and cannot be claimed. Claim the domains your company actually owns.

Removing an SSO connection immediately revokes its active SSO sessions, signing those users out. It does not release the domains that workspace claimed. So moving a domain from one workspace to another is a support request rather than something either workspace can do for itself — message us and we will move it.

What you see once SSO is set up

Once a connection is attached, the settings page replaces the empty state with an Identity Provider summary block showing four read-only values:

• IdP Entity ID — the entity ID we read from your metadata.
• Sign-in URL — where Churnkey sends people to authenticate.
• Claimed domains — the email domains routed to this workspace.
• Certificate expires — the expiry date of your signing certificate.

Where no domains have been claimed yet the field reads None, and where no expiry could be read from the certificate it reads Unknown.

Outside the Team page, an SSO-enabled workspace also carries an SSO chip in the workspace switcher, with the hover text "Signs in through its own identity provider".

Requiring SSO for your team

Require Single Sign-On is a Required / Optional switch on the same page, under the note "Members must sign in through your identity provider. Organization owners keep password sign-in as a fallback."

Only the workspace Owner can move it. Everyone else sees the switch, disabled, with a tooltip explaining why. Turning it on asks for confirmation first, in a dialog titled Require single sign-on? that reads "Members without an organization owner role will no longer be able to sign in with a password. Organization owners keep password sign-in as a fallback.", with Require SSO to go ahead and Back to think again. Turning it off does not ask. Either way you get a confirmation — Single sign-on is now required or Single sign-on is now optional.

Requiring SSO takes effect immediately for sessions that already exist, not just for future sign-ins: on their next request, anyone signed in with a password or Google is returned to the login page to sign in through your provider. Owners are the exception, as everywhere else on this page. So flip the switch when the team can absorb a round of re-authentication, not in the middle of their workday.

If the switch is disabled for you, the tooltip gives one of three reasons, in this order:

1. "Connect an identity provider before requiring SSO." — the workspace has no SAML connection yet. Everyone sees this one until the connection is attached, Owners included.
2. "Only organization owners can change this." — a connection exists, but you are not the Owner.
3. "This organization has no owner yet. Invite an owner, or promote a member to owner, so someone keeps password sign-in if the identity provider is unavailable."

Because the reasons are evaluated in that order, an Admin looking at a workspace with no connection sees the first message rather than the one about ownership. An existing Owner can promote another member to Owner through Team > Members > Edit Role. If your workspace has no Owner, existing Admins are not automatically promoted; contact support to assign an Owner. See Roles and Permissions.

What requiring SSO does and does not cover

• Everyone except Owners must use SSO. Owners keep password sign-in — deliberately: it is the fallback for the day your provider is unavailable.
• Data API keys are unaffected. Server-to-server integrations keep working exactly as before, because a key authenticates an integration rather than a person.
• MCP and other OAuth connections authorized before you required SSO stop working. Each person signs in through SSO once and then reconnects the client — a one-time step, not a permanent limitation. Owners are not affected.
• Two-factor authentication. If your workspace requires Churnkey's email 2FA, the settings page adds a Two-factor authentication and SSO note: "Members who sign in via SSO are already verified by your identity provider, so Churnkey doesn't also email them a code. Password and Google sign-ins still require one."

How your team signs in

There are three ways in, and all of them start from Churnkey.

1. From the login page. Click Sign in with SSO, type the address in the Work email field, and press Continue with SSO →. Churnkey looks up which workspace claims that email domain and sends the person to your provider. ← Back to sign-in options returns to the password form.
2. From a bookmark or an identity provider portal tile. Your workspace has a start URL of the form https://api.churnkey.co/v1/auth/saml/authorize?org=<your-workspace-id>. Support gives you the exact URL — it is not shown in the dashboard. Point an Okta or Entra dashboard tile at it and people land in Churnkey in one click. This is how you get a portal tile, since true identity-provider-initiated logins are rejected.
3. From an invitation. When a workspace requires SSO, the invitation email sends the person straight into your provider instead of carrying a magic link, because a magic-link session would be refused on its first request anyway.

For an invitation to work, the person needs to exist in two places: as a member of the Churnkey workspace, and in your identity provider with the Churnkey application assigned to them. The order does not matter. If the assertion is valid but the address is not a member of the workspace, the sign-in stops with "Your identity provider signed you in, but you have no access to this workspace." — invite them on the Team page and try again. Owners receive the ordinary invitation, since they keep password sign-in.

One consequence worth telling your team about: an SSO session is bound to the workspace that asserted it. In the workspace switcher, other workspaces are dimmed with the hint "This session came from your identity provider. Sign out to switch workspaces." Anyone who works across several Churnkey workspaces signs out and back in to move between them — see Multi-Workspace Support.

Rotating your signing certificate

The Identity Provider block shows Certificate expires. Within 30 days of that date the settings page adds a warning line — The signing certificate expires in <N> days (singular at one day), or The signing certificate has expired once the date has passed — followed by the instruction "Rotate the certificate in your identity provider and send us the new metadata. Sign-ins keep working until your provider starts signing with a new key, and break as soon as it does."

So the rotation is: rotate the certificate in your provider, send us the new metadata, and we replace the connection. Replacing the connection does not touch your claimed domains. And because Churnkey can hold more than one certificate for a connection at a time, you can publish the next certificate first and have us attach it before your provider starts signing with it, which makes the rotation invisible to your team.

One thing to plan for: that warning appears on the SSO settings page only. Nobody is emailed about an approaching expiry, so put your own reminder in a calendar.

If your identity provider is unavailable

There are two ways back in, in this order.

1. A workspace Owner signs in with their password. SSO enforcement never applies to Owners. That is the whole reason Churnkey refuses to require SSO in a workspace with no Owner — the dashboard says so itself: "This organization has no owner yet. Invite an owner, or promote a member to owner, so someone keeps password sign-in if the identity provider is unavailable."
2. If no Owner can sign in, contact Churnkey support. Reach us through the in-app chat or at [email protected] and we can restore access to the workspace while you fix your provider.

When a sign-in fails

Every message below except SSO Required appears under the title Single Sign-On Failed on the Churnkey login page.

The last two are different in kind from the first five: they happen to a session that already exists, on any dashboard request, rather than during a sign-in at your provider. One exception worth knowing, because it looks like a bug otherwise — when the refusal comes from trying to switch workspaces, the workspace switcher reports it in place and the existing session stays valid, so there is no redirect and no code in the URL.

Three more things people run into, none of which produce a code:

• "I clicked Forgot Password." For a member of a workspace that requires SSO the reset is refused up front, with the message This organization signs in with SSO. Use "Continue with SSO" on the login page. Owners are the exception: their password reset still works, because password sign-in is their fallback.
• A tab left open after the provider. The hand-off back to Churnkey is single-use and lasts about five minutes. A stale tab shows Sign-in link expired with "This single sign-on link is no longer valid. Please start over from your identity provider." Start the sign-in again.
• A whole office signing in at once. Behind a single outbound IP address, some people may see "Too many SSO login attempts, please try again in a minute". Waiting a minute is the fix.

Google sign-in is not SSO

Google sign-in on the Churnkey login page signs in an existing Churnkey user whose email address matches the Google account. There is nothing to configure and no account linking step. If no Churnkey account uses that address, the sign-in is refused with "No Churnkey account uses this Google address. Sign in another way, or ask an admin to invite you."

The operative part for an administrator: Google sign-in is not SSO. In a workspace that requires SSO, a Google session is bounced back to the login page with the SSO Required message, exactly like a password session. Google sign-ins also still receive the workspace's 2FA email code, where SSO sign-ins do not.

Common questions

Can we launch Churnkey from our Okta or Entra dashboard?
Yes, as a tile pointing at your workspace start URL — see How your team signs in. True identity-provider-initiated logins are not supported.

Will new hires get Churnkey accounts automatically?
No. Someone with the Owner or Admin role invites them from the Team page. SSO authenticates people; it never creates accounts.

Does removing someone from our identity provider remove their Churnkey access?
Not by itself. It stops new SSO sign-ins, but their workspace membership stays, a session they already have keeps working until it expires (sessions last seven days), and unless your workspace requires SSO they can still sign in with a password or Google. Offboarding someone means removing them from the workspace on the Team page as well.

Someone at our company signed up before we set up SSO. What happens to that workspace?
It stays theirs, and it does not interfere with your SSO. Worth setting expectations on one detail: signing in through your identity provider lands the person straight in the workspace that asserted them, never on a workspace picker. The picker belongs to password sign-in — see Multi-Workspace Support. To reach the other workspace they sign out and sign in with a password. If you would rather the older workspace was cleaned up, ask support.

Can two workspaces use the same email domain?
No. A domain is claimed by exactly one workspace, and removing an SSO connection does not release the claim, so moving a domain between workspaces is a support request.

If you genuinely run two Churnkey workspaces and want SSO on both — a parent and a child, or two business units — the domain claim is not the only way in. A workspace start URL works without one, because it names the workspace outright instead of looking it up from the email domain. Claim the domain on the workspace your team signs into by typing their email, and give the other one a bookmark or a portal tile.

We have more than one identity provider. Can we connect both?
No. A workspace has one SAML connection, and new metadata replaces it.

Does requiring SSO break our API keys?
No. Data API keys are unaffected. MCP and other OAuth connections authorized before enforcement need a one-time reconnect — see What requiring SSO does and does not cover.

Who can turn SSO enforcement on?
Only the workspace Owner. Admins see the switch disabled with an explanation in the tooltip.