diff --git a/website/docs/docs/cloud/manage-access/external-oauth.md b/website/docs/docs/cloud/manage-access/external-oauth.md index c04c50354b7..56159c4dcff 100644 --- a/website/docs/docs/cloud/manage-access/external-oauth.md +++ b/website/docs/docs/cloud/manage-access/external-oauth.md @@ -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 --- @@ -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. ::: @@ -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. @@ -53,7 +55,9 @@ 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** @@ -61,7 +65,7 @@ The `external_oauth_token_user_mapping_claim` and `external_oauth_snowflake_u -## 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**. @@ -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**. @@ -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: @@ -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. @@ -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. @@ -156,4 +160,95 @@ Adjust the other settings as needed to meet your organizations configurations in -4. **Save** the connection and you have now configured External Oauth with Okta and Snowflake! \ No newline at end of file +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 — 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 + type = external_oauth + enabled = true + external_oauth_type = azure + external_oauth_issuer = '' + external_oauth_jws_keys_url = '' + external_oauth_audience_list = ('') + 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. +