Перейти к основному содержимому

Настройка Azure DevOps с использованием сервисного пользователя

Обзор сервисного пользователя​

important

Сервисные пользователи больше не являются рекомендуемым методом аутентификации, и dbt постепенно внедряет новый вариант — service principal Microsoft Entra ID. Как только эта опция станет доступна в настройках вашего аккаунта, вам следует запланировать миграцию с сервисного пользователя на service principal. Service principal — это рекомендуемый Microsoft тип сервисной учетной записи для аутентификации приложений.

Чтобы использовать нативную интеграцию с Azure DevOps в dbt, администратор аккаунта должен настроить приложение Microsoft Entra ID. Мы рекомендуем создавать отдельное приложение Entra ID, отличное от используемого для SSO.

  1. Зарегистрировать приложение Entra ID.
  2. Добавить разрешения для нового приложения.
  3. Добавить дополнительный redirect URI.
  4. Подключить Azure DevOps к новому приложению.
  5. Добавить приложение Entra ID в dbt.

После добавления приложения Microsoft Entra ID в dbt, администратор аккаунта также должен подключить сервисного пользователя через OAuth. Этот пользователь будет использоваться для headless‑действий в dbt, таких как deployment‑запуски и CI.

После того как приложение Microsoft Entra ID добавлено в dbt и сервисный пользователь подключен, разработчики dbt смогут выполнять персональную аутентификацию в dbt через Azure DevOps. Подробнее см. Аутентификация с Azure DevOps.

Для выполнения шагов на этой странице требуются следующие роли:

  • администратор Microsoft Entra ID
  • администратор Azure DevOps
  • администратор аккаунта dbt
  • администратор Azure (если среды Entra ID и Azure DevOps не связаны)

Регистрация приложения Microsoft Entra ID​

Администратор Microsoft Entra ID должен выполнить следующие шаги:

  1. Войдите в Azure portal и выберите Microsoft Entra ID.
  2. В левой панели выберите App registrations.
  3. Нажмите New registration. Откроется форма создания нового приложения Entra ID.
  4. Укажите имя приложения. Мы рекомендуем использовать, например, dbt Labs Azure DevOps app.
  5. В качестве Supported Account Types выберите Accounts in any organizational directory (Any Entra ID directory - Multitenant).
    Многие клиенты спрашивают, почему необходимо выбирать Multitenant вместо Single tenant, и часто ошибаются на этом шаге. Microsoft рассматривает Azure DevOps (ранее Visual Studio) и Microsoft Entra ID как отдельные тенанты, поэтому для корректной работы приложения Entra ID необходимо выбрать Multitenant.
  6. Добавьте redirect URI.
    1. Выберите платформу Web.
    2. В поле введите https://YOUR_ACCESS_URL/complete/azure_active_directory. Обязательно замените YOUR_ACCESS_URL на соответствующий Access URL для вашего региона и плана.
  7. Нажмите Register.
Переход к регистрации приложений Entra IDПереход к регистрации приложений Entra ID

Вот как должно выглядеть приложение перед регистрацией:

Регистрация прил�ожения Microsoft Entra IDРегистрация приложения Microsoft Entra ID

Добавление разрешений для нового приложения​

Администратор Entra ID должен предоставить новому приложению доступ к Azure DevOps:

  1. В левой панели навигации выберите API permissions.
  2. Удалите разрешение Microsoft Graph / User Read.
  3. Нажмите Add a permission.
  4. Выберите Azure DevOps.
  5. Выберите разрешение user_impersonation. Это единственное доступное разрешение для Azure DevOps.
Добавление разрешений для приложенияДобавление разрешений для приложения

Добавление дополнительного redirect URI​

Администратор Microsoft Entra ID должен добавить еще один redirect URI в приложение Entra ID. Этот redirect URI будет использоваться для аутентификации сервисного пользователя при headless‑действиях в средах деплоя.

Перед добавлением убедитесь, что при регистрации приложения Microsoft Entra ID в качестве платформы была выбрана Web.

  1. Перейдите к вашему приложению Microsoft Entra ID.
  2. Нажмите на ссылку рядом с Redirect URIs.
  3. Нажмите Add URI и добавьте URI, заменив YOUR_ACCESS_URL на соответствующий Access URL для вашего региона и плана:
    https://YOUR_ACCESS_URL/complete/azure_active_directory_service_user
  4. Нажмите Save.
