Skip to content

Commit

Permalink
Rebrand of Azure Active Directory to Microsoft Entra ID (#5054)
Browse files Browse the repository at this point in the history
## What are you changing in this pull request and why?

Rebranding of Azure Active Directory to Microsoft Entra ID. Replace all
instances in user docs.

Closes #4335 

### Usages
- `Microsoft Entra service principal` gleaned from
https://learn.microsoft.com/en-us/entra/architecture/service-accounts-principal
- `Microsoft Entra password` gleaned from
https://learn.microsoft.com/en-us/entra/identity/authentication/concept-password-ban-bad-combined-policy
- `Microsoft Entra admin center` gleaned from
https://learn.microsoft.com/en-us/entra/external-id/customers/how-to-manage-admin-accounts#add-an-admin-account

### Previews
- [Connect Microsoft
Fabric](https://docs-getdbt-com-git-ly-docs-add-rebrand-dbt-labs.vercel.app/docs/cloud/connect-data-platform/connect-microsoft-fabric)
page
- [Set up Azure
DevOps](https://docs-getdbt-com-git-ly-docs-add-rebrand-dbt-labs.vercel.app/docs/cloud/git/setup-azure)
page
- [Migrating to Auth0 for
SSO](https://docs-getdbt-com-git-ly-docs-add-rebrand-dbt-labs.vercel.app/docs/cloud/manage-access/auth0-migration)
page
- [Set up SSO with Microsoft Entra
ID](https://docs-getdbt-com-git-ly-docs-add-rebrand-dbt-labs.vercel.app/docs/cloud/manage-access/set-up-sso-microsoft-entra-id)
page
- [Single sign-on (SSO)
Overview](https://docs-getdbt-com-git-ly-docs-add-rebrand-dbt-labs.vercel.app/docs/cloud/manage-access/sso-overview)
page
- [Microsoft Fabric Synapse Data Warehouse
setup](https://docs-getdbt-com-git-ly-docs-add-rebrand-dbt-labs.vercel.app/docs/core/connect-data-platform/fabric-setup)
page
- [Microsoft SQL Server
setup](https://docs-getdbt-com-git-ly-docs-add-rebrand-dbt-labs.vercel.app/docs/core/connect-data-platform/mssql-setup)
page
- [Permissions
section](https://docs-getdbt-com-git-ly-docs-add-rebrand-dbt-labs.vercel.app/reference/resource-configs/fabric-configs#permissions)
on the page Microsoft Fabric DWH configurations
- [Grants with auto provisioning
section](https://docs-getdbt-com-git-ly-docs-add-rebrand-dbt-labs.vercel.app/reference/resource-configs/mssql-configs#grants-with-auto-provisioning)
on the page Microsoft SQL Server configurations

## Checklist
- [x] 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.
- [x] 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).
- [x] Update anchor links for any page/section title changes
- [ ] Needs review from PM

Renaming pages (delete if not applicable):
- [x] Update page name in `website/sidebars.js`
- [x] Provide a unique filename for renamed pages
- [x] Add a redirect for renamed pages in `website/vercel.json`
- [x] Run link testing locally with `npm run build` to update the links
that point to old page name
  • Loading branch information
nghi-ly authored Apr 3, 2024
2 parents 6335a34 + ce0942a commit c25a791
Show file tree
Hide file tree
Showing 13 changed files with 115 additions and 103 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@ sidebar_label: "Connect Microsoft Fabric"

## Supported authentication methods
The supported authentication methods are:
- Azure Active Directory (Azure AD) service principal
- Azure AD password
- Microsoft Entra service principal
- Microsoft Entra password

SQL password (LDAP) is not supported in Microsoft Fabric Synapse Data Warehouse so you must use Azure AD. This means that to use [Microsoft Fabric](https://www.microsoft.com/en-us/microsoft-fabric) in dbt Cloud, you will need at least one Azure AD service principal to connect dbt Cloud to Fabric, ideally one service principal for each user.
SQL password (LDAP) is not supported in Microsoft Fabric Synapse Data Warehouse so you must use Microsoft Entra ID. This means that to use [Microsoft Fabric](https://www.microsoft.com/en-us/microsoft-fabric) in dbt Cloud, you will need at least one Microsoft Entra service principal to connect dbt Cloud to Fabric, ideally one service principal for each user.

### Active Directory service principal
The following are the required fields for setting up a connection with a Microsoft Fabric using Azure AD service principal authentication.
### Microsoft Entra service principal
The following are the required fields for setting up a connection with a Microsoft Fabric using Microsoft Entra service principal authentication.

| Field | Description |
| --- | --- |
Expand All @@ -25,18 +25,18 @@ The following are the required fields for setting up a connection with a Microso
| **Client secret** | The service principal's **client secret** (not the **client secret id**). |


### Active Directory password
### Microsoft Entra password

The following are the required fields for setting up a connection with a Microsoft Fabric using Azure AD password authentication.
The following are the required fields for setting up a connection with a Microsoft Fabric using Microsoft Entra password authentication.

| Field | Description |
| --- | --- |
| **Server** | The server hostname to connect to Microsoft Fabric. |
| **Port** | The server port. You can use `1433` (the default), which is the standard SQL server port number. |
| **Database** | The database name. |
| **Authentication** | Choose **Active Directory Password** from the dropdown. |
| **User** | The AD username. |
| **Password** | The AD username's password. |
| **User** | The Microsoft Entra username. |
| **Password** | The Microsoft Entra password. |

## Configuration

Expand Down
61 changes: 34 additions & 27 deletions website/docs/docs/cloud/git/setup-azure.md
Original file line number Diff line number Diff line change
@@ -1,35 +1,36 @@
---
title: "Set up Azure DevOps"
id: "setup-azure"
description: "You can set up your Azure DevOps by creating an Entra ID app and adding it to dbt Cloud."
description: "You can set up your Azure DevOps by creating a Microsoft Entra ID app and adding it to dbt Cloud."
sidebar_label: "Set up Azure DevOps"
---

<Snippet path="available-enterprise-tier-only" />

## Overview

To use our native integration with Azure DevOps in dbt Cloud, an account admin needs to set up an Microsoft Entra ID app. We recommend setting up a separate [Entra ID application than used for SSO](/docs/cloud/manage-access/set-up-sso-azure-active-directory).
To use our native integration with Azure DevOps in dbt Cloud, an account admin needs to set up an Microsoft Entra ID app. We recommend setting up a separate [Entra ID application than used for SSO](/docs/cloud/manage-access/set-up-sso-microsoft-entra-id).

1. [Register an Entra ID app](#register-an-entra-id-app).
1. [Register an Entra ID app](#register-a-microsoft-entra-id-app).
2. [Add permissions to your new app](#add-permissions-to-your-new-app).
3. [Add another redirect URI](#add-another-redirect-uri).
4. [Connect Azure DevOps to your new app](#connect-azure-devops-to-your-new-app).
5. [Add your Entra ID app to dbt Cloud](#add-your-azure-ad-app-to-dbt-cloud).

Once the Entra ID app is added to dbt Cloud, an account admin must also [connect a service user](#connecting-a-service-user) via OAuth, which will be used to power headless actions in dbt Cloud such as deployment runs and CI.
Once the Microsoft Entra ID app is added to dbt Cloud, an account admin must also [connect a service user](#connecting-a-service-user) via OAuth, which will be used to power headless actions in dbt Cloud such as deployment runs and CI.

Once the Entra ID app is added to dbt Cloud and the service user is connected, then dbt Cloud developers can personally authenticate in dbt Cloud from Azure DevOps. For more on this, see [Authenticate with Azure DevOps](/docs/cloud/git/authenticate-azure).

Once the Microsoft Entra ID app is added to dbt Cloud and the service user is connected, then dbt Cloud developers can personally authenticate in dbt Cloud from Azure DevOps. For more on this, see [Authenticate with Azure DevOps](/docs/cloud/git/authenticate-azure).

The following personas are required to complete the steps on this page:
- Entra ID admin
- Microsoft Entra ID admin
- Azure DevOps admin
- dbt Cloud account admin
- Azure admin (if your Entra ID and Azure DevOps environments are not connected)

## Register an Entra ID app
## Register a Microsoft Entra ID app

An Entra ID admin needs to perform the following steps:
A Microsoft Entra ID admin needs to perform the following steps:

1. Sign into your Azure portal and click **Microsoft Entra ID**.
2. Select **App registrations** in the left panel.
Expand All @@ -44,7 +45,8 @@ Many customers ask why they need to select Multitenant instead of Single tenant,

Here's what your app should look like before registering it:

<Lightbox src="/img/docs/dbt-cloud/connecting-azure-devops/AD app.png" title="Registering an Entra ID app"/>
<Lightbox src="/img/docs/dbt-cloud/connecting-azure-devops/AD app.png" title="Registering a Microsoft Entra ID app"/>


## Add permissions to your new app

Expand All @@ -60,59 +62,62 @@ An Entra ID admin needs to provide your new app access to Azure DevOps:

## Add another redirect URI

An Entra ID admin needs to add another redirect URI to your Entra ID application. This redirect URI will be used to authenticate the service user for headless actions in deployment environments.
A Microsoft Entra ID admin needs to add another redirect URI to your Entra ID application. This redirect URI will be used to authenticate the service user for headless actions in deployment environments.

1. Navigate to your Microsoft Entra ID application.

1. Navigate to your Entra ID application.
2. Select the link next to **Redirect URIs**
3. Click **Add URI** and add the URI, replacing `YOUR_ACCESS_URL` with the [appropriate Access URL](/docs/cloud/about-cloud/access-regions-ip-addresses) for your region and plan:
`https://YOUR_ACCESS_URL/complete/azure_active_directory_service_user`
`https://YOUR_ACCESS_URL/complete/microsoft_entra_id_service_user`
4. Click **Save**.

<Lightbox src="/img/docs/dbt-cloud/connecting-azure-devops/redirect-uri.gif" title="Adding the Service User redirect URI"/>

## Create a client secret

An Entra ID admin needs to complete the following steps:
A Microsoft Entra ID admin needs to complete the following steps:

1. Navigate to your Entra ID application.
1. Navigate to your Microsoft Entra ID application.
2. Select **Certificates and Secrets** from the left navigation panel.
3. Select **Client secrets** and click **New client secret**
4. Give the secret a description and select the expiration time. Click **Add**.
5. Copy the **Value** field and securely share it with the dbt Cloud account admin who will complete the setup.

## Connect Azure DevOps to your new app

An Azure admin will need one of the following permissions in both the Entra ID and Azure DevOps environments:
An Azure admin will need one of the following permissions in both the Microsoft Entra ID and Azure DevOps environments:
- Azure Service Administrator
- Azure Co-administrator

If your Azure DevOps account is connected to Entra ID, then you can proceed to [Connecting a service user](#connecting-a-service-user). However, if you're just getting set up, connect Azure DevOps to the Entra ID app you just created:
If your Azure DevOps account is connected to Entra ID, then you can proceed to [Connecting a service user](#connecting-a-service-user). However, if you're just getting set up, connect Azure DevOps to the Microsoft Entra ID app you just created:

1. From your Azure DevOps account, select **Organization settings** in the bottom left.
2. Navigate to Microsoft Entra ID.
3. Click **Connect directory**.
4. Select the directory you want to connect.
5. Click **Connect**.

<Lightbox src="/img/docs/dbt-cloud/connecting-azure-devops/connect AD to Azure DevOps.gif" title="Connecting Azure DevOps and Entra ID"/>
<Lightbox src="/img/docs/dbt-cloud/connecting-azure-devops/connect AD to Azure DevOps.gif" title="Connecting Azure DevOps and Microsoft Entra ID"/>

## Add your Entra ID app to dbt Cloud
## Add your Microsoft Entra ID app to dbt Cloud

A dbt Cloud account admin needs to perform the following steps.

Once you connect your Entra ID app and Azure DevOps, you need to provide dbt Cloud information about the app:
Once you connect your Microsoft Entra ID app and Azure DevOps, you need to provide dbt Cloud information about the app:


1. Navigate to your account settings in dbt Cloud.
2. Select **Integrations**.
3. Scroll to the Azure DevOps section.
4. Complete the form:
- **Azure DevOps Organization:** Must match the name of your Azure DevOps organization exactly. Do not include the `dev.azure.com/` prefix in this field. ✅ Use `my-devops-org` ❌ Avoid `dev.azure.com/my-devops-org`
- **Application (client) ID:** Found in the Entra ID app.
- **Client Secrets:** Copy the **Value** field in the Entra ID app client secrets and paste it in the **Client Secret** field in dbt Cloud. Entra ID admins are responsible for the Entra ID app secret expiration and dbt Admins should not the expiration date for rotation.
- **Directory(tenant) ID:** Found in the Entra ID app.
<Lightbox src="/img/docs/dbt-cloud/connecting-azure-devops/AzureDevopsAppdbtCloud.gif" title="Adding an Entra ID app to dbt Cloud"/>
- **Application (client) ID:** Found in the Microsoft Entra ID app.
- **Client Secrets:** Copy the **Value** field in the Microsoft Entra ID app client secrets and paste it in the **Client Secret** field in dbt Cloud. Entra ID admins are responsible for the Entra ID app secret expiration and dbt Admins should not the expiration date for rotation.
- **Directory(tenant) ID:** Found in the Microsoft Entra ID app.
<Lightbox src="/img/docs/dbt-cloud/connecting-azure-devops/AzureDevopsAppdbtCloud.gif" title="Adding a Microsoft Entra ID app to dbt Cloud"/>

Your Microsoft Entra ID app should now be added to your dbt Cloud Account. People on your team who want to develop in the dbt Cloud IDE or dbt Cloud CLI can now personally [authorize Azure DevOps from their profiles](/docs/cloud/git/authenticate-azure).

Your Entra ID app should now be added to your dbt Cloud Account. People on your team who want to develop in the dbt Cloud IDE or dbt Cloud CLI can now personally [authorize Azure DevOps from their profiles](/docs/cloud/git/authenticate-azure).

## Connect a service user

Expand Down Expand Up @@ -150,13 +155,14 @@ The service user's permissions will also power which repositories a team can sel

While it's common to enforce multi-factor authentication (MFA) for normal user accounts, service user authentication must not need an extra factor. If you enable a second factor for the service user, this can interrupt production runs and cause a failure to clone the repository. In order for the OAuth access token to work, the best practice is to remove any more burden of proof of identity for service users.

As a result, MFA must be explicity disabled in the Office 365 or Entra ID administration panel for the service user. Just having it "un-connected" will not be sufficient, as dbt Cloud will be prompted to set up MFA instead of allowing the credentials to be used as intended.
As a result, MFA must be explicity disabled in the Office 365 or Microsoft Entra ID administration panel for the service user. Just having it "un-connected" will not be sufficient, as dbt Cloud will be prompted to set up MFA instead of allowing the credentials to be used as intended.


**To disable MFA for a single user using the Office 365 Administration console:**

- Go to Microsoft 365 admin center -> Users -> Active users -> Select the user -> Manage multifactor authentication -> Select the user -> Disable multi-factor authentication.

**To use the Entra ID interface:**
**To use the Microsoft Entra ID interface:**

Note, this procedure involves disabling Security Defaults in your Entra ID environment.

Expand Down Expand Up @@ -360,8 +366,9 @@ You must connect your service user before setting up a dbt Cloud project, as the
A dbt Cloud account admin with access to the service user's Azure DevOps account must complete the following to connect the service user:
1. Sign in to the service user's Azure DevOps account.
2. In dbt Cloud, click **Link Azure Service User**.
3. You will be directed to Azure DevOps and must accept the Entra ID app's permissions.
3. You will be directed to Azure DevOps and must accept the Microsoft Entra ID app's permissions.
4. Finally, you will be redirected to dbt Cloud, and the service user will be connected.

<Lightbox src="/img/docs/dbt-cloud/connecting-azure-devops/azure-service-user.png" title="Connecting an Azure Service User"/>

Once connected, dbt Cloud displays the email address of the service user so you know which user's permissions are enabling headless actions in deployment environments. To change which account is connected, disconnect the profile in dbt Cloud, sign into the alternative Azure DevOps service account, and re-link the account in dbt Cloud.
Expand Down
2 changes: 1 addition & 1 deletion website/docs/docs/cloud/manage-access/about-access.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ of a group inherit any permissions applied to the group itself.
Users can be added to a dbt Cloud group based on their group memberships in the
configured [Identity Provider](sso-overview) for the account. In this way, dbt
Cloud administrators can manage access to dbt Cloud resources via identity
management software like Azure AD, Okta, or GSuite. See _SSO Mappings_ below for
management software like Microsoft Entra ID (formerly Azure AD), Okta, or GSuite. See _SSO Mappings_ below for
more information.

You can view the groups in your account or create new groups from the **Groups & Licenses**
Expand Down
10 changes: 5 additions & 5 deletions website/docs/docs/cloud/manage-access/auth0-migration.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ description: "Required actions for migrating to Auth0 for SSO services on dbt Cl

dbt Labs is partnering with Auth0 to bring enhanced features to dbt Cloud's single sign-on (SSO) capabilities. Auth0 is an identity and access management (IAM) platform with advanced security features, and it will be leveraged by dbt Cloud. These changes will require some action from customers with SSO configured in dbt Cloud today, and this guide will outline the necessary changes for each environment.

If you have not yet configured SSO in dbt Cloud, refer instead to our setup guides for [SAML](/docs/cloud/manage-access/set-up-sso-saml-2.0), [Okta](/docs/cloud/manage-access/set-up-sso-okta), [Google Workspace](/docs/cloud/manage-access/set-up-sso-google-workspace), or [Azure Active Directory](/docs/cloud/manage-access/set-up-sso-azure-active-directory) single sign-on services.
If you have not yet configured SSO in dbt Cloud, refer instead to our setup guides for [SAML](/docs/cloud/manage-access/set-up-sso-saml-2.0), [Okta](/docs/cloud/manage-access/set-up-sso-okta), [Google Workspace](/docs/cloud/manage-access/set-up-sso-google-workspace), or [Microsoft Entra ID (formerly Azure AD)](/docs/cloud/manage-access/set-up-sso-microsoft-entra-id) single sign-on services.

## Auth0 Multi-tenant URIs

Expand Down Expand Up @@ -90,9 +90,9 @@ You must complete the domain authorization before you toggle `Enable New SSO Aut

<Lightbox src="/img/docs/dbt-cloud/access-control/google-enable.png" title="Enable new SSO for Google Workspace"/>

## Azure Active Directory
## Microsoft Entra ID

Azure Active Directory admins will need to make a slight adjustment to the existing authentication app in the Azure AD portal. This migration does not require that the entire app be deleted or recreated; you can edit the existing app. Start by opening the Azure portal and navigating to the Active Directory overview.
Microsoft Entra ID admins will need to make a slight adjustment to the existing authentication app in the Azure portal. This migration does not require that the entire app be deleted or recreated; you can edit the existing app. Start by opening the Azure portal and navigating to the Microsoft Entra ID overview.

Below are steps to update. You must complete all of them to ensure uninterrupted access to dbt Cloud and you should coordinate with your identity provider admin when making these changes.

Expand All @@ -108,12 +108,12 @@ Below are steps to update. You must complete all of them to ensure uninterrupted

<Lightbox src="/img/docs/dbt-cloud/access-control/redirect-URI.png" title="Enter new redirect URI"/>

4. Navigate to the dbt Cloud environment and open the **Account Settings**. Click the **Single Sign-on** option from the left side menu and click the **Edit** option from the right side of the SSO pane. The **domain** field is the domain your organization uses to login to Azure AD. Toggle the **Enable New SSO Authentication** option and **Save**. _Once this option is enabled, it cannot be undone._
4. Navigate to the dbt Cloud environment and open the **Account Settings**. Click the **Single Sign-on** option from the left side menu and click the **Edit** option from the right side of the SSO pane. The **domain** field is the domain your organization uses to login to Microsoft Entra ID. Toggle the **Enable New SSO Authentication** option and **Save**. _Once this option is enabled, it cannot be undone._

:::warning Domain authorization

You must complete the domain authorization before you toggle `Enable New SSO Authentication`, or the migration will not complete successfully.

:::

<Lightbox src="/img/docs/dbt-cloud/access-control/azure-enable.png" title="Enable new SSO for Azure AD"/>
<Lightbox src="/img/docs/dbt-cloud/access-control/azure-enable.png" title="Enable new SSO"/>
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ of a group inherit any permissions applied to the group itself.
Users can be added to a dbt Cloud group based on their group memberships in the
configured [Identity Provider](sso-overview) for the account. In this way, dbt
Cloud administrators can manage access to dbt Cloud resources via identity
management software like Azure AD, Okta, or GSuite. See _SSO Mappings_ below for
management software like Microsoft Entra ID (formerly Azure AD), Okta, or GSuite. See _SSO Mappings_ below for
more information.

You can view the groups in your account or create new groups from the **Team > Groups**
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
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"
id: "set-up-sso-microsoft-entra-id"
sidebar_label: "Set up SSO with Microsoft Entra ID"
---

Expand All @@ -19,7 +19,7 @@ Currently supported features include:

## Configuration

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.
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 a Microsoft Entra ID Application.

### Creating an application

Expand Down
Loading

0 comments on commit c25a791

Please sign in to comment.