diff --git a/website/docs/docs/cloud/manage-access/set-up-sso-azure-active-directory.md b/website/docs/docs/cloud/manage-access/set-up-sso-azure-active-directory.md index 28d20b526db..28684daf1d4 100644 --- a/website/docs/docs/cloud/manage-access/set-up-sso-azure-active-directory.md +++ b/website/docs/docs/cloud/manage-access/set-up-sso-azure-active-directory.md @@ -1,16 +1,16 @@ --- -title: "Set up SSO with Azure Active Directory" -description: "Learn how dbt Cloud administrators can use Azure Active Directory to control access in a dbt Cloud account." +title: "Set up SSO with Microsoft Entra ID (formerly Azure AD)" +description: "Learn how dbt Cloud administrators can use Microsoft Entra ID to control access in a dbt Cloud account." id: "set-up-sso-azure-active-directory" -sidebar_label: "Set up SSO with Azure AD" +sidebar_label: "Set up SSO with Microsoft Entra ID" --- import SetUpPages from '/snippets/_sso-docs-mt-available.md'; -dbt Cloud Enterprise supports single-sign on via Azure Active Directory (Azure AD). -You will need permissions to create and manage a new Azure AD application. +dbt Cloud Enterprise supports single-sign on via Microsoft Entra ID (formerly Azure AD). +You will need permissions to create and manage a new Entra ID application. Currently supported features include: * IdP-initiated SSO @@ -19,83 +19,71 @@ Currently supported features include: ## Configuration -dbt Cloud supports both single tenant and multi-tenant Azure Active Directory SSO -Connections. For most Enterprise purposes, you will want to use the single -tenant flow when creating an Azure AD Application. +dbt Cloud supports both single tenant and multi-tenant Microsoft Entra ID (formerly Azure AD) SSO Connections. For most Enterprise purposes, you will want to use the single-tenant flow when creating an Azure AD Application. ### Creating an application -Log into the Azure portal for your organization. Using the **Azure Active Directory** page, you will -need to select the appropriate directory and then register a new application. +Log into the Azure portal for your organization. Using the [**Microsoft Entra ID**](https://portal.azure.com/#home) page, you will need to select the appropriate directory and then register a new application. -1. Under **Manage**, select **App registrations** -2. Click **+ New Registration** to begin creating a new application -3. Supply configurations for the **Name** and **Supported account types** - fields as shown in the below. +1. Under **Manage**, select **App registrations**. +2. Click **+ New Registration** to begin creating a new application registration. + + + +3. Supply configurations for the **Name** and **Supported account types** fields as shown in the following table: | Field | Value | | ----- | ----- | | **Name** | dbt Cloud | | **Supported account types** | Accounts in this organizational directory only _(single tenant)_ | -4. Configure the **Redirect URI**. The table below shows the appropriate - Redirect URI values for single-tenant and multi-tenant deployments. For most - enterprise use-cases, you will want to use the single-tenant Redirect URI. Replace `YOUR_AUTH0_URI` with the [appropriate Auth0 URI](/docs/cloud/manage-access/sso-overview#auth0-multi-tenant-uris) for your region and plan. - +4. Configure the **Redirect URI**. The table below shows the appropriate Redirect URI values for single-tenant and multi-tenant deployments. For most enterprise use-cases, you will want to use the single-tenant Redirect URI. Replace `YOUR_AUTH0_URI` with the [appropriate Auth0 URI](/docs/cloud/manage-access/sso-overview#auth0-multi-tenant-uris) for your region and plan. | Application Type | Redirect URI | | ----- | ----- | -| Single-Tenant _(recommended)_ | `https://YOUR_AUTH0_URI/login/callback` | -| Multi-Tenant | `https://YOUR_AUTH0_URI/login/callback` | - - -5. Save the App registration to continue setting up Azure AD SSO +| Single-tenant _(recommended)_ | `https://YOUR_AUTH0_URI/login/callback` | +| Multi-tenant | `https://YOUR_AUTH0_URI/login/callback` | - - + +5. Save the App registration to continue setting up Microsoft Entra ID SSO -**Configuration with the new Azure AD interface (optional)** +:::info Configuration with the new Microsoft Entra ID interface (optional) -Depending on your Azure AD settings, your App Registration page might look -different than the screenshots shown above. If you are _not_ prompted to -configure a Redirect URI on the **New Registration** page, then follow steps 6 -and 7 below after creating your App Registration. If you were able to set up -the Redirect URI in the steps above, then skip ahead to step 8. +Depending on your Microsoft Entra ID settings, your App Registration page might look different than the screenshots shown earlier. If you are _not_ prompted to configure a Redirect URI on the **New Registration** page, then follow steps 6 - 7 below after creating your App Registration. If you were able to set up the Redirect URI in the steps above, then skip ahead to [step 8](#adding-users-to-an-enterprise-application). +::: -6. After registering the new application without specifying a Redirect URI, - navigate to the **Authentication** tab for the new application. +6. After registering the new application without specifying a Redirect URI, click on **App registration** and then navigate to the **Authentication** tab for the new application. -7. Click **+ Add platform** and enter a Redirect URI for your application. See - step 4 above for more information on the correct Redirect URI value for your - dbt Cloud application. +7. Click **+ Add platform** and enter a Redirect URI for your application. See step 4 above for more information on the correct Redirect URI value for your dbt Cloud application. - + ### Azure <-> dbt Cloud User and Group mapping The Azure users and groups you will create in the following steps are mapped to groups created in dbt Cloud based on the group name. Reference the docs on [enterprise permissions](enterprise-permissions) for additional information on how users, groups, and permission sets are configured in dbt Cloud. -### Adding Users to an Enterprise Application +### Adding users to an Enterprise application Once you've registered the application, the next step is to assign users to it. Add the users you want to be viewable to dbt with the following steps: -8. From the **Default Directory** click **Enterprise Applications** +8. Navigate back to the [**Default Directory**](https://portal.azure.com/#home) (or **Home**) and click **Enterprise Applications** 9. Click the name of the application you created earlier 10. Click **Assign Users and Groups** 11. Click **Add User/Group** 12. Assign additional users and groups as-needed - + :::info User assignment required? -Under **Properties** check the toggle setting for **User assignment required?** and confirm it aligns to your requirements. Most customers will want this toggled to **Yes** so that only users/groups explicitly assigned to dbt Cloud will be able to sign in. If this setting is toggled to **No** any user will be able to access the application if they have a direct link to the application per [Azure AD Documentation](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/assign-user-or-group-access-portal#configure-an-application-to-require-user-assignment) +Under **Properties** check the toggle setting for **User assignment required?** and confirm it aligns to your requirements. Most customers will want this toggled to **Yes** so that only users/groups explicitly assigned to dbt Cloud will be able to sign in. If this setting is toggled to **No** any user will be able to access the application if they have a direct link to the application per [Microsoft Entra ID Documentation](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/assign-user-or-group-access-portal#configure-an-application-to-require-user-assignment) ::: ### Configuring permissions -13. Under **Manage**, click **API Permissions** -14. Click **+Add a permission** and add the permissions shown below +13. Navigate back to [**Default Directory**](https://portal.azure.com/#home) (or **Home**) and then **App registration**. +14. Select your application and then select **API Permissions** +15. Click **+Add a permission** and add the permissions shown below | API Name | Type | Permission | | -------- | ---- | ---------- | @@ -103,33 +91,28 @@ Under **Properties** check the toggle setting for **User assignment required?** | Microsoft Graph | Delegated | `Directory.Read.All` | | Microsoft Graph | Delegated | `User.Read` | -15. Save these permissions, then click **Grant admin consent** to grant admin - consent for this directory on behalf of all of your users. +16. Save these permissions, then click **Grant admin consent** to grant admin consent for this directory on behalf of all of your users. - + ### Creating a client secret -16. Under **Manage**, click **Certificates & secrets** -17. Click **+New client secret** -18. Name the client secret "dbt Cloud" (or similar) to identify the secret -19. Select **730 days (24 months)** as the expiration value for this secret (recommended) -20. Click **Add** to finish creating the client secret value (not the client secret ID) -21. Record the generated client secret somewhere safe. Later in the setup process, - we'll use this client secret in dbt Cloud to finish configuring the - integration. +17. Under **Manage**, click **Certificates & secrets** +18. Click **+New client secret** +19. Name the client secret "dbt Cloud" (or similar) to identify the secret +20. Select **730 days (24 months)** as the expiration value for this secret (recommended) +21. Click **Add** to finish creating the client secret value (not the client secret ID) +22. Record the generated client secret somewhere safe. Later in the setup process, we'll use this client secret in dbt Cloud to finish configuring the integration. - - + + ### Collect client credentials -22. Navigate to the **Overview** page for the app registration -23. Note the **Application (client) ID** and **Directory (tenant) ID** shown in - this form and record them along with your client secret. We'll use these keys - in the steps below to finish configuring the integration in dbt Cloud. +23. Navigate to the **Overview** page for the app registration +24. Note the **Application (client) ID** and **Directory (tenant) ID** shown in this form and record them along with your client secret. We'll use these keys in the steps below to finish configuring the integration in dbt Cloud. - + ## Configuring dbt Cloud @@ -137,36 +120,30 @@ To complete setup, follow the steps below in the dbt Cloud application. ### Supplying credentials -24. Click the gear icon at the top right and select **Profile settings**. To the left, select **Single Sign On** under **Account Settings**. -25. Click the **Edit** button and supply the following SSO details: +25. Click the gear icon at the top right and select **Profile settings**. To the left, select **Single Sign On** under **Account Settings**. +26. Click the **Edit** button and supply the following SSO details: | Field | Value | | ----- | ----- | -| **Log in with** | Azure AD Single Tenant | +| **Log in with** | Microsoft Entra ID Single Tenant | | **Client ID** | Paste the **Application (client) ID** recorded in the steps above | -| **Client Secret** | Paste the **Client Secret** (remember to use the Secret Value instead of the Secret ID) recorded in the steps above;
**Note:** When the client secret expires, an Azure AD admin will have to generate a new one to be pasted into dbt Cloud for uninterrupted application access. | +| **Client Secret** | Paste the **Client Secret** (remember to use the Secret Value instead of the Secret ID) recorded in the steps above;
**Note:** When the client secret expires, an Entra ID admin will have to generate a new one to be pasted into dbt Cloud for uninterrupted application access. | | **Tenant ID** | Paste the **Directory (tenant ID)** recorded in the steps above | | **Domain** | Enter the domain name for your Azure directory (such as `fishtownanalytics.com`). Only use the primary domain; this won't block access for other domains. | | **Slug** | Enter your desired login slug. Users will be able to log into dbt Cloud by navigating to `https://YOUR_ACCESS_URL/enterprise-login/LOGIN-SLUG`, replacing `YOUR_ACCESS_URL` with the [appropriate Access URL](/docs/cloud/manage-access/sso-overview#auth0-multi-tenant-uris) for your region and plan. Login slugs must be unique across all dbt Cloud accounts, so pick a slug that uniquely identifies your company. | + - - -26. Click **Save** to complete setup for the Azure AD SSO integration. From - here, you can navigate to the login URL generated for your account's _slug_ to - test logging in with Azure AD. +1. Click **Save** to complete setup for the Microsoft Entra ID SSO integration. From here, you can navigate to the login URL generated for your account's _slug_ to test logging in with Entra ID. - - - ## Setting up RBAC -Now you have completed setting up SSO with Azure AD, the next steps will be to set up +Now you have completed setting up SSO with Entra ID, the next steps will be to set up [RBAC groups](/docs/cloud/manage-access/enterprise-permissions) to complete your access control configuration. ## Troubleshooting Tips Ensure that the domain name under which user accounts exist in Azure matches the domain you supplied in [Supplying credentials](#supplying-credentials) when you configured SSO. - + diff --git a/website/docs/docs/cloud/manage-access/set-up-sso-saml-2.0.md b/website/docs/docs/cloud/manage-access/set-up-sso-saml-2.0.md index ba925fa2c24..7083e7ac5f8 100644 --- a/website/docs/docs/cloud/manage-access/set-up-sso-saml-2.0.md +++ b/website/docs/docs/cloud/manage-access/set-up-sso-saml-2.0.md @@ -164,7 +164,6 @@ dbt Cloud expects by using the Attribute Statements and Group Attribute Statemen | -------- | ----------- | ------------- | ----- | ------------------------------------- | | `groups` | Unspecified | Matches regex | `.*` | _The groups that the user belongs to_ | - You can instead use a more restrictive Group Attribute Statement than the example shown in the previous steps. For example, if all of your dbt Cloud groups start with `DBT_CLOUD_`, you may use a filter like `Starts With: DBT_CLOUD_`. **Okta @@ -282,11 +281,11 @@ Expected **Attributes**: After creating the Google application, follow the instructions in the [dbt Cloud Setup](#dbt-cloud-setup) -## Azure integration +## Microsoft Entra ID (formerly Azure AD) integration -If you're using Azure Active Directory (Azure AD), the instructions below will help you configure it as your identity provider. +If you're using Microsoft Entra ID (formerly Azure AD), the instructions below will help you configure it as your identity provider. -### Create Azure AD Enterprise application +### Create a Microsoft Entra ID Enterprise application @@ -297,7 +296,7 @@ Login slugs must be unique across all dbt Cloud accounts, so pick a slug that un Follow these steps to set up single sign-on (SSO) with dbt Cloud: 1. Log into your Azure account. -2. In the Azure AD portal, select **Enterprise applications** and click **+ New application**. +2. In the Entra ID portal, select **Enterprise applications** and click **+ New application**. 3. Select **Create your own application**. 4. Name the application "dbt Cloud" or another descriptive name. 5. Select **Integrate any other application you don't find in the gallery (Non-gallery)** as the application type. @@ -306,8 +305,15 @@ Follow these steps to set up single sign-on (SSO) with dbt Cloud: 8. Click the application you just created. 9. Select **Single sign-on** under Manage in the left navigation. 10. Click **Set up single sign on** under Getting Started. -11. Click **SAML** in "Select a single sign-on method" section. -12. Click **Edit** in the Basic SAML Configuration section. + + +11. Click **SAML** in "Select a single sign-on method" section. + + +12. Click **Edit** in the Basic SAML Configuration section. + + + 13. Use the following table to complete the required fields and connect to dbt: | Field | Value | @@ -315,7 +321,8 @@ Follow these steps to set up single sign-on (SSO) with dbt Cloud: | **Identifier (Entity ID)** | Use `urn:auth0::`. | | **Reply URL (Assertion Consumer Service URL)** | Use `https://YOUR_AUTH0_URI/login/callback?connection=`. | | **Relay State** | `` | -14. Click **Save** at the top of the form. + +14. Click **Save** at the top of the form. ### Creating SAML settings @@ -337,13 +344,12 @@ From the Set up Single Sign-On with SAML page: 7. Set **Source attribute** to **Group ID**. 8. Under **Advanced options**, check **Customize the name of the group claim** and specify **Name** to **groups**. -**Note:** Keep in mind that the Group ID in Azure AD maps to that group's GUID. It should be specified in lowercase for the mappings to work as expected. The Source Attribute field alternatively can be set to a different value of your preference. +**Note:** Keep in mind that the Group ID in Entra ID maps to that group's GUID. It should be specified in lowercase for the mappings to work as expected. The Source Attribute field alternatively can be set to a different value of your preference. ### Finish setup 9. After creating the Azure application, follow the instructions in the [dbt Cloud Setup](#dbt-cloud-setup) section to complete the integration. - ## OneLogin integration Use this section if you are configuring OneLogin as your identity provider. diff --git a/website/static/img/docs/dbt-cloud/access-control/basic-saml.jpg b/website/static/img/docs/dbt-cloud/access-control/basic-saml.jpg new file mode 100644 index 00000000000..2707fb5a378 Binary files /dev/null and b/website/static/img/docs/dbt-cloud/access-control/basic-saml.jpg differ diff --git a/website/static/img/docs/dbt-cloud/access-control/saml.jpg b/website/static/img/docs/dbt-cloud/access-control/saml.jpg new file mode 100644 index 00000000000..b88eec2cd2b Binary files /dev/null and b/website/static/img/docs/dbt-cloud/access-control/saml.jpg differ diff --git a/website/static/img/docs/dbt-cloud/access-control/single-sign-on-overview.jpg b/website/static/img/docs/dbt-cloud/access-control/single-sign-on-overview.jpg new file mode 100644 index 00000000000..95e40aaa8a0 Binary files /dev/null and b/website/static/img/docs/dbt-cloud/access-control/single-sign-on-overview.jpg differ