# SSO using SAML
### Overview
This guide walks Unifize workspace admins through setting up Single Sign-On (SSO) using SAML 2.0. When SSO is enabled, users in your org are authenticated through your company's identity provider (IdP)—such as Microsoft Entra ID, Okta, or Google Workspace—rather than with a Unifize password.
You can configure one or more SSO tenants under a single org. This is useful when your users are spread across multiple IdP tenants (for example, separate Microsoft Entra ID directories for different subsidiaries). Each tenant is mapped to specific email domains, so users are always routed to the right login portal.
### Before You Begin
Make sure you have the following ready before opening the SSO configuration page:
* Access to your IdP admin console (e.g., Microsoft Entra ID, Okta, Google Workspace)
* The email domain(s) you want to route through SSO (e.g., yourcompany.com)
* Permission to create an enterprise application in your IdP
* Unifize workspace admin role
### Step 1 — Open SSO Settings in Unifize
1. Log in to Unifize as a workspace admin.
2. Navigate to Org Settings → SSO.
3. Click Add Tenant to begin configuring your first (or additional) SSO tenant.
### Step 2 — Collect Values from Unifize to Configure Your IdP
Before filling in your IdP details, copy the following values from the Unifize SSO configuration panel. You will need to enter these into your IdP's enterprise application setup.
| Field in Unifize | Where to use it in your IdP | Example value |
| ------------------------------------------ | ------------------------------------ | ------------------------------------------------------------- |
| Identifier (Entity ID) | Application Entity ID / Audience URI | unifize-866-saml |
| Reply URL (Assertion Consumer Service URL) | ACS URL / Reply URL | |
| Sign on URL | Sign-on URL / Login initiation URL | |
### Step 3 — Configure the Enterprise Application in Your IdP
In your identity provider's admin console, create or open the enterprise application you will use for Unifize SSO, and enter the Unifize values from Step 2. The specific steps vary by IdP:
#### Microsoft Entra ID (Azure AD)
1. Go to Microsoft Entra ID → Enterprise applications → New application.
2. Select Create your own application and choose Integrate any other application you don't find in the gallery.
3. Under Single sign-on, choose SAML.
4. In Basic SAML Configuration, enter:
* Identifier (Entity ID): paste the Identifier value from Unifize
* Reply URL (ACS URL): paste the Reply URL from Unifize
* Sign on URL: paste the Sign on URL from Unifize
5. Save the configuration.
6. Download the Certificate (Base64) from the SAML Signing Certificate section.
7. Copy the Microsoft Entra Identifier (Entity ID) and Login URL from the Set up section.
#### Okta
1. Go to Applications → Create App Integration → SAML 2.0.
2. In the SAML Settings step, enter:
* Single sign-on URL: paste the Reply URL from Unifize
* Audience URI (SP Entity ID): paste the Identifier from Unifize
3. Complete setup and go to the Sign On tab.
4. Download the Signing Certificate and copy the Identity Provider Entity ID and Login URL.
#### Google Workspace
1. Go to Admin Console → Apps → Web and mobile apps → Add app → Add custom SAML app.
2. Copy the SSO URL and Certificate from the Google IdP details page—you will need these in Step 4.
3. In the Service Provider Details step, enter:
* ACS URL: paste the Reply URL from Unifize
* Entity ID: paste the Identifier from Unifize
4. Complete setup.
### Step 4 — Enter Your IdP Details into Unifize
Return to the Unifize SSO configuration page and fill in the tenant fields with the values from your IdP:
| Field in Unifize | What to enter | Where to find it in your IdP |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
| Domain | The email domain for this tenant (e.g., yourcompany.com). Users with this domain will be routed to this tenant's IdP. | Your org's email domain — not from the IdP |
| Microsoft Entra Identifier | The Entity ID of your IdP application | Entra: 'Microsoft Entra Identifier' in the Set up section |
| Login URL | The IdP's SAML login endpoint | Entra: 'Login URL' in the Set up section |
| Certificate (Base64) | The SAML signing certificate from your IdP. Must begin with -----BEGIN CERTIFICATE----- and end with -----END CERTIFICATE----- | Downloaded from IdP in Step 3 |
### Step 5 — Save and Test
1. Click Save in the Unifize SSO configuration panel.
2. Open a new private/incognito browser window.
3. Go to and enter an email address that belongs to the domain you configured.
4. You should be redirected to your IdP's login page.
5. Log in with your corporate credentials and confirm you land back in Unifize.
### Adding Additional Tenants
If your organization uses more than one identity provider tenant (for example, separate Entra ID directories for different business units), you can add multiple tenants to a single Unifize org.
1. In Org Settings → SSO, click Add Tenant.
2. Repeat Steps 2–5 for each additional tenant, using the credentials and domain(s) for that tenant.
3. Each tenant will have its own Domain, Microsoft Entra Identifier, Login URL, and Certificate.
## SSO Configuration Reference
### Field Reference
This table describes every field in the SSO tenant configuration panel and what is expected in each.
| Field | Description | Required |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| Domain | The email domain mapped to this tenant. Users with this domain are forced through SSO. Example: yourcompany.com | Yes — per tenant |
| Microsoft Entra Identifier | The Entity ID from your IdP. Identifies the IdP application to Unifize. Also called 'Identity Provider Entity ID' in Okta and 'Entity ID' in Google Workspace. | Yes |
| Login URL | The SAML login endpoint of your IdP. Unifize redirects users to this URL to begin authentication. | Yes |
| Certificate (Base64) | The X.509 signing certificate from your IdP, in Base64 format. Used to verify the SAML response. Must start with -----BEGIN CERTIFICATE----- and end with -----END CERTIFICATE----- | Yes |
| Identifier (Entity ID) | Read-only. Unifize's own SAML Entity ID. Copy this into your IdP's enterprise application configuration. | Provided by Unifize |
| Reply URL (ACS URL) | Read-only. The Assertion Consumer Service URL where your IdP sends the SAML response. Copy this into your IdP. | Provided by Unifize |
| Sign on URL | Read-only. A direct login link that triggers SSO for your org. Unique to the org; defaults to the first configured tenant. For tenant-specific links, append \&domain=\. | Provided by Unifize |
### Field Label Changes (Previous vs. Current)
The SSO configuration page labels were updated to match Microsoft Entra ID's SAML setup terminology. If you configured SSO previously, use this table to find the fields you are familiar with.
| Previous Label | Current Label |
| -------------------------- | ------------------------------------------ |
| Service Provider Entity ID | Reply URL (Assertion Consumer Service URL) |
| Org SSO URL | Sign on URL |
| Entity ID | Microsoft Entra Identifier |
| SSO URL | Login URL |
| Certificate | Certificate (Base64) |
### How Authentication Works — Admin Overview
Understanding the flow helps you diagnose issues and configure your IdP correctly.
1. User enters their work email on the Unifize login screen.
2. Unifize checks the email domain against all configured SSO tenants for your org.
3. If a matching tenant is found, the user is redirected to that tenant's Login URL.
4. The IdP authenticates the user (with MFA if your IdP policy requires it).
5. The IdP sends a SAML assertion back to Unifize's Reply URL (ACS URL).
6. Unifize validates the assertion using the Certificate (Base64) you provided.
7. The user is logged in and redirected to their workspace.
### User Email Updates and Tenant Migration
If a user's email address is updated in Unifize and their new domain belongs to a different SSO tenant, Unifize will automatically migrate them to the correct tenant.
Practically, this means:
* Updating a user's email in Unifize will re-evaluate which tenant they belong to.
* If their new domain maps to a different tenant, their account is migrated to that tenant automatically.
* No manual re-configuration is needed after an email domain change.
### Troubleshooting
| Symptom | Likely Cause | What to Check |
| -------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| User not redirected to IdP — sees password field instead | Email domain not mapped to any SSO tenant | Confirm the domain is entered correctly in the tenant's Domain field in Org Settings → SSO |
| SAML error / assertion validation failure | Certificate mismatch or expired certificate | Re-download the Base64 certificate from your IdP and update it in Unifize |
| Login loop — user keeps being redirected | ACS URL or Identifier mismatch between IdP and Unifize | Verify the Reply URL and Identifier in your IdP match exactly what Unifize shows |
| User redirected to wrong tenant's login | Email domain mapped to the wrong tenant | Review domain assignments across all configured tenants in Org Settings → SSO |
| Sign on URL routes to wrong tenant | URL defaults to first tenant when multiple are configured | Use the domain-scoped URL format: /sso-redirect?slug=\\&domain=\ |
| User cannot complete digital signature | OTP not delivered — email mismatch or spam filter | Verify the user's email in Unifize matches their IdP email; check spam/junk folder |
| Mobile login stalls after IdP redirect | Outdated app version or redirect handling issue | Ask the user to force-close and reopen the Unifize app, and update to the latest version |