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

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

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

important

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

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

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

После добавления приложения Microsoft Entra ID в dbt администратор аккаунта также должен подключить служебного пользователя с помощью OAuth. Эта учётная запись будет использоваться для выполнения действий без участия пользователя в dbt, таких как запуски развёртывания и 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 и нажмите Microsoft Entra ID.
  2. Выберите App registrations на левой панели.
  3. Выберите New registration. Откроется форма создания нового приложения Entra ID.
  4. Укажите имя приложения. Рекомендуем использовать «dbt Labs Azure DevOps app».
  5. Выберите 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. Добавьте URI перенаправления.
    1. Выберите Web в качестве платформы.
    2. Введите в поле https://YOUR_ACCESS_URL/complete/azure_active_directory. Обязательно замените YOUR_ACCESS_URL на соответствующий URL доступа для вашего региона и тарифного плана.
  7. Нажмите Register.
Переход к регистрации приложений Entra IDПереход к регистрации приложений Entra ID

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

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

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

Администратор Microsoft 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‑действиях в средах деплоя.

Перед добавлением URI убедитесь, что при регистрации приложения вы выбрали платформу 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.

Создание секрета клиента​

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

Добавление URI перенаправления для служебного пользователяДобавление URI перенаправления для служебного пользователя
  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 из раздела секретов клиента приложения Microsoft Entra ID и вставьте его в поле Client Secret в dbt. Администраторы Entra ID отвечают за срок действия секрета приложения Entra ID, а администраторам dbt следует зафиксировать дату истечения срока действия, чтобы своевременно заменить секрет.
    • Directory(tenant) ID: Указан в приложении Microsoft Entra ID.
      Добавление приложения Microsoft Entra ID в dbtДобавление приложения Microsoft Entra ID в dbt

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

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

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

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

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

Если Studio IDE не запускается и отображает сообщение Failed to start server. The project is not fully set up: Azure Service User not found, значит, служебный пользователь на уровне аккаунта не подключён. Подробнее см. в разделе Подключение служебного пользователя.

Если вместо этого отображается сообщение Missing Azure user, значит, личный аккаунт Azure DevOps разработчика не связан с dbt. Подробнее см. в разделе Аутентификация в Azure DevOps.

Разрешения служебных пользователей​

Учётная запись служебного пользователя должна иметь следующие разрешения Azure DevOps для всех проектов и репозиториев 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 отображает адрес электронной почты служебного пользователя, чтобы вы знали, разрешения какого пользователя используются для выполнения действий без участия пользователя в средах развёртывания. Чтобы сменить подключённый аккаунт, отключите профиль в dbt, войдите в другой служебный аккаунт Azure DevOps и повторно привяжите аккаунт в dbt.

Персональные токены доступа (PAT)

dbt использует служебного пользователя для создания временных токенов доступа, называемых PAT.

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

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

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

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

0
Loading