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

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.omni.co/feedback

```json
{
  "path": "/administration/authentication/entra/saml",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Microsoft Entra SAML authentication

> Configure service provider (SP)-initiated SAML authentication between Microsoft Entra and Omni.

When enabled, users in your organization can log into Omni using their Microsoft Entra credentials.

## Requirements

To follow the steps in this guide, you'll need:

* **Omni Organization Admin permissions**

* **Permissions in Microsoft Entra that allow you to:**

  * Access the admin panel
  * Add & configure Microsoft Entra applications
  * Assign users to applications

## Setup

<Steps>
  <Step title="Open the Omni authentication settings">
    In your Omni instance, navigate to **Settings > Authentication** and locate the **SAML** section.

    Leave this page open - you'll need it to complete the setup.
  </Step>

  <Step title="Create an Omni application in Entra">
    1. Log in to the Microsoft Entra admin panel.
    2. Navigate to **Applications > Enterprise Applications**.
    3. Click **New application**, then **Create your own application**.
    4. Name the application `Omni`.
    5. Select the **Integrate any other application you don't find in the gallery (Non-gallery)** option.
    6. Click **Create**.
  </Step>

  <Step title="Configure the Entra Omni application">
    1. Click the Entra Omni application you created in the previous step.

    2. Navigate to the **Manage > Single sign-on configuration** section.

    3. Select **SAML sign-on** as the method.

    4. In the **Basic SAML configuration** section, click **Edit** and modify these settings:

       * **Identifier (Entity ID)** - Enter the full hostname of your Omni instance, e.g. `blobsrus.omniapp.co`. Do not include `https://`.
       * **Reply URL (Assertion Consumer Service URL)** - Copy and paste the value of the **Single sign-on URL** field from the Omni Authentication settings you opened in step 1.

    5. Save the changes to the settings.

    Next, edit the application's **Attributes & Claims**. This requires **three claims**, outlined as follows:

    |                      | **Claim 1**                                                                                    | **Claim 2**       | **Claim 3**      |
    | -------------------- | ---------------------------------------------------------------------------------------------- | ----------------- | ---------------- |
    | **Description**      | User's email address                                                                           | User's first name | User's last name |
    | **Name**             | `email_address`                                                                                | `first_name`      | `last_name`      |
    | **Namespace**        | Leave blank                                                                                    | Leave blank       | Leave blank      |
    | **Source**           | Attribute                                                                                      | Attribute         | Attribute        |
    | **Source attribute** | The attribute you use to identify a user's email address. Usually `user.email` or `user.mail`. | `user.first_name` | `user.surname`   |

    <Note>
      The name for a claim must **match exactly** the value in the **Name** row in the above table. For example, `first_name` is valid but `firstName` is not.
    </Note>

    Create and configure the claims for the application until you have one for each of the claims outlined in the previous table.
  </Step>

  <Step title="Assign yourself to the Entra Omni application">
    In this step, you'll assign the Entra Omni application to yourself. This will allow you to test the setup in Omni before rolling everything out to your organization.

    Follow the steps in the [Entra documentation](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-assign-users#assign-a-user-account-to-an-enterprise-application) to assign yourself to the Omni application.
  </Step>

  <Step title="Download the signing certificate">
    1. In the Entra Omni application's settings, locate the **SAML Certificates** section.
    2. Click the **Base64** download link to [download the certificate](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/tutorial-manage-certificates-for-federated-single-sign-on#autogenerated-certificate-for-gallery-and-non-gallery-applications).
    3. Locate the certificate file on your computer and change the extension to `.txt`. This will allow you to open it.
    4. Keep the file open - you'll need it to complete the next step.
  </Step>

  <Step title="Configure Omni authentication settings">
    Navigate back to the Omni authentication settings (**Settings > Authentication**) to complete the setup:

    * **Entity ID / Issuer** - Copy and paste the **Microsoft Entra ID Identifier** value from Entra

    * **SSO (Sign on) URL** - Copy and paste the **Login URL** value from Entra

    * **Certificate** - Copy and paste the contents of the certificate you downloaded in step 4.

          <Warning>
            The certificate must include `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`, for example:

            ```txt wrap theme={null}
            -----BEGIN CERTIFICATE-----[Your certificate contents]-----END CERTIFICATE-----
            ```

            If the certificate you paste into Omni doesn't have these values, add them in the **Certificate** field so that it looks like the above example.
          </Warning>

    * **Automatically provision new users on first login from this SAML provider** - Toggle this setting to **on** if:

      * You want to provision users only when they first access Omni **and**
      * You don't plan to set up SCIM provisioning

    * **Enable SAML login** - Toggle this setting to **on** to enable SAML authentication

    When finished, click **Save SAML changes**.

    <img src="https://mintcdn.com/omni-e7402367/Yjln-KKAZUa_xMOt/administration/authentication/images/omni-authentication-settings.png?fit=max&auto=format&n=Yjln-KKAZUa_xMOt&q=85&s=39a3c9cfd23ee9d9ece9e00d4d696bb4" alt="" width="970" height="873" data-path="administration/authentication/images/omni-authentication-settings.png" />
  </Step>

  <Step title="Test the setup">
    Test your SAML setup by logging out of Omni. On the Omni login page, you should see a **Log in with SAML** button. Click the button to log in using SAML.
  </Step>

  <Step title="Assign users to the Omni application">
    <Note>
      User groups can be pushed from Microsoft Entra to Omni using SCIM. Check out the [Entra-Omni SCIM guide](/administration/authentication/entra/scim) for more information.
    </Note>

    Once you confirm everything is working as expected, you can assign the Omni application to other people and groups in your organization.

    Follow the steps in the [Entra documentation](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-assign-users#assign-a-user-account-to-an-enterprise-application) to assign users to the Omni application.
  </Step>
</Steps>

## What's next?

Setting up SAML allows your users to authenticate to Omni using their Microsoft Entra credentials. With this setup completed, you can also:

* [Configure SCIM to auto-provision users & user groups in Omni](/administration/authentication/entra/scim)
* [Use SCIM to sync user attributes from Microsoft Entra to Omni](/administration/authentication/entra/user-attributes)