SAML SSO

QA Sphere supports SAML 2.0 single sign-on, so your team can sign in through identity providers like Okta, Microsoft Entra ID, Auth0, Google Workspace, or JumpCloud instead of managing separate passwords. Combined with SCIM provisioning, your IdP becomes the single source of truth for who can access QA Sphere.

SAML SSO is available on the Business plan and above. Configuration requires the Admin or Owner role.

Service Provider Details

QA Sphere does not publish an SP metadata file — register it in your IdP by entering these two values manually. Both are shown with copy buttons in Settings → Security once you enable SAML:

Field	Value
Audience URI (SP Entity ID)	`urn:hypersequent:qasphere:{workspace-id}`
Single Sign-On URL (ACS)	`https://{your-company}.{your-region-code}.qasphere.com/api/saml/acs`

Copy the exact values from the Security page rather than constructing them yourself — the Entity ID embeds your workspace's unique ID.

When configuring the IdP application, keep in mind:

QA Sphere sends the sign-in request via the HTTP-Redirect binding, so your IdP's SAML metadata must advertise an HTTP-Redirect single sign-on endpoint. The response comes back as a standard browser POST to the ACS URL.
Assertions must be signed by the IdP. QA Sphere verifies every response against the certificates in your IdP metadata.
Do not require signed AuthnRequests and do not enable assertion encryption — QA Sphere has no SP certificate, so neither is supported.

Attribute Mapping

QA Sphere resolves the signing-in user by email. Configure your IdP to release:

Attribute	Purpose
`email` (also accepts `mail`, `emailAddress`)	Required. Matched against the QA Sphere account email.
`firstName` / `givenName`, `lastName` / `sn`	Optional. Used as the display name when a new user registers.
`displayName` or `name`	Optional fallback if first/last name attributes are absent.

If no email attribute is present, QA Sphere falls back to the NameID — but only when it is an email address. Some IdPs (ADFS in particular) put an opaque identifier in the NameID rather than an email, so always map an explicit email attribute.

Configuring QA Sphere

Go to Settings → Security and turn on Sign in with SAML SSO.
Choose how QA Sphere reads your IdP metadata:
- Metadata URL (recommended) — QA Sphere fetches the URL when you save and re-fetches it daily, so IdP certificate rotation is picked up automatically. The URL must be publicly reachable — addresses on private networks are rejected.
- Metadata XML — paste the metadata document (or use Load from file…), up to 1 MiB. It is used as-is: after your IdP rotates certificates or changes endpoints, you must paste the updated metadata yourself.
Copy the Audience URI and Single Sign-On URL from the same page into your IdP application.

Settings save automatically on change. The metadata is fetched and validated immediately, so mistakes surface right away — for example, metadata without an HTTP-Redirect sign-on endpoint or without a signing certificate is rejected on save.

Once saved, use the Test SSO login link on the Security page: it starts the sign-in flow in a new tab, and landing back on the Security page confirms the round trip works.

Members sign in with the Sign in with SSO button on your workspace's sign-in page. QA Sphere matches the asserted email against existing accounts and starts a regular session. Multi-factor authentication is your IdP's responsibility — QA Sphere does not run its own 2FA challenge for SAML sign-ins.

New users are not created automatically on first sign-in. Someone must exist in QA Sphere before SAML lets them in:

Invite them from Settings → Members. The invitation email opens the registration page, where Register with SSO completes sign-up through the IdP. The invitation email must match the email asserted by the IdP.
Or provision them via SCIM to automate the whole lifecycle.

Users without an account see an error asking them to request an invitation from an admin.

Enforcing SSO

To make SAML the only way in, turn off Password Authentication and Sign in with Google in Settings → Security — at least one method must always remain enabled. Disabling a method signs out every user who has no remaining allowed sign-in method.

Limitations

Sign-in is SP-initiated only: users start from the QA Sphere sign-in page (or an invitation link), not from the IdP dashboard.
One IdP configuration per workspace.
Single Logout (SLO) is not supported — signing out of QA Sphere does not end the IdP session, and vice versa.
No just-in-time provisioning — use invitations or SCIM.

The ACS URL contains your workspace subdomain. If your workspace URL changes, update the Single Sign-On URL in your IdP application, or sign-in will break.

Troubleshooting

Symptom	Likely cause
"no HTTP-Redirect SSO Location found in metadata"	Your IdP metadata only advertises an HTTP-POST sign-on endpoint. Enable the HTTP-Redirect binding in the IdP application.
"could not fetch SAML metadata from URL"	The metadata URL is unreachable from the internet, returns a non-200 status, or points to a private address.
"saml audience mismatch"	The Audience URI in your IdP doesn't match the value shown in Settings → Security.
"saml assertion invalid"	Signature verification failed — usually stale certificates. Re-save the metadata URL or paste the current metadata XML.
"saml assertion expired"	The assertion's validity window doesn't match QA Sphere's clock. Check your IdP's clock settings. With Auth0 this can appear intermittently — retrying usually works.
"no account for … ask an admin to invite you"	The user doesn't exist in QA Sphere yet. Invite them or provision via SCIM.
"register token email does not match…"	The invitation was sent to a different email than the IdP asserts. Re-invite using the IdP email.
"saml login is disabled for this tenant"	The Sign in with SAML SSO toggle is off, or your subscription no longer includes advanced authentication.

If you get stuck, contact QA Sphere support with the error message and the time of the failed sign-in attempt — the exact reason a sign-in was rejected is recorded on our side.