Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

clarify email mismatch in external oauth #6701

Open
wants to merge 3 commits into
base: current
Choose a base branch
from
+31 −19
Open

clarify email mismatch in external oauth #6701

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8b331ee
add callouts about email mismatch
mirnawong1 Dec 20, 2024
c48d819
Merge branch 'current' into update-external-oauth
mirnawong1 Dec 23, 2024
0a2f638
Merge branch 'current' into update-external-oauth
runleonarun Dec 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 31 additions & 19 deletions website/docs/docs/cloud/manage-access/external-oauth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,11 @@ The process of setting up external OAuth will require a little bit of back-and-f

If the admins that handle these products are all different people, it’s better to have them coordinating simultaneously to reduce friction.

:::info Username and credential matching required
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we title this, Snowflake and idP username matching required because it sounds like the credentials are not required to match. Or are they? If they are, we might want to specify that below.

Ensure that the username entered by the IdP admin matches the username in the Snowflake credentials. If the email address used in the dbt Cloud setup is different from the Snowflake username, the connection will fail or you may run into issues.
:::


### Snowflake commands

The following is a template for creating the OAuth configurations in the Snowflake environment:
Expand All @@ -45,18 +50,22 @@ external_oauth_audience_list = ('')
external_oauth_token_user_mapping_claim = 'sub'
external_oauth_snowflake_user_mapping_attribute = 'email_address'
external_oauth_any_role_mode = 'ENABLE'

```

The `external_oauth_token_user_mapping_claim` and `external_oauth_snowflake_user_mapping_attribute` can be modified based on the your organizations needs. These values point to the claim in the users’ token. In the example, Snowflake will look up the Snowflake user whose `email` matches the value in the `sub` claim.

**Note:** The Snowflake default roles ACCOUNTADMIN, ORGADMIN, or SECURITYADMIN, are blocked from external OAuth by default and they will likely fail to authenticate. See the [Snowflake documentation](https://docs.snowflake.com/en/sql-reference/sql/create-security-integration-oauth-external) for more information.
**Notes:**
- The Snowflake default roles ACCOUNTADMIN, ORGADMIN, or SECURITYADMIN, are blocked from external OAuth by default and they will likely fail to authenticate. See the [Snowflake documentation](https://docs.snowflake.com/en/sql-reference/sql/create-security-integration-oauth-external) for more information.
- The value for `external_oauth_snowflake_user_mapping_attribute` must map correctly to the Snowflake username. For example, if `email_address` is used, the email in the token from the IdP must match the Snowflake username exactly.

## Identity provider configuration

Select a supported identity provider (IdP) for instructions on configuring external OAuth in their environment and completing the integration in dbt Cloud.
Select a supported identity provider (IdP) for instructions on configuring external OAuth in their environment and completing the integration in dbt Cloud:

<Expandable alt_header="Okta">
- [Okta](#okta)
- [Entra ID](#entra-id)

## Okta

### 1. Initialize the dbt Cloud settings

Expand Down Expand Up @@ -139,6 +148,11 @@ Adjust the other settings as needed to meet your organization's configurations i

3. Run the steps to create the integration in Snowflake.

:::info Username consistency
Ensure that the username (for example, email address) entered in the IdP matches the Snowflake credentials for all users. Mismatched usernames will result in authentication failures.
:::


### 5. Configuring the integration in dbt Cloud

1. Navigate back to the dbt Cloud **Account settings** —> **Integrations** page you were on at the beginning. It’s time to start filling out all of the fields.
Expand Down Expand Up @@ -169,31 +183,29 @@ Adjust the other settings as needed to meet your organization's configurations i

4. **Save** the connection, and you have now configured External OAuth with Okta and Snowflake!

</Expandable>

<Expandable alt_header="Entra ID">

## Entra ID

### 1. Initialize the dbt Cloud settings

1. In your dbt Cloud account, navigate to **Account settings** —> **Integrations**.
2. Scroll down to **Custom integrations** and click **Add integrations**.
3. Leave this window open. You can set the **Integration type** to Entra ID and note the **Redirect URI** at the bottom of the page. Copy this to your clipboard for use in the next steps.

### Entra ID
### 2. Create the Entra ID apps

You’ll create two apps in the Azure portal: A resource server and a client app.
- You’ll create two apps in the Azure portal: A resource server and a client app.
- In your Azure portal, open the **Entra ID** and click **App registrations** from the left menu.

:::important

The admin who creates the apps in the Microsoft Entra ID account must also be a user in Snowflake.

The `value` field gathered in these steps is only displayed once. When created, record it immediately.

- The admin who creates the apps in the Microsoft Entra ID account must also be a user in Snowflake.
- The `value` field gathered in these steps is only displayed once. When created, record it immediately.
- Ensure that the username (for example, email address) entered in the IdP matches the Snowflake credentials for all users. Mismatched usernames will result in authentication failures.
:::

In your Azure portal, open the **Entra ID** and click **App registrations** from the left menu.

### 1. Create a resource server
### 3. Create a resource server

1. From the app registrations screen, click **New registration**.
1. Give the app a name.
Expand All @@ -209,7 +221,7 @@ In your Azure portal, open the **Entra ID** and click **App registrations** from
4. Ensure **State** is set to **Enabled**.
5. Click **Add scope**.

### 2. Create a client app
### 4. Create a client app

1. From the **App registration page**, click **New registration**.
1. Give the app a name that uniquely identifies it as the client app.
Expand All @@ -225,7 +237,7 @@ In your Azure portal, open the **Entra ID** and click **App registrations** from
7. Record the `value` for use in a future step and record it immediately.
**Note**: Entra ID will not display this value again once you navigate away from this screen.

### 3. Snowflake configuration
### 5. Snowflake configuration

You'll be switching between the Entra ID site and Snowflake. Keep your Entra ID account open for this process.

Expand Down Expand Up @@ -257,7 +269,7 @@ app in Entra ID, click **Endpoints** and open the **Federation metadata document
- The **Application ID URI** maps to the `external_oauth_audience_list` field in Snowflake.
4. Run the configurations. Be sure the admin who created the Microsoft apps is also a user in Snowflake, or the configuration will fail.

### 4. Configuring the integration in dbt Cloud
### 6. Configuring the integration in dbt Cloud

1. Navigate back to the dbt Cloud **Account settings** —> **Integrations** page you were on at the beginning. It’s time to start filling out all of the fields. There will be some back-and-forth between the Entra ID account and dbt Cloud.
2. `Integration name`: Give the integration a descriptive name that includes identifying information about the Entra ID environment so future users won’t have to guess where it belongs.
Expand All @@ -266,7 +278,7 @@ app in Entra ID, click **Endpoints** and open the **Federation metadata document
5. `Authorization URL` and `Token URL`: From the client ID app, open the `Endpoints` tab. These URLs map to the `OAuth 2.0 authorization endpoint (v2)` and `OAuth 2.0 token endpoint (v2)` fields. *You must use v2 of the `OAuth 2.0 authorization endpoint`. Do not use V1.* You can use either version of the `OAuth 2.0 token endpoint`.
6. `Application ID URI`: Copy the `Application ID URI` field from the resource server’s Overview screen.

</Expandable>


## FAQs

Expand Down
Loading