Get things done

Set up SAML single sign-on

Point your identity provider at this product so staff at a verified domain sign in there instead of with a password here.

SAML lets your own identity provider (Entra ID, Keycloak, or another SAML IdP) authenticate sign-ins for a domain, instead of a password stored here. It requires a paid plan, and it requires a verified domain first — the whole setup is refused at the last step if you skip ahead.

Before you begin

Claim and verify the email domain you're setting this up for. Nothing below can be completed without it.

Quick steps

Open the team's SSO tab and create a SAML connection.
Copy the connection's SP metadata URL into your IdP.
In your IdP, make sure the assertion is signed — not only the response. Keycloak needs "Sign assertions" turned on explicitly; Entra ID signs the assertion by default.
Check the connection's email attribute mapping matches what your IdP sends.
Bind the connection to the verified domain, then set that domain's login method to SAML.
Grant at least one person a break-glass exception before you enforce SAML, so a broken IdP or an expired certificate can't lock everyone out at once.

1. Create the connection and hand off metadata

From the team's SSO tab, create a SAML connection and give your IdP the SP metadata URL shown on it. The SP certificate is generated for you when the connection is created — you never paste a private key. If your organization's PKI needs to issue the SP certificate instead, you can supply your own.

Fill the IdP details from its metadata

Rather than typing the issuer, sign-in URL and signing certificates by hand, paste your IdP's federation metadata into Import from IdP metadata at the top of the connection form and choose Fetch and fill. Two sources:

Metadata URL — the better choice whenever your IdP publishes one. Entra ID, Okta and Google Workspace all do. The URL is stored with the connection, and a daily job re-reads it, so a certificate rotation is picked up without anyone touching the connection.
Paste metadata XML — for an IdP that publishes no URL, or one only reachable inside your network. This is a point-in-time snapshot: nothing re-reads it, so you must re-import by hand when the IdP rotates.

While a metadata URL is set, the issuer, sign-in and sign-out URLs and the signing certificates are shown read-only, because the daily refresh overwrites them — an edit made there would revert with nothing said. Use Fetch and fill to update them, or switch to Paste metadata XML to take them over by hand. Everything else on the connection — its name, the SP entity ID, the attribute mapping — is yours to set either way.

Metadata is fetched over HTTPS only, and the identity provider must be reachable from the public internet. A URL that resolves to a private address is refused.

2. Make sure the IdP signs the assertion

This is the single most common setup failure. The IdP must sign the SAML assertion itself. Signing the surrounding response as well is fine and has no downside, but signing only the response — leaving the assertion unsigned — is refused: an unsigned assertion inside a signed response can be swapped for a different one without invalidating the response's signature.

Keycloak signs the response by default and leaves the assertion unsigned. Turn on "Sign assertions" on the client.
Entra ID signs the assertion by default — no change needed there.

If sign-in fails right after setup, this is the first thing to check.

3. Confirm the email attribute

The connection maps which assertion attribute carries the user's email, so a login can be matched to a person here. By default it looks for an attribute literally named email, and also for urn:oid:1.2.840.113549.1.9.1 — the OID Keycloak's canned "X500 email" mapper (and Shibboleth) emit by default — so most IdPs work without changing this. If your IdP sends the email under a different attribute name, add it to the connection's mapping. If no email is found in the assertion, the login is refused.

Order matters here, and each step is refused until the one before it is done:

The domain must already be verified.
Bind the SAML connection to the domain from the SSO tab.
Set the domain's login method to SAML.

Setting a domain's login method to SAML with no connection bound is refused on purpose — it would leave nobody at that domain able to complete a login. For the same reason, deleting a connection that a SAML domain currently depends on is refused; change that domain's login method first if you need to remove the connection.

Login methods are per verified domain — SAML, Google, passkey, or email and password — and once set, that is the only way in for everyone with an email at that domain.

5. Grant break-glass before you enforce it

Break-glass exempts named members from the domain's enforced login method. Grant it before switching a domain to SAML, to at least one person who can act if things break: if your IdP goes down, or an IdP signing certificate expires without its replacement in place, nobody at that domain can sign in — including the admin who would otherwise fix it. A break-glass exception is the only way back in when that happens.

Manage break-glass grants from the team's SSO tab.

6. Rotate IdP signing certificates without an outage

The connection holds a list of IdP signing certificates, not just one, because a federation metadata rotation publishes the next certificate alongside the still-active one — both need to work during that overlap window. When your IdP rotates:

Add the new certificate to the connection alongside the existing one.
Confirm sign-in still works.
Remove the old certificate once your IdP has fully switched over.

Removing the old certificate too early — before the IdP has finished rotating — breaks sign-in for anyone whose assertion is still signed with it.

What good looks like

The domain shows SAML as its login method, a test sign-in from the IdP succeeds, and at least one break-glass grant exists so a broken IdP or an expiring certificate is a fix, not a lockout.