Добавление redirect URI для сервисного по�льзователяДобавление redirect URI для сервисного пользователя

Создание client secret​

Администратор Microsoft Entra ID должен выполнить следующие шаги:

  1. Перейдите к вашему приложению Microsoft Entra ID.
  2. В левой панели навигации выберите Certificates and Secrets.
  3. Выберите Client secrets и нажмите New client secret.
  4. Задайте описание секрета и выберите срок действия. Нажмите Add.
  5. Скопируйте значение поля Value и безопасно передайте его администратору аккаунта dbt, который завершит настройку.

Подключение Azure DevOps к новому приложению​

Администратору Azure потребуется одно из следующих разрешений как в Microsoft Entra ID, так и в Azure DevOps:

  • Azure Service Administrator
  • Azure Co-administrator

Если ваш аккаунт Azure DevOps уже подключен к Entra ID, вы можете перейти к разделу Подключение сервисного пользователя. Если же вы только настраиваете интеграцию, подключите Azure DevOps к созданному приложению Microsoft Entra ID:

  1. В аккаунте Azure DevOps выберите Organization settings в левом нижнем углу.
  2. Перейдите в раздел Microsoft Entra ID.
  3. Нажмите Connect directory.
  4. Выберите каталог, который нужно подключить.
  5. Нажмите Connect.
Подключение Azure DevOps и Microsoft Entra IDПодключение Azure DevOps и Microsoft Entra ID

Добавление приложения Microsoft Entra ID в dbt​

Администратор аккаунта dbt должен выполнить следующие шаги.

После подключения приложения Microsoft Entra ID и Azure DevOps необходимо предоставить dbt информацию о приложении:

  1. Перейдите в настройки аккаунта в dbt.
  2. Выберите Integrations.
  3. Прокрутите до раздела Azure DevOps и нажмите на значок карандаша для редактирования интеграции.
  4. Заполните форму:
    • Azure DevOps Organization: должно в точности совпадать с именем вашей организации Azure DevOps. Не включайте префикс dev.azure.com/. ✅ Используйте my-devops-org ❌ Не используйте dev.azure.com/my-devops-org
    • Application (client) ID: указывается из приложения Microsoft Entra ID.
    • Client Secrets: скопируйте значение поля Value из client secret приложения Microsoft Entra ID и вставьте его в поле Client Secret в dbt. Администраторы Entra ID отвечают за срок действия секрета, а администраторы dbt должны учитывать дату его истечения для ротации.
    • Directory(tenant) ID: указывается из приложения Microsoft Entra ID.
      Добавление приложения Microsoft Entra ID в dbtДобавление приложения Microsoft Entra ID в dbt

Теперь приложение Microsoft Entra ID должно быть добавлено в ваш аккаунт dbt. Участники команды, которые хотят разрабатывать в Studio IDE или использовать CLI dbt, могут персонально авторизовать Azure DevOps из своего профиля.

Подключение сервисного пользователя​

Сервисный пользователь — это псевдо‑пользователь, который настраивается аналогично реальному пользователю‑администратору, но получает разрешения, специально ограниченные для взаимодействия сервис‑к‑сервису. Следует избегать привязки аутентификации к реальному пользователю Azure DevOps, поскольку при его уходе из организации dbt потеряет доступ к репозиториям dbt в Azure DevOps, что приведет к сбоям production‑запусков.

Срок действия аутентификации сервисного пользователя

dbt обновляет аутентификацию сервисного пользователя при каждом запуске, инициированном планировщиком, API или CI. Если в аккаунте не было активных запусков более 90 дней, администратору потребуется вручную обновить аутентификацию сервисного пользователя, отключив и повторно подключив его профиль через OAuth‑процесс, описанный выше, чтобы возобновить headless‑взаимодействия, такие как настройка проектов, deployment‑запуски и CI.

Разрешения сервисного пользователя​

