Single sign-on

Verify your domain, connect a SAML 2.0 or OpenID Connect identity provider, and require SSO once it works.

Single sign-on (SSO) lets people sign in to UnitX with your existing identity provider — Okta, Microsoft Entra ID, Google Workspace or any other SAML 2.0 or OpenID Connect provider — instead of a separate UnitX password. You prove you own your email domain, connect your provider, and, once it works, can require it.

How it fits together#

Open SettingsSingle sign-on. It has three sub-tabs:

1. Domains — add the domain your people’s email addresses use and prove you control it with a DNS record.
2. Identity provider — connect a verified domain to your provider and, once sign-in works, require SSO for it.
3. Provisioning — let your provider create and deactivate members automatically. See SCIM provisioning.

Who can set it up#

Permissions

sso.managescim.manage

sso.manage shows the tab and covers domains and identity providers. scim.manage is needed for the Provisioning sub-tab. Both are held by Organization Owner and Organization Admin.

Before you start#

A domain your organization owns, and access to add a TXT record to its DNS.
Administrator access to your identity provider, to create an application for UnitX.
For SAML: your provider’s sign-on URL and its public signing certificate. For OpenID Connect: the issuer, the client ID and the JWKS URI.

Step 1: Add and verify your domain#

Add the domain
On 1. Domains, type the domain (for example everyrealm.com) and choose Add domain. It appears with a Not verified badge.
Publish the TXT record
Copy the value shown under the domain and add it as a TXT record on that exact domain at your DNS host.
Choose Verify
DNS changes can take a few minutes to propagate. When UnitX finds the record, the badge changes to Verified.

Why verification matters

Verification is what stops another organization from configuring SSO for your domain and claiming your people. A domain can belong to only one organization, and public email domains such as gmail.com cannot be used at all.

Remove next to a domain deletes it.

Step 2: Connect your identity provider#

The 2. Identity provider sub-tab only offers verified domains. Until you have one, it shows Verify a domain first.

Choose the domain and protocol
Under Configure an identity provider, pick the verified Domain and the Protocol: SAML 2.0 or OpenID Connect.
Enter your provider’s details
For SAML 2.0, paste the Sign-on URL and the Signing certificate. For OpenID Connect, enter the Issuer, Client ID and JWKS URI.
Choose Save connection
The certificate is checked when you save, so a malformed one is caught now rather than at someone’s first sign-in. The connection appears below with its status.
Give UnitX’s details to your provider
Each connection shows Give these to your identity provider: an Entity ID and a Reply URL. Enter both in the application you created for UnitX in your provider.
Test with a real account
Have someone with an address on the domain sign in through your provider before going any further.

Field reference#

Sign-on URL: SAML only. Where your provider receives sign-in requests.
Signing certificate: SAML only. Your provider’s public X.509 certificate, beginning -----BEGIN CERTIFICATE-----. It is public, so it is shown back to you.
Issuer: OpenID Connect only. Your provider’s issuer URL.
Client ID: OpenID Connect only. The ID of the application you created for UnitX.
JWKS URI: OpenID Connect only. Where your provider publishes the keys that sign its tokens.
Entity ID / Reply URL: Generated by UnitX. Your provider needs both to send people back to UnitX.

Step 3: Require SSO#

Once sign-in works, switch on Require SSO for this domain on the connection. From then on, people with an email address on that domain can no longer sign in with a password.

Warning

Confirm that SSO sign-in works before you require it. If the connection is misconfigured while SSO is required, people on that domain cannot sign in with a password to get round it.

What happens to existing accounts#

When someone signs in through SSO for the first time and UnitX already has an account with that email address, SSO does not take the account over. A link is recorded, and the account owner has to confirm it before SSO sign-in is connected to their account. This stops a misconfigured or hostile provider from gaining access to someone else’s account.

Your provider must also have verified the email address it sends, and the address must be on the connection’s domain; otherwise the sign-in is refused.

Certificate expiry and rotation#

Within 30 days of a SAML certificate expiring, the connection shows Certificate expires in Nd, and Certificate expired afterwards. Renew it with your provider before then.
When a replacement certificate has been staged for a connection, it shows Rotation pending and a Finish rotation button. Choose it once your provider has switched to the new certificate; the previous certificate is no longer accepted from that moment. Staging a replacement is done through the UnitX API.

“The verification TXT record was not found”

The record is missing, is on a different host name, or DNS has not propagated yet. Check it is on the exact domain shown, wait a few minutes and choose Verify again.

“Verify the domain before configuring SSO for it”

Finish step 1 first. Only verified domains can carry a connection.

“That domain is already claimed”

Another UnitX organization has already added it. A domain can belong to only one organization.

“That does not parse as an X.509 certificate”

Paste the whole certificate, including the BEGIN and END lines, exactly as your provider gives it.

Does SSO replace two-factor authentication?

For people signing in through SSO, your identity provider’s own sign-in rules apply. The organization-wide two-factor requirement is a separate switch; see Organization settings.

Still stuck? Search the docs with ⌘K, open Help inside UnitX, or contact support.