Single sign-on (SSO)

Single sign-on lets people at your company sign in to QRdx through your identity provider instead of an email code, Google or GitHub. You set up one connection for one email domain, prove you own the domain, and people at that domain are offered single sign-on when they enter their work email to sign in. Signing in that way makes them a member of your workspace. You can also require it, so your identity provider is the only way in for that domain.

Single sign-on is part of the Business plan. A workspace has it when one of its owners or billing members is on Business. See Seats and workspace limits.

Single sign-on is a Business feature under the QRdx commercial license. A self-hosted QRdx server needs a license key (QRDX_EE_LICENSE) to turn it on; see Self-hosting.

Before you startCopy Anchor Link

• You need to be an owner or admin of the workspace.
• You need to be able to add a DNS record for your email domain, like acme.com.
• Setting up, changing, verifying or removing the connection, and requiring single sign-on, asks you to confirm it's you first: with your passkey or a two-step verification code, or, if two-step verification is off, with a code we email you or, for an OIDC connection, by signing in through it again. One confirmation covers your changes for the next 10 minutes.

QRdx uses the standard OIDC and SAML 2.0 settings that identity providers ask for. The steps below list the values; where to paste them depends on your provider.

Set up with OIDCCopy Anchor Link

1. In the workspace, go to Settings → Single sign-on. OIDC is selected.
2. In your identity provider, create a web app (OIDC client) for QRdx and add the Redirect URI shown on the page as an allowed redirect.
3. Back in QRdx, fill in:
   • Email domain: your company's domain, like acme.com.
   • Issuer URL: your provider's issuer. QRdx reads the rest from <issuer>/.well-known/openid-configuration, so the issuer has to match that document exactly.
   • Client ID and Client secret from the app you created.
4. Click Save connection.

QRdx asks for the openid, email and profile scopes and uses PKCE. The issuer has to be reachable over HTTPS from the internet; identity providers on a private network aren't supported.

Set up with SAML 2.0Copy Anchor Link

1. In the workspace, go to Settings → Single sign-on and choose SAML 2.0.
2. In your identity provider, create a SAML app for QRdx with the values shown on the page:
   • Assertion Consumer Service (ACS) URL
   • Entity ID (audience)
   • Metadata URL, if your provider can read QRdx's settings from a URL
3. Send the person's email address as the NameID (email format) or as an attribute named email. For their name, send givenName and surname (or firstName and lastName, or the X.500 names urn:oid:2.5.4.42 and urn:oid:2.5.4.4), or a display name (displayName, name or urn:oid:2.16.840.1.113730.3.1.241). Without a name, QRdx uses the part of the address before the @.
4. Back in QRdx, enter your Email domain and paste your provider's metadata XML. Or click Enter the details instead and fill in the Sign-in URL (SSO URL), the provider's entity ID and its signing certificate.
5. Click Save connection.

Your provider has to sign its responses and include an HTTP-Redirect sign-in URL. QRdx turns away responses without a valid signature or without validity times (NotBefore and NotOnOrAfter).

Signatures have to use SHA-256 or stronger. QRdx turns away responses signed or digested with SHA-1; if your provider is set to SHA-1 for the QRdx app, switch it to SHA-256.

QRdx doesn't sign its sign-in requests. If your provider is set to require signed requests from the QRdx app, turn that off, or it turns people away before they can sign in.

Verify your domainCopy Anchor Link

Nobody can sign in through the connection until you prove you own the domain.

1. Under Verify on the Single sign-on page, copy the TXT record's Name and Value.
2. Add the TXT record at your DNS provider.
3. Click Verify. New records can take a few minutes, sometimes longer, to show up. If QRdx doesn't find the record yet, it says so; wait and try again.

The verification value is valid for 7 days. If it expires, reload the page for a new one and update the record.

A verified domain covers its subdomains too, so acme.com also covers eu.acme.com. A domain can be verified for single sign-on in only one workspace. If another workspace already verified it, or a domain that overlaps it, QRdx tells you when you save or verify.

What your team seesCopy Anchor Link

1. On the sign-in page, they enter their work email and click Email me a code, like any email sign-in.
2. Before sending a code, QRdx checks the address's domain. For your verified domain, it says your company signs in with single sign-on and offers Continue with SSO. No code is sent unless they ask for one.
3. Continue with SSO sends them to your identity provider, then back to QRdx, signed in and in your workspace.

They can choose Email me a code instead, unless you require single sign-on. Sign in with SSO, below the email field, also still works: it asks for their work email and goes straight to your identity provider.

QRdx offers single sign-on only while the domain is verified and the workspace is on Business. The check looks at the domain alone, so it never shows whether someone has a QRdx account.

If someone turned on two-step verification, QRdx still asks for their second step after your identity provider signs them in, unless they chose not to be asked again on that device. That's the same when single sign-on is required.

Every SSO sign-in makes sure the person is in your workspace:

• Someone who isn't a member joins with the role you pick under New members: Member (the default) or Viewer.
• Someone with a pending invitation to the workspace joins with the invitation's role, and the invitation is marked accepted.
• Members keep the role they have. You can change anyone's role on the Team page.

This includes people you removed from the workspace: they rejoin the next time they sign in with SSO.

If someone already has a QRdx account with the same email address, signing in with SSO uses that account. They keep their own workspace and everything in it.

QRdx only signs someone in through your connection if the address your provider sends is at your verified domain. Their other ways to sign in, like an email code to the same address, keep working unless you require single sign-on.

