Single Sign-On (SSO)
Let people sign in with the account your organization already manages, such as Microsoft Entra ID (Azure AD), Google Workspace or Okta.
Signing In with SSO
- On the sign-in screen, click Sign in with SSO under the Sign in button.
- Enter your Work email and click Continue with SSO.
- PersivX sends you to your organization's sign-in page. Sign in there as usual.
- You come back to PersivX signed in, on the page you started from (a dashboard link, for example).
Click Sign in with password to go back to the normal form. Remember me works the same way for both.
You need a PersivX account already: SSO signs you in to the account your admin invited, matched by email address. It never creates accounts. If two-step verification is on for your PersivX account, PersivX still asks for your code, unless your organization trusts its provider's own (see below).
Switching to another account
Signing out of PersivX doesn't sign you out of your identity provider. If the provider is still signed in as someone else when you sign in with SSO, PersivX notices that the account doesn't match the email you typed and sends you back to the provider once to sign in again. There, choose or enter the other account. With some providers the page shows the previous account with a button to switch, such as Keycloak's ⟳ next to the username. To avoid this, sign out of your identity provider too, or use a private browser window.
Messages you may see
| Message | What it means |
|---|---|
| Single sign-on isn't set up for this email address. Sign in with your password instead. | Your email's domain isn't set up for SSO in any organization. |
| There's no PersivX account for … in this organization. Ask your admin to invite you. | Your provider confirmed who you are, but nobody has invited that address to PersivX. |
| Your identity provider says … isn't verified. | Your provider hasn't confirmed you own that address. Ask your IT team. |
| Your identity provider signed you in as …, not … | Your provider is still signed in as another account and you signed in to that one again. Sign out of your provider, or use a private window, then sign in as the account you want. |
| Your organization signs in with single sign-on. Use "Sign in with SSO" below. | Your organization requires SSO, so password sign-in is off for you. |
| That sign-in took too long or was already used. Please start again. | More than 10 minutes passed, or the sign-in was finished in another browser. Start again from the same browser. |
Setting Up SSO (Organization Admins)
Open the admin console and choose Single sign-on in the menu. The item only appears when SSO is switched on for your PersivX server.
1. Register PersivX with your identity provider
Create an OpenID Connect web application in your provider. Every provider asks for the same things and gives you two values back:
- Redirect URI: copy it from Redirect URI to register with your provider on the Single sign-on page. It must match exactly.
- Scopes:
openid,emailandprofile. - Sign-in flow: authorization code, as a confidential (web) client with a client secret.
- You get back a client ID and a client secret.
Microsoft Entra ID (Azure AD, Microsoft 365)
- In the Microsoft Entra admin center, open App registrations and click New registration.
- Name it (for example PersivX). Under Supported account types choose Accounts in this organizational directory only. Under Redirect URI, pick Web and paste PersivX's redirect URI. Click Register.
- From the app's Overview, copy the Application (client) ID and the Directory (tenant) ID.
- Open Certificates & secrets, click New client secret, and copy its Value (not the Secret ID). It's shown only once.
- Recommended: open Token configuration, click Add optional claim, choose ID and tick email. Without it, PersivX uses the person's sign-in name (UPN), so their PersivX email must match their UPN.
- In PersivX, the issuer URL is
https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0.
Microsoft client secrets expire on the date you chose in step 4. Create a new one before then and paste it into PersivX, or sign-ins will start to fail.
Google Workspace
- In the Google Cloud console, under APIs & Services, set up the OAuth consent screen with user type Internal, so only your Workspace accounts can use it.
- Open Credentials, click Create credentials then OAuth client ID, and choose Web application.
- Under Authorized redirect URIs, add PersivX's redirect URI. Click Create and copy the client ID and client secret.
- In PersivX, the issuer URL is
https://accounts.google.com.
PersivX accepts only accounts of your Workspace domain (Google's hd value must match the email's domain), so personal Gmail accounts are refused.
Okta
- In the Okta Admin Console, open Applications and click Create App Integration.
- Choose OIDC - OpenID Connect and Web Application.
- Under Sign-in redirect URIs, add PersivX's redirect URI. Keep the Authorization Code grant type.
- Assign the people or groups who should use PersivX, save, and copy the client ID and client secret.
- In PersivX, the issuer URL is your Okta domain,
https://<your org>.okta.com, or your custom authorization server's issuer if you use one.
On-premises Active Directory with AD FS
AD FS 2016 and later support OpenID Connect. Register PersivX as a server application (a confidential client) with PersivX's redirect URI and a shared secret, and make sure the ID token includes the person's email address. The issuer URL is https://<your AD FS host>/adfs. If AD FS is reachable only on your private network, the PersivX server administrator also needs to allow that (see below).
Keycloak and other OpenID Connect providers
Create a confidential OpenID Connect client with the authorization code flow and PersivX's redirect URI. The issuer URL is the issuer value from the provider's /.well-known/openid-configuration (for Keycloak, https://<host>/realms/<realm>).
2. Enter the provider's details
Fill in Issuer URL, Client (application) ID and Client secret. The secret is stored encrypted and never shown again; leave it blank later to keep it. Turn on Turn on single sign-on and click Save. PersivX checks that it can reach the provider before saving.
3. Add and verify your email domains
Under Email domains, add each domain your people's addresses use (for example acme.com). PersivX shows a TXT record to add to that domain's DNS, such as persivx-sso-verification=…. Once it's published, click Verify. DNS changes can take a while to appear.
Verification proves your organization owns the domain, so no other customer can claim it. Each domain belongs to one organization only, and public email providers such as gmail.com or outlook.com can't be claimed. SSO only signs in addresses at verified domains.
Options
| Option | Default | What it does |
|---|---|---|
| Turn on single sign-on | Off | Adds SSO sign-in for addresses at your verified domains. Password sign-in keeps working. |
| Require SSO | Off | People in your organization can no longer sign in with a password; they're told to use SSO. The server's instance admin can always use a password, so a provider problem can't lock everyone out. Needs SSO on and at least one verified domain. |
| Trust the provider's two-step verification | Off | Skips PersivX's own two-step verification for SSO sign-ins. Turn it on only if your provider already requires it. |
4. Test it
Before telling everyone, sign in yourself with Sign in with SSO from a private browser window. Keep Require SSO off until that works, so password sign-in stays available while you fix any problem.
Setup messages
| Message | What to check |
|---|---|
| Could not reach your identity provider. Check the issuer URL. | The issuer URL is wrong, or the PersivX server can't reach the provider. |
| The issuer URL doesn't match what the identity provider reports. Use your tenant's own issuer URL. | Use the exact issuer, including any trailing /v2.0. For Microsoft, use your tenant ID, not common or organizations. |
| The issuer URL must start with https:// | Identity providers must use https. |
| Your identity provider refused the sign-in. Ask your admin to check the client id and secret. | The client ID or secret is wrong, or the secret has expired. Create a new secret and paste it in. |
| The TXT record wasn't found on … yet. | The DNS record isn't published yet or hasn't spread. Check its value matches exactly, and try again later. |
| … has already been added by an organization. | Another organization on this PersivX server has claimed that domain. Contact your PersivX administrator. |
An error on your provider's page about the redirect URI (for Microsoft, AADSTS50011) | The redirect URI registered with the provider doesn't exactly match the one PersivX shows. |
For the PersivX Server Administrator
Single sign-on is off for the whole server until you turn it on. Then each organization's admin sets it up for their own organization.
- Install the Python packages and run the database migration (
pip install -r requirements.txt, thenpython manage.py migrate). This adds SSO's own tables and changes no existing ones. - Set
SSO_ENABLED=1in the server's.envand restart PersivX. - Serve PersivX over https. If it runs behind a proxy, set
SSO_CALLBACK_URLto the public address, for examplehttps://persivx.example.com/utilities/auth/sso/callback/, so providers are given the right redirect URI. - The PersivX server must be able to reach each organization's provider over https. A provider on a private network (an internal AD FS server, for example) is blocked unless
ALLOW_PRIVATE_NETWORK_TARGETSis on. - Never set
SSO_DEV_MODEon a server people use. It exists only for testing with a local provider.
The instance admin can always sign in with a password, even in an organization that requires SSO.
When Someone Leaves
Disabling a person in your identity provider stops their next SSO sign-in, but a PersivX session they already have stays open until it expires (see Signing In & Account Security). To end it at once, also block their access in the admin console's Users list.
