> ## 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.

# Configuring Snowflake External OAuth with Microsoft Entra ID

> Configure Snowflake External OAuth to authenticate users through Microsoft Entra ID (Azure AD).

<Note>
  For authenticating Snowflake users directly through Snowflake, see [Snowflake native OAuth](/connect-data/oauth/snowflake/native).
</Note>

[Snowflake External OAuth](https://docs.snowflake.com/en/user-guide/oauth-ext-overview) allows each Omni user to authenticate to Snowflake using their own identity through an external identity provider instead of Snowflake's built-in OAuth server. Each user's queries run under their own Snowflake role and session, so Snowflake's row-level security and role restrictions apply automatically.

## Requirements

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

* **Permissions in Microsoft Entra ID** that allow you to register applications and configure OAuth settings
* **In Omni**:
  * To have the **OAuth database connection** feature enabled
  * **Organization Admin** permissions
  * **An existing Snowflake connection.** Refer to [Connecting a Snowflake database](/connect-data/setup/snowflake) before continuing.
* **In Snowflake**:
  * **`ACCOUNTADMIN` or `SECURITYADMIN`** privileges to create a security integration
  * **A service account** with access to all schemas and tables you want to use in Omni. This is required even when OAuth is enabled, because Omni uses the service account to build the model.
  * **To assign regular user roles to your Snowflake users.** Snowflake blocks `ACCOUNTADMIN`, `ORGADMIN`, and `SECURITYADMIN` from external OAuth authentication by default.

<Warning>
  Before continuing, review the [OAuth limitations](/connect-data/oauth#limitations).
</Warning>

## Setup

<Steps>
  <Step title="Register an Entra OAuth resource app" id="create-resource-app" titleSize="h3">
    <Steps>
      <Step title="Create the app" noAnchor>
        1. In the Azure portal, navigate to **Microsoft Entra ID > App registrations**.
        2. Click **New registration**.
        3. Enter a name (e.g., *Omni Snowflake OAuth Resource*).
        4. Set **Supported account types** to **Single tenant**.
        5. Click **Register**.
      </Step>

      <Step title="Set the Application ID URI" noAnchor>
        1. Navigate to **Expose an API**.
        2. Click the link next the **Application ID URI** to add the Application ID URI. This value must be unique within your directory (e.g., `https://<your-domain>/<app-guid>`).

        Save this value — you'll need it as the **Audience** in both Snowflake and Omni.
      </Step>

      <Step title="Configure app permissions" noAnchor>
        1. Click **Add a scope**.
        2. Select who can consent.
        3. In the **Value** field, enter `session:role-any`. This allows the token to work with any role the user holds in Snowflake.
        4. **Optional**. Add a description.
        5. Save the role.
      </Step>
    </Steps>
  </Step>

  <Step title="Register an Entra OAuth client app" id="create-client-app" titleSize="h3">
    <Steps>
      <Step title="Create the app" noAnchor>
        1. In the Azure portal, navigate to **Microsoft Entra ID > App registrations**.
        2. Click **New registration**.
        3. Enter a name (e.g., *Omni Snowflake OAuth Client*).
        4. Set **Supported account types** to **Single tenant**.
        5. Click **Register**.
      </Step>

      <Step title="Retrieve your OAuth information" noAnchor>
        1. On the page that displays after registering the app, copy the **Application (client) ID**. This is your **OAuth Client ID** for Omni.
        2. Navigate to **Certificates & secrets > New client secret**.
        3. Copy the secret value. This is your **OAuth Client Secret** for Omni.
      </Step>

      <Step title="Configure app permissions" noAnchor>
        1. Navigate to **Manage API permissions > Add a permission > My APIs**.
        2. Select the Omni resource app you created in the previous section.
        3. Select the **Delegated Permissions** box.
        4. Confirm that the scope permissions (`session:role-any`) for the resource app are present and correct.
        5. Click **Add permissions**.
        6. Click **Grant admin consent** to grant the permissions to the client.
        7. Click **Yes**.
      </Step>

      <Step title="Add the redirect URI" noAnchor>
        1. Navigate to **Manage > Authentication**.
        2. Add a **web** platform.
        3. Add the following **Redirect URI**, replacing `<your-omni-domain>` with the name of your Omni instance:

           ```text theme={null}
           https://callbacks.<your-omni-domain>/callback/oauth
           ```
      </Step>
    </Steps>
  </Step>

  <Step title="Collect Entra ID metadata" id="collect-metadata" titleSize="h3">
    In your resource app registration, go to the **Endpoints** tab and collect the following values:

    | Value                      | Where to find it                                                                                                                          |
    | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
    | **Authorization endpoint** | **OAuth 2.0 authorization endpoint (v2)**                                                                                                 |
    | **Token endpoint**         | **OAuth 2.0 token endpoint (v2)**                                                                                                         |
    | **JWK Set URI**            | Open the **OpenID Connect metadata document** URL in a browser and find the `jwks_uri` value                                              |
    | **Issuer**                 | Open the **Federation metadata document** URL in a browser and find the `entityID` value (format: `https://sts.windows.net/<tenant-id>/`) |
  </Step>

  <Step title="Create a Snowflake security integration" id="create-snowflake-integration" titleSize="h3">
    Run this in Snowflake as `ACCOUNTADMIN` or `SECURITYADMIN`, substituting the values from the previous step.

    ```sql theme={null}
    CREATE SECURITY INTEGRATION omni_external_oauth_azure
      TYPE = EXTERNAL_OAUTH
      ENABLED = TRUE
      EXTERNAL_OAUTH_TYPE = AZURE
      EXTERNAL_OAUTH_ISSUER = '<issuer from Federation metadata>'
      EXTERNAL_OAUTH_JWS_KEYS_URL = '<jwks_uri from OpenID metadata>'
      EXTERNAL_OAUTH_AUDIENCE_LIST = ('<Application ID URI from resource app>')
      EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM = 'upn'                    
      EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = 'login_name'
      EXTERNAL_OAUTH_ANY_ROLE_MODE = 'ENABLE';
    ```

    When filling in the placeholder values, keep in mind that:

    * The `EXTERNAL_OAUTH_ISSUER` value is case-sensitive and must match exactly. Include the trailing slash (`https://sts.windows.net/<tenant-id>/`).
    * The `EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM: upn` (User Principal Name) claim maps Entra ID users to Snowflake. Each user's UPN in Entra ID must exactly match the `LOGIN_NAME` on their Snowflake user record. Verify this before going live.
  </Step>

  <Step title="Configure the connection in Omni" id="configure-omni" titleSize="h3">
    <Note>
      You must still configure a service account on this connection. Omni uses the service account to build the model, which provides the foundation for all user queries.
    </Note>

    This guide assumes you have an existing Snowflake connection in Omni. If you don't, refer to [Connecting a Snowflake database](/connect-data/setup/snowflake) for more information.

    1. In Omni, navigate to **Settings > Connections** and click on the Snowflake connection you want to use.

    2. Under **Authentication type**, select **External OAuth User Authentication**.

    3. Fill in the fields as follows:

       | Field               | Value                                                             |
       | ------------------- | ----------------------------------------------------------------- |
       | Authorization URL   | Authorization endpoint from [Entra ID](#collect-metadata)         |
       | Token URL           | Token endpoint from [Entra ID](#collect-metadata)                 |
       | OAuth Client ID     | Application (client) ID from the [client app](#create-client-app) |
       | OAuth Client Secret | Client secret from the [client app](#create-client-app)           |
       | Audience            | Application ID URI from the [resource app](#create-resource-app)  |

    4. Save the connection.
  </Step>

  <Step title="Verify the user experience" titleSize="h3">
    After saving, each Omni user who wants to query this connection will need to authorize once through the OAuth flow. They'll be redirected to Microsoft to sign in, then redirected back to Omni. After that, Omni will automatically refresh their token in the background.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication failures">
    Double-check that each user's UPN (User Principal Name) in Entra ID matches their Snowflake `LOGIN_NAME` exactly (case-sensitive). Mismatches are the most common cause of auth failures.
  </Accordion>

  <Accordion title="Token expiration issues">
    If users experience frequent re-authentication prompts, verify that:

    * The refresh token lifetime in Entra ID is sufficient
    * The Snowflake security integration is correctly configured with the IdP's token endpoint
  </Accordion>
</AccordionGroup>

## Next steps

To ensure database permissions align with what users see in Omni, we recommend implementing:

* [**Access grants**](/modeling/models/access-grants) to control which fields and tables are visible to each user in the model and field browser
* [**Content permissions**](/administration/users/permissions) to control which dashboards and documents users can access