Email addresses have to be verified in your identity provider. If it tells QRdx an address isn't verified (OIDC's email_verified claim, or a SAML email_verified or emailVerified attribute, set to false), QRdx doesn't sign the person in, doesn't create an account for them and doesn't link an existing one. They see a message asking your admin to verify addresses there. If your provider doesn't say either way, QRdx trusts it for your verified domain.

Signing out of QRdx doesn't sign anyone out of your identity provider. While they're still signed in there, their next SSO sign-in goes straight through without asking for their password. On a shared computer, sign out of your identity provider too.

Open QRdx from your identity providerCopy Anchor Link

With a SAML connection, people can also start from your identity provider: clicking the QRdx app in its app dashboard signs them in to QRdx without going through QRdx's sign-in page. This is often called IdP-initiated sign-in.

In your identity provider, open the SAML app you created for QRdx and make sure it's shown to people in the app dashboard and allows sign-in started from the identity provider. People land on the dashboard in your workspace. QRdx ignores any RelayState the app sends, so a sign-in QRdx didn't ask for never picks the page that opens.

The same rules apply as when the sign-in starts on QRdx: the domain has to be verified, the workspace on Business, and the response signed with SHA-256 or stronger. QRdx also needs:

• exactly one assertion, with an ID, that isn't encrypted;
• an expiry on the assertion (NotOnOrAfter in its Conditions), which most identity providers send by default.

Each response signs someone in once. If the same response arrives again, QRdx turns it away and asks the person to sign in again. If someone turned on two-step verification, QRdx asks for their second step first, then takes them to the dashboard.

A sign-in from the app dashboard doesn't count as confirming it's you unless the person answered their second step, because QRdx didn't ask for it. Before a change that asks, they confirm as usual.

An OIDC connection always starts at QRdx. To put QRdx in your identity provider's app dashboard, add it as a link to QRdx's sign-in page.

Require single sign-onCopy Anchor Link

Once your domain is verified, you can make your identity provider the only way in for people at it. On the Single sign-on page, turn on Require single sign-on for your domain. It covers subdomains too, like the connection.

While it's on, for an address at your domain:

• Email codes, Google and GitHub don't sign them in, and nor does Continue with passkey. They see that your company requires single sign-on, and Continue with SSO.
• Their two-step verification still applies after your identity provider signs them in. A passkey still works as that second step.
• A sign-in lasts 24 hours at most. Then they go through your identity provider again, so someone you unassign there can't sign in to QRdx again, and is signed out within a day.
• Their QRdx email can't be changed to an address elsewhere, and nobody else's can be changed to one at your domain. Signing in with single sign-on is how an address there gets into QRdx.

Turning it on signs everyone at your domain out of sessions that didn't start with single sign-on, and the ones that did end 24 hours after that sign-in. Nobody gets an email about it; they're asked to sign in with SSO next time.

Owners keep their other ways to sign in. None of this applies to the workspace's owners: they can still use an email code, Google or GitHub, or a passkey, their sessions aren't cut short, and they can change their email. So a problem with your identity provider can't lock everyone out of this setting. Keep the owner role to the few people who need it.

To turn it on:

• You need to be an owner or admin on the Business plan, with a verified domain, and you'll be asked to confirm it's you.
• If you're an admin with an address at the domain, sign in with single sign-on first. Turning it on would otherwise sign you out, and signing in that way shows the connection works.

Turning it off, removing the connection, or the workspace leaving Business stops requiring it. People keep the sessions they have, and can use their other ways to sign in again. It can take up to a minute to reach every QRdx server: someone who signs in another way in that minute may be signed straight back out, and can sign in again a minute later.

Single sign-on is about signing in. API keys aren't sign-ins, so requiring it doesn't stop them; removing someone on the Team page does stop the API keys they made for the workspace.

Remove someone for goodCopy Anchor Link

Because every SSO sign-in adds the person back, removing them on the Team page isn't enough on its own:

1. In your identity provider, unassign them from the QRdx app (or turn off their account there), so it can't sign them in to QRdx.
2. Then remove them on the Team page. The remove dialog reminds you when the person's address is at your verified domain.

If you require single sign-on, step 1 also signs them out of QRdx within 24 hours. Remove them on the Team page too, so they're no longer a member and their API keys for the workspace stop working.

Removing someone from the workspace doesn't delete their QRdx account. Unless single sign-on is required for their address, they can still sign in to their own workspace with an email code, Google or GitHub.

Change or remove the connectionCopy Anchor Link

• Replace secret (OIDC) or Replace certificate (SAML) updates the connection when you rotate them at your identity provider. A SAML connection set up from metadata XML is changed by removing it and setting it up again.
• Remove turns single sign-on off, and stops requiring it. Everyone stays in the workspace and can sign in with an email code, Google or GitHub.

If the plan changesCopy Anchor Link

If the workspace is no longer on Business, nobody can sign in with SSO, including halfway through a sign-in, and single sign-on stops being required. People see a message and can sign in another way. The connection and its settings are kept, so they work again when the workspace is back on Business, and you can still remove it.

What isn't supportedCopy Anchor Link

• Automatic provisioning and removal (SCIM). Removing someone from your identity provider doesn't remove them from the workspace. Without required single sign-on it doesn't end their QRdx sessions either; remove them on the Team page too (see Remove someone for good).
• Roles or groups from your identity provider. Everyone joins with the role under New members.
• More than one connection, or more than one domain, per workspace.
• Sign-in started from your identity provider with an OIDC connection (it works with SAML: see Open QRdx from your identity provider), SAML single logout, and encrypted assertions.
• Identity providers that aren't reachable from the internet.

RelatedCopy Anchor Link

• Team roles
• Seats and workspace limits
• Create a workspace and invite people