Merge branch 'current' into ly-docs-preview-adv-ci

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,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**.
@@ -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
 
 <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 create two different `apps` in the Azure portal &mdash: A resource server and a client app.
+
+:::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.
+
+:::
+
+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**.
+    1. Give the app a name. 
+    2. Ensure **Supported account types** are set to “Accounts in this organizational directory only (`Org name` - Single Tenant).” 
+    3. Click **Register** and you will be taken to the apps overview.
+2. From the app overview page, click **Expose an API** from the left menu.
+3. Click **Add** next to **Application ID URI**. The field will automatically populate. Click **Save**. 
+4. Record the `value` field as it will be used in a future step. *This is only displayed once. Be sure to record it immediately. It will be hidden when you leave the page and come back.* 
+5. 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**.
+    1. Give the app a name that uniquely identifies it as the client app.
+    2. Ensure **Supported account types** are set to “Accounts in this organizational directory only (`Org name` - Single Tenant).” 
+    3. Set the **Redirect URI** to **Web** and copy/paste the **Redirect URI** from dbt Cloud into the field.
+    4. Click **Register**.
+2. From the app overview page, click **API permissions** from the left menu, and click **Add permission**.
+3. From the pop-out screen, click **APIs my organization uses**, search for the resource server name from the previous steps, and click it.
+4. Ensure the box for the **Permissions** `session:role-any` is enabled and click **Add permissions**.
+5. Click **Grant admin consent** and from the popup modal click **Yes**.
+6. From the left menu, click **Certificates and secrets** and cllick **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 essential to document the expiration date so that the secret can be refreshed before the expiration or user authorization will fail. 
+7. Record the `value` for use in a future step and record it immediately. 
+**Note**: This value will not be displayed again once you navigate away from this screen.
+
+### 3. Snowflake configuration
+
+You'll be switching 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';
+```
+On 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 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. 
+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 created; if you return later, it will be hidden, and you must recreate the secret. 
+4. `Client ID`: Copy the’ Application (client) ID’ on the overview page for the client ID app.
+5. `Authorization URL` and `Token URL`: From the client ID app, open the `Endpoints` tab. The `Oauth 2.0 authorization endpoint (v2)` and `Oauth 2.0 token endpoint (v2)` fields map to these. *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.

website/docs/docs/collaborate/column-level-lineage.md

@@ -9,6 +9,10 @@ CLL is available to dbt Cloud Enterprise accounts that can use Explorer.
 
 <Lightbox src="/img/docs/collaborate/dbt-explorer/example-overview-cll.png" width="95%" title="Overview of column level lineage"/>
 
+import ExplorerCourse from '/snippets/_explorer-course-link.md';
+
+<ExplorerCourse />
+
 ## Access the column-level lineage
 
 There is no additional setup required for CLL if your account is on an Enterprise plan that can use Explorer. You can access the CLL by expanding the column card in the **Columns** tab of an Explorer [resource details page](/docs/collaborate/explore-projects#view-resource-details) for a model, source, or snapshot.

website/docs/docs/collaborate/explore-multiple-projects.md

@@ -6,6 +6,10 @@ description: "Learn about project-level lineage in dbt Explorer and its uses."
 
 View all the projects and public models in your account (where public models are defined) and gain a better understanding of your cross-project resources and how they're used.
 
+import ExplorerCourse from '/snippets/_explorer-course-link.md';
+
+<ExplorerCourse />
+
 The resource-level lineage graph for a project displays the cross-project relationships in the DAG, with a **PRJ** icon indicating whether or not it's a project resource. That icon is located to the left side of the node name.
 
 To view the project-level lineage graph, click the **View lineage** icon in the upper right corner from the main overview page:

website/docs/docs/collaborate/explore-projects.md

@@ -8,6 +8,10 @@ pagination_prev: null
 
 With dbt Explorer, you can view your project's [resources](/docs/build/projects) (such as models, tests, and metrics) and their <Term id="data-lineage">lineage</Term> to gain a better understanding of its latest production state. Navigate and manage your projects within dbt Cloud to help you and other data developers, analysts, and consumers discover and leverage your dbt resources.
 
+import ExplorerCourse from '/snippets/_explorer-course-link.md';
+
+<ExplorerCourse />
+
 ## Prerequisites
 
 - You have a dbt Cloud account on the [Team or Enterprise plan](https://www.getdbt.com/pricing/).

website/docs/docs/collaborate/model-performance.md

@@ -8,6 +8,10 @@ dbt Explorer provides metadata on dbt Cloud runs for in-depth model performance
 
 <Lightbox src="/img/docs/collaborate/dbt-explorer/explorer-model-performance.gif" width="100%" title="Overview of Performance page navigation."/>
 
+import ExplorerCourse from '/snippets/_explorer-course-link.md';
+
+<ExplorerCourse />
+
 ## The Performance overview page 
 
 You can pinpoint areas for performance enhancement by using the Performance overview page. This page presents a comprehensive analysis across all project models and displays the longest-running models, those most frequently executed, and the ones with the highest failure rates during runs/tests. Data can be segmented by environment and job type which can offer insights into:

website/docs/docs/collaborate/project-recommendations.md

@@ -10,6 +10,10 @@ dbt Explorer provides recommendations about your project from the `dbt_project_e
 - These recommendations provide insight into how you can create a better-documented, better-tested, and better-built dbt project, creating more trust and less confusion.
 - For a seamless and consistent experience, recommendations use `dbt_project_evaluator`'s pre-defined settings and don't import customizations applied to your package or project.
 
+import ExplorerCourse from '/snippets/_explorer-course-link.md';
+
+<ExplorerCourse />
+
 ## Recommendations page
 The Recommendations overview page includes two top-level metrics measuring the test and documentation coverage of the models in your project. 
 

website/snippets/_explorer-course-link.md

@@ -0,0 +1,3 @@
+:::info  On-demand learning
+If you enjoy video courses, check out our [dbt Explorer on-demand course](https://learn.getdbt.com/learn/course/dbt-explorer) and learn how to best explore your dbt project(s)!
+:::