Skip to content

Commit

Permalink
Adding Entra ID to Oauth (#5909)
Browse files Browse the repository at this point in the history 
## What are you changing in this pull request and why?

beta doc

## Checklist
<!--
Uncomment when publishing docs for a prerelease version of dbt:
- [ ] Add versioning components, as described in [Versioning
Docs](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#versioning-entire-pages)
- [ ] Add a note to the prerelease version [Migration
Guide](https://github.com/dbt-labs/docs.getdbt.com/tree/current/website/docs/docs/dbt-versions/core-upgrade)
-->
- [ ] Review the [Content style
guide](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/content-style-guide.md)
so my content adheres to these guidelines.
- [ ] For [docs
versioning](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#about-versioning),
review how to [version a whole
page](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#adding-a-new-version)
and [version a block of
content](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/single-sourcing-content.md#versioning-blocks-of-content).
- [ ] Add a checklist item for anything that needs to happen before this
PR is merged, such as "needs technical review" or "change base branch."

Adding or removing pages (delete if not applicable):
- [ ] Add/remove page in `website/sidebars.js`
- [ ] Provide a unique filename for new pages
- [ ] Add an entry for deleted pages in `website/vercel.json`
- [ ] Run link testing locally with `npm run build` to update the links
that point to deleted pages
  • Loading branch information
@matthewshaver
matthewshaver authored Aug 8, 2024
1 parent 7403a54 commit bc9a7d7
Showing 1 changed file with 104 additions and 9 deletions.
113 changes: 104 additions & 9 deletions website/docs/docs/cloud/manage-access/external-oauth.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ title: "Set up external Oauth"
id: external-oauth
description: "Configuration instructions for dbt Cloud and external Oauth connections"
sidebar_label: "Set up external Oauth"
unlisted: true
pagination_next: null
pagination_prev: null
---
Expand All @@ -13,7 +14,7 @@ pagination_prev: null

External OAuth for authentication is available in a limited beta. If you are interested in joining the beta, please contact your account manager.

This feature is currently only available for the Okta identity provider and Snowflake connections. Only available to Enterprise accounts.
This feature is currently only available for the Okta and Entra ID identity providers and Snowflake connections. Only available to Enterprise accounts.

:::

Expand All @@ -22,11 +23,12 @@ dbt Cloud Enterprise supports [OAuth authentication](https://docs.snowflake.net

## Getting started

The process of setting up external Oauth will require a little bit of back-and-forth between your dbt Cloud, Okta, and Snowflake accounts, and having them open in multiple browser tabs will help speed up the configuration process:
The process of setting up external Oauth will require a little bit of back-and-forth between your dbt Cloud, IdP, and Snowflake accounts, and having them open in multiple browser tabs will help speed up the configuration process:

- **dbt Cloud:** You’ll primarily be working in the **Account Settings** —> **Integrations** page. You will need [proper permission](/docs/cloud/manage-access/enterprise-permissions) to set up the integration and create the connections.
- **Snowflake:** Open a worksheet in an account that has permissions to [create a security integration](https://docs.snowflake.com/en/sql-reference/sql/create-security-integration).
- **Okta:** You’ll be working in multiple areas of the Okta account, but you can start in the **Applications** section. You will need permissions to [create an application](https://help.okta.com/en-us/content/topics/security/custom-admin-role/about-role-permissions.htm#Application_permissions) and an [authorization server](https://help.okta.com/en-us/content/topics/security/custom-admin-role/about-role-permissions.htm#Authorization_server_permissions).
- **Entra ID** An admin with access to create [Entra ID apps](https://learn.microsoft.com/en-us/entra/identity/role-based-access-control/custom-available-permissions) who is also a user in Snowflake is required.

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

Expand All @@ -53,15 +55,17 @@ The `external_oauth_token_user_mapping_claim` and `external_oauth_snowflake_u

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

## 1. Initialize the dbt Cloud settings
## Set up with Okta

### 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 Okta and make a note of the **Redirect URI** at the bottom of the page. Copy this to your clipboard for use in the next steps.

<Lightbox src="/img/docs/dbt-cloud/callback-uri.png" width="60%" title="Copy the callback URI at the bottom of the integration page in dbt Cloud" />

## 2. Create the Okta app
### 2. Create the Okta app

1. From the Okta dashboard, expand the **Applications** section and click **Applications.** Click the **Create app integration** button.
2. Select **OIDC** as the sign-in method and **Web applications** as the application type. Click **Next**.
Expand All @@ -76,7 +80,7 @@ The `external_oauth_token_user_mapping_claim` and `external_oauth_snowflake_u

6. Save the app configuration. You’ll come back to it, but for now move on to the next steps.

## 3. Create the Okta API
### 3. Create the Okta API

1. From the Okta sidebar menu, expand the **Security** section and clicl **API**.
2. On the API screen, click **Add authorization server**. Give the authorizations server a name (a nickname for your Snowflake account would be appropriate). For the **Audience** field, copy and paste your Snowflake login URL (for example, https://abdc-ef1234.snowflakecomputing.com). Give the server an appropriate description and click **Save**.
Expand Down Expand Up @@ -107,7 +111,7 @@ The `external_oauth_token_user_mapping_claim` and `external_oauth_snowflake_u

8. Navigate back to the **Settings** tab and leave it open in your browser. You’ll need some of the information in later steps.

## 4. Create the Oauth settings in Snowflake
### 4. Create the Oauth settings in Snowflake

1. Open up a Snowflake worksheet and copy/paste the following:

Expand All @@ -134,7 +138,7 @@ Adjust the other settings as needed to meet your organizations configurations in

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

## 5. Configuring the integration in dbt Cloud
### 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.
1. `Integration name`: Give the integration a descriptive name that includes identifying information about the Okta environment so future users won’t have to guess where it belongs.
Expand All @@ -145,7 +149,7 @@ Adjust the other settings as needed to meet your organizations configurations in

2. **Save** the configuration

## 6. Create a new connection in dbt Cloud
### 6. Create a new connection in dbt Cloud

1. Navigate the **Account settings** and click **Connections** from the menu. Click **Add connection**.
2. Configure the `Account`, `Database`, and `Warehouse` as you normally would and for the `Oauth method` select the external Oauth you just created.
Expand All @@ -156,4 +160,95 @@ Adjust the other settings as needed to meet your organizations configurations in

<Lightbox src="/img/docs/dbt-cloud/select-oauth-config.png" width="60%" title="The new connection displayed in the External Oauth Configurations box" />

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

## Set up with 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 Okta and make a note of the **Redirect URI** at the bottom of the page. Copy this to your clipboard for use in the next steps.

### Entra ID

You’ll be creating two different `apps` in the Azure portal &mdash; A resource server and client app.

:::important

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

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

:::

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

### 1. Create a resource server

1. From the app registrations screen, click **New registration**
2. Give the app a name.
3. Ensure **Supported account types** is set to “Accounts in this organizational directory only (`Org name` - Single Tenant).”
4. Click **Register**.
5. From the app page, click **Expose an API** from the left menu.
6. Click **Add** next to **Application ID URI**. The field will automatically populate, so click **Save**.
7. Record the `value` field as it will be used in a future step. *This is only displayed once, so be sure to record it immediately. It will be hidden when you leave the page and come back.*
8. From the same screen, click **Add scope**.
1. Give the scope a name.
2. Set “Who can consent?” to **Admins and users**.
3. Set **Admin consent display name** session:role-any and give it a description.
4. Ensure **State** is set to **Enabled**.
5. Click **Add scope**.

### 2. Create a client app

1. From the **App registration page**, click **New registration**.
2. Give the app a name that will uniquely identify it as the client app.
3. Ensure **Supported account types** is set to “Accounts in this organizational directory only (`Org name` - Single Tenant).”
4. Set the **Redirect URI** to **Web** and copy/paste the **Redirect URI** from dbt Cloud into the field.
5. Click **Register**.
6. From the app page, click **API permissions from the left menu, and click **Add permission**.
7. From the pop-out screen, click **APIs my organization uses and search for the resource server name from the previous steps and click it.
8. Ensure the box for the **Permissions** `session:role-any` is checked and click **Add permissions.
9. Click **Grant admin consent** and from the popup modal click **Yes**.
10. From the left menu, click **Certificates and secrets**. Click **New client secret**. Name the secret, set an expiration, and click **Add**. **Note**: Microsoft does not allow “forever” as an expiration. The maximum time is two years. It’s important to document the expiration date so that the secret can be refreshed before the expiration or user authorization will fail.
11. Record the **Value** for use in a future step and record it immediately. _Once you navigate away from this screen, this value will not be displayed again._

### 3. Snowflake configuration

You'll be going back-and-forth between the Entra ID site and Snowflake. Keep your Entra ID account open for this process.

Copy and paste the following as a template in a Snowflake worksheet:

```sql
create or replace security integration <whatever you want to name it>
type = external_oauth
enabled = true
external_oauth_type = azure
external_oauth_issuer = '<AZURE_AD_ISSUER>'
external_oauth_jws_keys_url = '<AZURE_AD_JWS_KEY_ENDPOINT>'
external_oauth_audience_list = ('<SNOWFLAKE_APPLICATION_ID_URI>')
external_oauth_token_user_mapping_claim = 'upn'
external_oauth_any_role_mode = 'ENABLE'
external_oauth_snowflake_user_mapping_attribute = 'login_name';
```

In the Entra ID site:

1. From the Client ID app in Entra ID click **Endpoints** and open the **Federation metadata document** in a new tab.
- The **entity ID** on this page maps to the `external_oauth_issuer` field in the Snowflake config.
2. Back on the list of endpoints, open the **OpenID Connect metadata document** in a new tab.
- The **jwks_uri** field maps to the `external_oauth_jws_keys_url` field in Snowflake.
3. Navigate to the resource server in previous steps.
- The **Application ID URI** maps to teh `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

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 here between the Entra ID account and dbt Cloud.
2. `Integration name`: Give the integration a descriptive name that includes identifying information about the Okta environment so future users won’t have to guess where it belongs.
3. `Client secrets`: These are found in the Client ID from the **Certificates and secrets** page. `Value` is the `Client secret` . Note that it only appears when it is created; if you come back later it will be hidden and you will have to recreate the secret.
4. `Client ID`: On the overview page for the client ID app, copy the `Application (client) ID`.
5. `Authorization URL` and `Token URL`: From the client ID app, open the `Endpoints` tab. The `Oauth 2.0 auhtorization endpoint (v2)` and `Oauth 2.0 token endpoint (v2)` fields map to these. *You must use the v2 authorization endpoint. Do not use V1.* You can use either version of the token endpoint.
6. `Application ID URI`: From the **Overview** screen of the resource server, copy the `Application ID URI` field.

0 comments on commit bc9a7d7

Please sign in to comment.