> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visotrust.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SSO / SAML Configuration

> Set up SAML 2.0 single sign-on for VISO TRUST with Okta, Azure AD, Entra ID, or any compliant identity provider — including IdP setup and metadata exchange.

VISO TRUST supports Single Sign-On (SSO) with any **SAML 2.0 compliant identity provider (IdP)** — including Okta, Azure Active Directory / Entra ID, and others. Once SSO is configured, users authenticate through your IdP rather than with a VISO TRUST password.

SSO configuration requires coordination between your Org Admin and your VISO TRUST Customer Success representative. Contact [support@visotrust.com](mailto:support@visotrust.com) to begin the setup process.

## What You'll Need

SSO setup involves two sides: configuring VISO TRUST as a SAML application in your IdP, then providing the IdP's details to VISO TRUST.

### What VISO TRUST Provides to You

Your Customer Success representative will give you:

| Field                            | Description                                              |
| -------------------------------- | -------------------------------------------------------- |
| **Audience URI (Entity ID)**     | Identifies VISO TRUST to your IdP                        |
| **Single Sign-on URL (ACS URL)** | The endpoint in VISO TRUST that receives SAML assertions |

Enter these values when creating the VISO TRUST application in your IdP.

### What You Provide to VISO TRUST

Once the IdP application is configured, share the following with your CS representative:

| Field                       | Description                                  |
| --------------------------- | -------------------------------------------- |
| **IdP SSO URL**             | The SAML endpoint in your IdP                |
| **IdP Issuer URL**          | The entity ID of your IdP                    |
| **X.509 Certificate**       | The certificate used to sign SAML assertions |
| **IdP Metadata** (optional) | XML metadata file if available from your IdP |

## Required SAML Configuration

Your IdP application must be configured with these exact settings:

**Name ID format:** Email address (lowercase)

**SAML assertion attributes** (no namespace or format prefix):

| Attribute name | Value                                         |
| -------------- | --------------------------------------------- |
| `firstName`    | User's first name                             |
| `lastName`     | User's last name                              |
| `email`        | User's email address (must match the Name ID) |

The `email` attribute value must be identical to the Unique User Identifier / Name ID. This is used as the user's identifier across the platform and for email communications.

## Important Behavior Notes

**VISO TRUST does not support IdP-initiated login.** A tile or bookmark in your IdP dashboard will not directly sign users in. To give users a convenient entry point, create a **Bookmark application** in your IdP that points to `https://app.visotrust.com` and hide the actual SAML application from users.

**First login must use SAML.** New users cannot sign in with Google or Microsoft social login on their first access — they must use your SAML provider. After a successful first SSO login, social logins will work for subsequent sessions.

**User provisioning happens at first login.** Simply assign users to the VISO TRUST application in your IdP, then invite them in VISO TRUST and instruct them to navigate to `https://app.visotrust.com` and sign in with their email. Their IdP session handles the rest.

## Okta Setup Example

When creating the VISO TRUST app in Okta:

1. Create a new **SAML 2.0 application**
2. Set the **Single sign-on URL** to the ACS URL provided by VISO TRUST
3. Set the **Audience URI** to the Entity ID provided by VISO TRUST
4. Set **Name ID format** to `EmailAddress`
5. Set **Application username** to `Email`
6. Add attribute statements for `firstName`, `lastName`, and `email` mapped to the appropriate Okta profile fields
7. Download the IdP metadata or copy the SSO URL, Issuer URL, and certificate — share these with your VISO TRUST CS representative

## Azure Active Directory / Entra ID Setup Example

When creating the enterprise application in Azure:

1. Create a new **Enterprise Application → Non-gallery**
2. Go to **Single sign-on → SAML**
3. Set **Identifier (Entity ID)** to the Entity ID provided by VISO TRUST
4. Set **Reply URL (ACS URL)** to the ACS URL provided by VISO TRUST
5. Set **Name ID format** to `Email address`
6. Add claims for `firstName`, `lastName`, and `email`
7. Download the **Federation Metadata XML** and share it with your VISO TRUST CS representative

## Troubleshooting

| Symptom                                           | Likely cause                                                         |
| ------------------------------------------------- | -------------------------------------------------------------------- |
| User sees an error after IdP login                | Name ID format is not set to email, or attributes are missing        |
| User can't log in — redirected to login page      | IdP-initiated login attempted; direct to `app.visotrust.com` instead |
| New user can't access after being assigned in IdP | User hasn't been invited in VISO TRUST yet — invite them first       |
| Social login fails for a new user                 | First login must be via SAML; social logins work after that          |

For configuration assistance, contact [support@visotrust.com](mailto:support@visotrust.com).