Аккаунт сервисного пользователя должен иметь следующие разрешения Azure DevOps для всех проектов и репозиториев, к которым требуется доступ в dbt. Ниже описано, как dbt использует каждое из этих разрешений.

  • Project Reader
  • ViewSubscriptions
  • EditSubscriptions
  • DeleteSubscriptions *
  • PullRequestContribute
  • GenericContribute

* Примечание: разрешение DeleteSubscriptions может входить в EditSubscriptions в зависимости от версии Azure.

Некоторые из этих разрешений доступны только через Azure DevOps API или CLI. Ниже мы также привели дополнительную информацию об использовании Azure DevOps API, чтобы ускорить настройку. Альтернативно вы можете включить разрешения через UI Azure DevOps, однако в этом случае нельзя добиться минимально необходимого набора разрешений.

Разрешения сервисного пользователя также определяют, какие репозитории команда сможет выбрать при создании dbt‑проекта. Поэтому администратор Azure DevOps должен предоставить сервисному пользователю как минимум доступ Project Reader до создания нового проекта в dbt. Если вы мигрируете существующий dbt‑проект на нативную интеграцию с Azure DevOps, сервисный пользователь аккаунта dbt должен иметь корректные разрешения на репозиторий до начала миграции.

ViewSubscriptions

Security Namespace ID: cb594ebe-87dd-4fc9-ac2c-6a10a4c92046

Namespace: ServiceHooks

Permission:

{
    "bit": 1,
    "displayName": "View Subscriptions",
    "name": "ViewSubscriptions"
}

Uses: Для просмотра существующих подписок service hooks в Azure DevOps

Token (where applicable - API only):

  • PublisherSecurity для доступа ко всем проектам
  • PublisherSecurity/<azure_devops_project_object_id> для доступа к отдельному проекту

UI/API/CLI: только API/CLI

Sample CLI code snippet

az devops security permission update --organization https://dev.azure.com/<org_name> --namespace-id cb594ebe-87dd-4fc9-ac2c-6a10a4c92046 --subject <service_account>@xxxxxx.onmicrosoft.com --token PublisherSecurity/<azure_devops_project_object_id> --allow-bit 1
EditSubscriptions

Security Namespace ID: cb594ebe-87dd-4fc9-ac2c-6a10a4c92046

Namespace: ServiceHooks

Permission:

{
    "bit": 2,
    "displayName": "Edit Subscription",
    "name": "EditSubscriptions"
}

Uses: Для добавления или обновления существующих подписок service hooks в Azure DevOps

Token (where applicable - API only):

  • PublisherSecurity для доступа ко всем проектам
  • PublisherSecurity/<azure_devops_project_object_id> для доступа к отдельному проекту

UI/API/CLI: только API/CLI

Sample CLI code snippet

az devops security permission update --organization https://dev.azure.com/<org_name> --namespace-id cb594ebe-87dd-4fc9-ac2c-6a10a4c92046 --subject <service_account>@xxxxxx.onmicrosoft.com --token PublisherSecurity/<azure_devops_project_object_id> --allow-bit 2
DeleteSubscriptions

Security Namespace ID: cb594ebe-87dd-4fc9-ac2c-6a10a4c92046

Namespace: ServiceHooks

Permission:

{
    "bit": 4,
    "displayName": "Delete Subscriptions",
    "name": "DeleteSubscriptions"
}

Uses: Для удаления избыточных подписок service hooks в Azure DevOps

Token (where applicable - API only):

  • PublisherSecurity для доступа ко всем проектам
  • PublisherSecurity/<azure_devops_project_object_id> для доступа к отдельному проекту

UI/API/CLI: только API/CLI

Sample CLI code snippet

az devops security permission update --organization https://dev.azure.com/<org_name> --namespace-id cb594ebe-87dd-4fc9-ac2c-6a10a4c92046 --subject <service_account>@xxxxxx.onmicrosoft.com --token PublisherSecurity/<azure_devops_project_object_id> --allow-bit 4

Additional Notes: В последних версиях Azure DevOps это разрешение признано устаревшим. Разрешение Edit Subscriptions (bit 2) включает права на удаление.

PullRequestContribute

Security Namespace ID: 2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87

Namespace: Git Repositories

Permission:

