> For the complete documentation index, see [llms.txt](https://learn.spexi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://learn.spexi.com/spexi-world-viewer/administration/configure-sso-saml-for-your-organization.md).

# Configure SSO/SAML for your organization

This guide provides step-by-step instructions for configuring Single Sign-On (SSO) using SAML in your organization. Follow these instructions to ensure a secure and seamless setup, regardless of your Identity Provider (IdP).

{% stepper %}
{% step %}

### Open the SSO/SAML configuration page

From Spexi World, navigate to **Settings** \[⚙️], then **SSO/SAML Configuration.**
{% endstep %}

{% step %}

### Configure SSO/SAML configuration detials

* Create a new SAML application in your IdP (e.g., Microsoft Entra, Google Workspace, Okta, OneLogin, Ping Identity, etc.).
* Enter the following details from your IdP:
  * Entity ID: Copy and paste the Entity ID from your IdP.
    * Example: `https://accounts.google.com/o/saml2?idpid=C02so64kf`
  * Entry Point URL: Enter the authentication request URL provided by your IdP.
    * Example: `https://accounts.google.com/o/saml2/idp?idpid=C02so64kf`
  * Certificate: Upload the X.509 certificate provided by your IdP (leave blank to retain the current one).
    * Certificates are used for secure authentication between your application and the IdP.
      {% endstep %}

{% step %}

### Configure attribute mappings

Map user attributes from your IdP to the corresponding fields in Spexi:

* First Name → firstName
* Last Name → lastName

Click Add Attribute Mapping for additional attributes.
{% endstep %}

{% step %}

### Add authorized domains

Enter the domains allowed to use SSO:

* `spexi.com`
* `spexigeo.com`

To remove a domain, click Remove next to it.
{% endstep %}

{% step %}

### Enable and test configuration

Test things out before enabling SSO for all users:

* Enable Test Mode.
* Use a test email: `sso://your-email@example.com`
* Attempt to login and verify SSO is working.

{% hint style="warning" %}
If Test Mode is disabled without a valid setup, users may lose access!
{% endhint %}
{% endstep %}

{% step %}

### Configure your identity provider (IdP)

* Configure the following settings in your IdP:
  * Assertion Consumer Service (ACS) URL
  * Entity ID
* Follow your IdP’s setup guide to configure a new SAML application using the provided ACS URL and Entity ID.

{% endstep %}

{% step %}

### Finalize your configuration

* Click Update SSO Config to save changes.
* Disable Test Mode once setup is confirmed to apply SSO to all users.
  {% endstep %}
  {% endstepper %}

#### Troubleshooting Guide

**Login Issues**

* Verify that ACS URL and Entity ID match the IdP settings.
* Check that the certificate is correctly uploaded.

**Attribute Mapping Errors**

* Ensure attribute names match exactly between IdP and Spexi.

**Domain Authorization Errors**

* Ensure all required domains are listed in the Domains section.

#### Need help? If you encounter issues, refer to your Identity Provider documentation or contact Spexi Support for assistance.