# Single Sign-On Source: https://docs.qualflare.com/docs/administration/sso · Last updated: 2026-10-27 Connect a SAML 2.0 identity provider to a Qualflare Enterprise workspace, map groups to roles, set the session lifetime and require SSO safely. In Qualflare, **single sign-on** (SSO) lets members of an Enterprise workspace sign in through your SAML 2.0 identity provider; only the workspace Owner can set it up, and a new connection stays off until you turn on **Connection enabled**. ## SSO at a glance | Fact | Detail | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | **Where** | **Workspace** sidebar > **Administration** > **Single Sign-On**, with **Verified Domains** and **SCIM Provisioning** below it | | **Plan** | (available on Enterprise) | | **Who** | (requires the Owner role in the workspace). Saving any change asks **Confirm it’s you** when you last signed in or confirmed more than 5 minutes ago | | **Protocol** | SAML 2.0, with your identity provider's metadata uploaded as an `.xml` file of up to 1 MB | > **Warning:** Requires the **Enterprise** plan, and only the workspace Owner can open these pages. On any other plan these pages show what the feature offers rather than the live configuration. ## How SSO works Members at a verified domain enter their work email on the sign-in page and select **Continue**. Qualflare sends them to your identity provider, which signs them in. ### Who can sign in through SSO Once the connection is on, anyone your identity provider signs in at a verified domain gets in. Someone who isn't a member yet joins the workspace at that first sign-in, with the role your [role rules](https://docs.qualflare.com/docs/administration/sso#attributes-and-role-mapping) give them, or the default role, and takes a team member seat. When the workspace has no free seat, or its subscription isn't active, that first sign-in fails with "Single sign-on failed. Please try again, or contact your workspace owner if it keeps happening." Members who already belong to the workspace keep signing in. SSO doesn't replace two-factor authentication: see [Account security](https://docs.qualflare.com/docs/administration/account-security#single-sign-on-sso). *Figure: Members at a verified domain enter their work email and select Continue.* ## Connect your identity provider 1. Upload your identity provider's SAML metadata as an XML file: drag and drop it onto the upload area, or click to browse. There's no paste-XML or metadata-URL option; a file is the only input. * **File requirements**: `.xml` extension, max 1 MB. * Saving creates the connection **disabled**: nothing routes to it until you turn on **Connection enabled**. *Figure: Upload your identity provider's metadata XML, then turn on Connection enabled.* 2. Once connected, the page shows the **service provider details** you give back to your identity provider when creating the Qualflare application there: | Field | Description | | ------------------------ | -------------------------------------- | | Entity ID (Audience URI) | Qualflare's SP entity identifier | | ACS URL (Reply URL) | Where the IdP sends the SAML assertion | | Name ID format | The NameID format Qualflare expects | *Figure: Give these details to your identity provider when you create the Qualflare app there.* 3. Turn on **Connection enabled**, then click **Turn on connection** in the confirmation. It says that anyone your identity provider signs in who isn't a member yet joins the workspace, and that nobody is signed out. ## Connection settings ### Require encrypted assertions **Require encrypted assertions** refuses a sign-in whose SAML assertion your identity provider didn't encrypt. It's off by default. Turn it on only after your identity provider encrypts assertions to the certificate in Qualflare's metadata, or every sign-in fails. It takes effect when you save the connection. ### Single Logout **Single Logout** signs a person out of Qualflare when they sign out at your identity provider. It's off by default, and you can turn it on only when your identity provider's metadata names a logout URL; otherwise the page says "Your identity provider's metadata names no logout URL, so Single Logout cannot be turned on." It takes effect when you update the connection. Then give your identity provider Qualflare's metadata again, so it knows where to send logouts. ### Rotate the signing keypair The signing certificate has an expiration date shown on this card. Rotating it takes two steps, so sign-in keeps working while your identity provider catches up: 1. Click **Rotate keypair**. Qualflare stages a new keypair: the current key keeps signing, and the SP metadata URL publishes both certificates. A **Rotation pending** panel shows the new certificate. > **Caution:** **Activate new keypair** deletes the old key, and you can't undo it. Until your identity provider has the new certificate, every SSO sign-in fails, and under **Require SSO** that locks out every covered member. 2. Give your identity provider the new certificate: re-import the SP metadata, or paste the certificate where it keeps Qualflare's. Then click **Activate new keypair** and confirm with **Activate**. If your identity provider holds only one certificate for Qualflare (Okta, for example), replace it there and activate right after. Use **Discard** (confirm with **Discard keypair**) only if your identity provider hasn't imported the new certificate. ### Identity provider certificates The **Identity provider** card separately lists your identity provider's **Signing certificates**, marked **Expired** or **Expires soon**. When your identity provider rolls its certificate, upload its new metadata. ## Map attributes and roles Configure how identity provider claims map onto a Qualflare profile and role: * **Profile attributes**: email, display name, first name, last name claim names. Leave blank to try standard claim names automatically. * **Group attribute**: the SAML claim holding the user's group memberships. * **Role rules**: an ordered list mapping a group-name match to a role (Viewer, Editor, or Maintainer). **The first matching rule wins** — reorder rules with the up/down controls to control precedence. Duplicate matches are flagged; only the first ever fires. * **Default role**: applied when no rule matches. * **Re-apply roles on every sign-in**: when on, a member's role is recomputed from the current rules at every login (manual role changes in Qualflare are overwritten). Workspace owners are never changed by this. Roles pushed via SCIM group sync take precedence over this setting. If no group attribute is set, role rules have no effect on SAML sign-ins — everyone gets the default role. Rules still apply to groups synced over SCIM. *Figure: The first matching role rule wins; anyone else gets the default role.* ## Set the SSO session lifetime The **SSO session lifetime** card sets how long a session from an SSO sign-in lasts before the member goes back through your identity provider. * **Maximum session length (hours)**: 1 to 168. Leave it empty for the default, 12 hours. * Changes apply to sign-ins after you click **Save**. People already signed in keep their current session end. *Figure: Leave the field empty for the default, 12 hours.* ## Verified domains Members are sent to your identity provider only when their email address is at a verified domain. Add and verify each domain on the [Verified Domains](https://docs.qualflare.com/docs/administration/verified-domains) page; at least one must be verified before you can require SSO. ## Require SSO The **Require SSO** switch is in the red panel at the bottom of the Single Sign-On page. It covers every member whose email address is at one of your verified domains, owners included. For them, password, Google, and GitHub sign-in stop working across their whole Qualflare account, not just this workspace. They sign in through your identity provider instead: they enter their work email on the sign-in page and select **Continue**. **Before you can turn it on:** * **Connection enabled** must be on. * Qualflare support hasn't disabled the connection. * At least one verified domain must exist. * Someone must have successfully completed a real SSO sign-in through the connection — this is enforced server-side, not just a UI check. To run one, sign out, enter an email address at a verified domain on the sign-in page, and select **Continue**. > **Caution:** Turning this on immediately signs out every covered member whose session didn't come from this connection, including you if you signed in with a password, Google, or GitHub. It also permanently revokes the access tokens that covered members created in this workspace's projects without signing in through this connection, so CI pipelines that use them stop working. Verifying another domain while the switch is on does the same to that domain's members. Sign in through SSO first, and create new tokens after you do. There is no way to undo this from the sign-in page itself — if everyone gets locked out, see [Recovering from a Lockout](https://docs.qualflare.com/docs/administration/sso#recovering-from-a-lockout) below. The switch can always be turned back **off**, even if the workspace is in a locked state. Members at other domains aren't covered and keep signing in as they do now. If there are any, the panel shows how many ("N members are not covered by SSO"), and the confirmation asks you to tick an acknowledgement before it turns the switch on. To bring them under SSO, verify their email domain. *Figure: Require SSO covers only members at your verified domains.* ## SCIM provisioning SCIM 2.0 lets your identity provider add, update and remove workspace members. It needs a working SSO connection and uses the role rules above; set it up on the [SCIM Provisioning](https://docs.qualflare.com/docs/administration/scim) page. ## Remove a connection > **Caution:** **Remove** permanently deletes the SAML configuration, its verified domains, its role mapping, and any SCIM provisioning token, so SCIM provisioning stops too. Using SSO again means setting it up, verifying your domains, and running a test sign-in from scratch. Nobody is removed from the workspace. Everyone who signed in through this connection is signed out right away, and their single sign-on link is removed. Members who signed in another way stay signed in. **Remove** is disabled while **Require SSO** is on — turn off enforcement first. ## Troubleshooting Until the connection is ready, the **Require SSO** switch can't be turned on, and the panel says why: * "This connection has been disabled by Qualflare support." * "Enable the connection first." * "Run a successful test sign-in first." * "Verify at least one email domain first." If Qualflare can't use the metadata file you upload, saving fails and the message gives the reason, for example that the file has no signing certificate. Members can see these on the sign-in page: * "Your email address's domain isn't verified for single sign-on with this workspace yet. Contact your workspace owner." * "Your identity provider signed you in, but this account isn't a member of any workspace that uses this single sign-on. Ask your workspace owner to invite you." * "Single sign-on failed. Please try again, or contact your workspace owner if it keeps happening." For what members can do about each sign-in error, see [SSO login failures](https://docs.qualflare.com/docs/faq/troubleshooting#sso-login-failures). ### Recovering from a lockout If a workspace locks itself out of SSO, email Qualflare support at [support@qualflare.com](mailto:support@qualflare.com). Support can disable the connection from the admin side, which also turns off the SSO requirement in the same action so password login works again immediately. ## Related * **Guides:** [Verified Domains](https://docs.qualflare.com/docs/administration/verified-domains) · [SCIM Provisioning](https://docs.qualflare.com/docs/administration/scim) · [Account security](https://docs.qualflare.com/docs/administration/account-security#single-sign-on-sso) * **Reference:** [Roles and permissions](https://docs.qualflare.com/docs/administration/roles-permissions) · [Plans and limits](https://docs.qualflare.com/docs/administration/plans#features-by-plan) · [Audit Logs](https://docs.qualflare.com/docs/administration/audit-logs) · [Access tokens](https://docs.qualflare.com/docs/api/access-tokens)