{ 	
    "bit": 16384,  
    "displayName": "Contribute to pull requests",
    "name": "PullRequestContribute"
}

Uses: Для публикации статусов Pull Request в Azure DevOps

Token (where applicable - API only):

  • repoV2 для доступа ко всем проектам
  • repoV2/<azure_devops_project_object_id> для доступа к отдельному проекту
  • repoV2/<azure_devops_project_object_id>/<azure_devops_repository_object_id> для доступа к отдельному репозиторию

UI/API/CLI: UI, API и CLI

Sample CLI code snippet

az devops security permission update --organization https://dev.azure.com/<org_name> --namespace-id 2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87 --subject <service_account>@xxxxxx.onmicrosoft.com --token repoV2/<azure_devops_project_object_id>/<azure_devops_repository_object_id> --allow-bit 16384

Additional Notes: Это разрешение автоматически наследуется, если в UI установлен Project Reader/Contributor/Administrator.

GenericContribute

Security Namespace ID: 2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87

Namespace: Git Repositories

Permission:

{
    "bit": 4,
    "displayName": "Contribute",
    "name": "GenericContribute"
}

Uses: Для публикации статусов коммитов в Azure DevOps

Token (where applicable - API only):

  • repoV2 для доступа ко всем проектам
  • repoV2/<azure_devops_project_object_id> для доступа к одному проекту
  • repoV2/<azure_devops_project_object_id>/<azure_devops_repository_object_id> для доступа к одному репозиторию

UI/API/CLI: UI, API и CLI

Sample CLI code snippet

az devops security permission update --organization https://dev.azure.com/<org_name> --namespace-id 2e9eb7ed-3c0a-47d4-87c1-0ffdd275fd87 --subject <service_account>@xxxxxx.onmicrosoft.com --token repoV2/<azure_devops_project_object_id>/<azure_devops_repository_object_id> --allow-bit 4

Additional Notes: Это разрешение автоматически наследуется, если в UI установлен Project Contributor/Administrator.

Вы должны подключить сервисного пользователя до настройки проекта dbt, так как разрешения сервисного пользователя определяют, какие проекты dbt может импортировать.

Администратор аккаунта dbt, имеющий доступ к аккаунту сервисного пользователя в Azure DevOps, должен выполнить следующие шаги для подключения сервисного пользователя:

  1. Войдите в аккаунт сервисного пользователя в Azure DevOps.
  2. В dbt перейдите в Account settings > Integrations.
  3. Перейдите в раздел Azure DevOps и выберите Service User.
  4. Введите значения в обязательные поля.
  5. Нажмите Save.
  6. Нажмите Link Azure service user.
  7. Вы будете перенаправлены в Azure DevOps, где необходимо принять разрешения приложения Microsoft Entra ID.
  8. После этого вы будете перенаправлены обратно в dbt, и сервисный пользователь будет подключен.
Подключение сервисного пользователя AzureПодключение сервисного пользователя Azure

После подключения dbt отображает email‑адрес сервисного пользователя, чтобы было понятно, учетная запись какого пользователя обеспечивает headless‑действия в средах деплоя. Чтобы изменить подключенный аккаунт, отключите профиль в dbt, войдите в альтернативный сервисный аккаунт Azure DevOps и повторно свяжите его с dbt.

Personal Access Tokens (PATs)

dbt использует сервисного пользователя для генерации временных токенов доступа — PATs.

Эти токены имеют ограниченную область действия, действительны только 5 минут и становятся недействительными после одного API‑вызова.

Токены ограничены следующими scopes:

  • vso.code_full: предоставляет полный доступ к исходному коду и метаданным системы контроля версий (коммиты, ветки и т.д.), а также возможность создавать и управлять репозиториями, pull request’ами и code review, и получать уведомления о событиях контроля версий через service hooks. Также включает ограниченную поддержку Client OM API.
  • vso.project: предоставляет возможность читать проекты и команды.
  • vso.build_execute: предоставляет возможность доступа к артефактам сборки, включая результаты сборок, определения и запросы, а также возможность ставить сборки в очередь, обновлять их свойства и получать уведомления о событиях сборки через service hooks.

Нашли ошибку?

0
Loading