Setting up SAML single sign-on (SSO)
With SAML SSO your team signs in to Qvasa through your identity provider instead of a Qvasa password. Qvasa works with any SAML 2.0 identity provider: Google Workspace, Okta, Microsoft Entra ID (Azure AD), OneLogin and others. Your account gets its own login page at https://<subdomain>.qvasa.com with a single sign-in button, and each user is matched to their Qvasa user by email address.
This guide uses Google Workspace as the worked example. The Qvasa side is identical for every provider: you give your provider two URLs, and your provider gives you three values (or a metadata URL) to paste into Qvasa.
Before you start
You are an admin in Qvasa.
You can create a custom SAML app in your identity provider (for Google Workspace, that means a Google Admin console super admin).
Pick a subdomain for your login page, for example acme. Lowercase letters, numbers and hyphens only. It becomes https://acme.qvasa.com and has to be unique across Qvasa.
Your identity provider must send each user's email address as the SAML Name ID, and it has to match the user's email in Qvasa exactly. Google Workspace does this by default.
Step 1: Allow SAML logins on your account
Go to Settings → Top Level Account Settings, search for SAML and enable SAML Logins Allowed.
This only makes SAML available as a login option. It doesn't configure anything yet, and nobody is forced to use SAML. Two things to know:
Once enabled, this setting can't be switched off from the settings page. If you ever need it off, reach out to the Qvasa team.
A new SAML card appears under Settings → Integrations. That is where the rest of the setup happens.
Step 2: Create the Qvasa app in your identity provider
Your identity provider needs two values from Qvasa. Both come straight from the subdomain you picked, so you can set up the provider side first:
ACS URL (also called the callback or reply URL): https://<subdomain>.qvasa.com/users/auth/saml/callback
Entity ID (also called the issuer or audience): https://<subdomain>.qvasa.com
For acme that is https://acme.qvasa.com/users/auth/saml/callback and https://acme.qvasa.com. No trailing slash on either. Qvasa shows both values again under Service Provider Details once you've saved your configuration in Step 3, together with an SP metadata URL that providers like Okta and Entra ID can import.
In Google Workspace:
In the Google Admin console go to Apps → Web and mobile apps → Add app → Add custom SAML app. Name it Qvasa and click Continue.
On the Google Identity Provider details page, copy the SSO URL, the Entity ID and the Certificate somewhere safe. You'll paste all three into Qvasa in Step 3. (Google also offers an IdP metadata download. Qvasa only accepts a metadata URL, so for Google use the three values.)
On Service provider details, enter the ACS URL and Entity ID from above. Leave the Name ID as Basic Information → Primary email, Google's default.
Skip attribute mapping. Qvasa needs nothing beyond the email in the Name ID.
Finish, then open the app's User access panel and turn it ON for everyone, or only for the organizational units that use Qvasa. Google can take a few minutes to apply this.
In other providers the steps are the same in different words: create a custom SAML 2.0 app, give it the ACS URL and Entity ID, make the Name ID the user's email, and note the provider's SSO URL, issuer (entity ID) and signing certificate, or its metadata URL if it publishes one.
Step 3: Create the SAML configuration in Qvasa
Go to Settings → Integrations → SAML and click Create SAML Configuration. None of the fields on this form are secrets.
Subdomain: the one you picked in Step 2.
Either an IdP metadata URL, if your provider publishes one. Qvasa fetches it at every login, so it has to be publicly reachable (not behind a VPN).
Or the three manual fields: IdP entity ID, IdP SSO target URL and IdP cert. Paste the whole certificate, including the BEGIN CERTIFICATE and END CERTIFICATE lines. For Google Workspace these are the three values you copied in Step 2.
Click Save. Qvasa won't save a configuration that has neither a metadata URL nor all three manual values.
Step 4: Test it and share the login URL
After saving you land on the SAML Single Sign-On page. A green SAML Configuration Looks Good banner means every required field is present.
Click Test Configuration. Qvasa builds the configuration it will use at login (fetching the metadata URL if you gave one) and shows the entity ID, SSO URL, a snippet of the certificate and the service provider values, without starting a login.
Then do a real sign-in yourself: open the User Login URL in a private window, click Login with SAML SSO, sign in at your identity provider, and you'll land back in Qvasa with a Signed in via SAML SSO message.
Share the User Login URL with your team. The regular Qvasa login page has no SAML button, so users need this link (it's worth bookmarking). The page also has a Normal Login Page link for anyone still signing in with a password.
After it works: deciding who must use SAML
Allowing SAML changes nothing for your existing users: they can keep signing in with their password until you say otherwise. Once you've verified a real login works, you have three controls.
Require SAML for a user. Go to Settings → Manage Account Members, edit the user and tick Must log in through SAML under Login Method Permissions. From then on that user can only sign in through your identity provider: the password login and password reset are blocked, and they're told to use the SAML login button instead. The members list shows a Force SAML column so you can see who is on it.
Two optional account settings appear on Settings → Top Level Account Settings once SAML logins are allowed:
Default New Users to Force SAML: every user you add from now on starts with Must log in through SAML ticked. It doesn't touch existing users.
Qvasa creates new users on SAML login: when someone your identity provider has verified signs in and Qvasa has no user with that email on your account yet, Qvasa creates one on the spot, with the lowest permissions (they can see agent dashboards) and forced to SAML. An admin then sets their permissions. With this off, such a login fails with User not found.
Keep one admin on password login. If an admin has Must log in through SAML and the configuration breaks (an expired certificate, a changed SSO URL), nobody can get in to fix it. The SAML page shows a Lockout Risk warning when the admin viewing it is forced through SAML. Leave at least one admin without that permission.
Troubleshooting
Issues Detected banner, or Test Configuration fails. With manual settings, all three IdP fields are required. With a metadata URL, open the URL in your browser: it should return XML containing the SSO endpoint and certificate, and some providers only publish it once the app is activated. If the metadata test fails but Qvasa reports that your stored manual settings pass, clear the metadata URL field and logins will use the manual values.
SAML login failed after returning from the identity provider. The ACS URL and Entity ID in your provider must match the Service Provider Details on the SAML page exactly (https, your subdomain, no trailing slash), and the certificate in Qvasa must be the provider's current signing certificate.
User not found. The email your provider sent doesn't match a user on your Qvasa account. Check the Name ID is the user's email and that it matches the Qvasa user exactly, or turn on Qvasa creates new users on SAML login.
"Your account requires you to login through SAML." The user has Must log in through SAML and used the regular login page. Send them the User Login URL.
"SAML logins are not enabled on this account." SAML Logins Allowed is off for the account (Step 1).
Google says the app isn't enabled for the user. Check the app's User access in the Google Admin console and allow a few minutes for the change to propagate.
Turning SAML off. Delete SAML Configuration on the SAML page removes the login page. Untick Must log in through SAML for the affected users first, or they won't be able to sign in at all. If you're locked out, contact the Qvasa team.