Использование субъектов-служб и управляемых удостоверений в Azure DevOps

Azure DevOps Services

Учетные данные службы и управляемые удостоверения обеспечивают безопасную масштабируемую аутентификацию для рабочих процессов автоматизации Azure DevOps. Эти типы удостоверений Microsoft Entra обеспечивают повышенную безопасность по сравнению с традиционными личными маркерами доступа (PATs). Они используют автоматическое управление учетными данными, более короткие сроки существования маркеров и средства управления доступом корпоративного уровня.

Преимущества сервисных принципалов и управляемых идентичностей

Улучшенная безопасность

• Кратковременные маркеры: срок действия маркеров Microsoft Entra истекает каждый час, что снижает риск воздействия по сравнению с PATs (что может длиться до одного года).
• Автоматическая смена: управляемые удостоверения обрабатывают смену учетных данных автоматически.
• Нет сохраненных секретов: необходимость хранения учетных данных в коде или конфигурации не требуется.

Эффективность работы

• Централизованное управление: управление доступом с помощью политик идентификатора Microsoft Entra и разрешений Azure DevOps.
• Возможности аудита: отслеживание шаблонов проверки подлинности и доступа с помощью комплексного ведения журнала.
• Эффективное масштабирование: поддержка сценариев корпоративной автоматизации без отдельных зависимостей пользователей.

Современная проверка подлинности

• На основе стандартов: использует протоколы OAuth 2.0 и OpenID Connect.
• Поддержка многофакторной проверки подлинности: наследует политики безопасности организации.
• Условный доступ: применяет расширенные политики безопасности на основе контекста.

Общие сведения о субъектах-службах и управляемых удостоверениях

Сервисные принципы

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

Основные характеристики

• Создаются с помощью регистрации приложений в идентификаторе Microsoft Entra.
• Поддержка мультитенантных сценариев.
• Требовать явное управление учетными данными (сертификаты или секреты клиента).
• Идеально подходит для приложений, которые должны проходить проверку подлинности в разных средах.

Управляемые идентичности

Управляемые удостоверения — это особый тип служебного принципала, которым Azure управляет автоматически. Они устраняют необходимость для разработчиков управлять учетными данными, предоставляя автоматически управляемое удостоверение в идентификаторе Microsoft Entra для ресурсов Azure.

Типы управляемых удостоверений

Управляемое удостоверение, назначаемое системой:

• Автоматически создается и привязана к определенному ресурсу Azure.
• Жизненный цикл, управляемый Azure (удаляется при удалении ресурса).
• Связь "один к одному" с ресурсом Azure.
• Лучше всего подходит для приложений, развернутых в одном ресурсе Azure.

Управляемое удостоверение, назначаемое пользователем:

• Создан как автономный ресурс Azure.
• Можно назначить нескольким ресурсам Azure.
• Жизненный цикл управляется независимо от связанных ресурсов.
• Лучше всего подходит для приложений, работающих на нескольких ресурсах или требующих общего удостоверения.

Когда следует использовать каждый тип:

• Субъекты-службы: развертывания между облаками, конвейеры непрерывной интеграции и непрерывной доставки (CI/CD), приложения за пределами Azure.
• Назначаемые системой управляемые удостоверения: одно приложения ресурсов Azure (Функции Azure, Служба приложений Azure).
• Назначаемые пользователем управляемые удостоверения: приложения с несколькими ресурсами, сценарии общего удостоверения.

Руководство по реализации

Выполните следующие действия, чтобы реализовать принципы службы или управляемые идентификаторы для аутентификации в Azure DevOps. Полные примеры кода см. в примерах приложений.

Шаг 1: Создайте свою личность

Выберите соответствующий тип удостоверения в зависимости от сценария развертывания.

Вариант A: Создание учетной записи службы (регистрация приложения)

Субъекты-службы хорошо работают для конвейеров CI/CD, сценариев между облаками и приложений, которым требуются гибкие варианты развертывания.

1. Зарегистрируйте приложение в Центре администрирования Microsoft Entra.

2. Перейдите к регистрации приложений>, чтобы создать регистрацию.

3. Настройте приложение:

   • Имя: используйте описательное имя приложения.
   • Типы учетных записей: выберите соответствующую поддержку клиента.
   • URI перенаправления. Оставьте пустым для сценариев "служба — служба".

4. Создайте учетные данные проверки подлинности:

   • Рекомендуется отправить сертификат для повышения безопасности.
   • Альтернатива. Создание секрета клиента (требуется регулярное поворот).

Дополнительные сведения см. в следующих статьях:

• Сведения об объектах приложения и субъекта-службы в Microsoft Entra ID
• Создать учетную запись службы

Вариант B: Создание управляемого удостоверения

Управляемые удостоверения предоставляют простейший интерфейс проверки подлинности для размещенных в Azure приложений.

Для управляемого удостоверения, назначаемого системой:

1. Перейдите к ресурсу Azure, например Службе приложений или приложению Функций Azure.
2. Перейдите к Идентификации>Системное назначение.
3. Переключите состояние на Вкл.
4. Нажмите кнопку "Сохранить", чтобы сохранить конфигурацию.

Для управляемого удостоверения, назначаемого пользователем:

1. Создайте управляемое удостоверение на портале Azure.
2. Перейдите к Создать ресурс>Управляемое удостоверение.
3. Настройте базовые параметры и создайте ресурс.
4. При необходимости назначьте ресурсы.

Дополнительные сведения см. в следующих статьях:

• Обзор управляемых идентификаторов
• Управление назначаемыми пользователем управляемыми идентичностями

Шаг 2: Добавить идентификатор в Azure DevOps

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

Предпосылки

• Роль администратора коллекции проектов.
• Роль администратора проекта или администратора группы, если политика приглашения позволяет администраторам групп добавлять пользователей.

Добавление удостоверения

Чтобы добавить удостоверение на портале Azure DevOps, выполните следующие действия.

1. Перейдите кпользователям> организации.

2. Выберите "Добавить пользователей".

3. Введите отображаемое имя вашего сервисного принципала или управляемой идентичности.

4. Выберите соответствующий уровень доступа и доступ к проекту.

5. Отправьте приглашение.

   

Добавьте удостоверение программным способом:

Используйте REST API ServicePrincipalEntitlements для автоматизации процесса.

Другие рекомендации.

• Найдите правильный идентификатор: Используйте идентификатор объекта субъекта-службы в области корпоративных приложений в Центре администрирования Microsoft Entra, а не идентификатор объекта регистрации приложения.
• Ограничения клиента: Удостоверения можно добавлять только из того же клиента, к которому подключена организация Azure DevOps. Сведения о сценариях с несколькими клиентами см. в разделе Обходное решение - часто задаваемые вопросы.

Шаг 3. Настройка разрешений

Настройте детализированные разрешения для служебного принципала или управляемого удостоверения в Azure DevOps. В отличие от других служб Azure, Azure DevOps использует собственную модель разрешений, а не разрешения приложения Microsoft Entra.

Параметры разрешений:

• Прямое назначение: назначение разрешений непосредственно удостоверению.
• Членство в группах. Добавление в группы Azure DevOps или группы безопасности Microsoft Entra.
• Уровни доступа: назначьте соответствующий уровень лицензии (базовый, базовый и тестовый план или подписчик Visual Studio).

Рекомендации:

• Примените минимальные привилегии: предоставьте только необходимые минимальные разрешения.
• Использование групп. Управление разрешениями с помощью групп для упрощения обслуживания.
• Регулярные проверки: периодические разрешения аудита.

Параметры управления разрешениями:

• Портал Azure DevOps: выбор параметров> организации.
• REST API: используйте API Графа субъекта-службы для программного управления.

Шаг 4: Получить токены идентификатора Microsoft Entra

Получение маркеров доступа для проверки подлинности приложений с помощью API и служб Azure DevOps.

Для субъектов-служб

Используйте поток учетных данных клиента:

POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={client-id}
&scope=https://app.vssps.visualstudio.com/.default
&client_secret={client-secret}
&grant_type=client_credentials

Используйте проверку подлинности сертификата (рекомендуется):

using Microsoft.Identity.Client;

var app = ConfidentialClientApplicationBuilder
    .Create(clientId)
    .WithCertificate(certificate)
    .WithAuthority(new Uri($"https://login.microsoftonline.com/{tenantId}"))
    .Build();

var result = await app
    .AcquireTokenForClient(new[] { "https://app.vssps.visualstudio.com/.default" })
    .ExecuteAsync();

string accessToken = result.AccessToken;

Для управляемых удостоверений

Из ресурсов Azure:

using Azure.Identity;
using Azure.Core;

var credential = new ManagedIdentityCredential();
var tokenRequest = new TokenRequestContext(new[] { "https://app.vssps.visualstudio.com/.default" });
var token = await credential.GetTokenAsync(tokenRequest);

string accessToken = token.Token;

Используйте службу метаданных экземпляра Azure:

GET http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https://app.vssps.visualstudio.com/
Metadata: true

Azure CLI для нерегламентированных операций

Для однократных операций или тестирования используйте Azure CLI:

# For service principal
az login --service-principal --username {client-id} --password {client-secret} --tenant {tenant-id}
az account get-access-token --resource https://app.vssps.visualstudio.com/

# For managed identity (from Azure resource)
az login --identity
az account get-access-token --resource https://app.vssps.visualstudio.com/

Дополнительные сведения см. в разделе "Получение токенов Microsoft Entra".

Шаг 5. Использование маркеров с Azure DevOps

Используйте полученные маркеры для проверки подлинности вызовов REST API и других операций Azure DevOps.

Выполните вызовы API, прошедшие проверку подлинности:

using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = 
    new AuthenticationHeaderValue("Bearer", accessToken);

var response = await client.GetAsync(
    "https://dev.azure.com/{organization}/_apis/projects?api-version=7.1");

Примеры видео

Распространенные сценарии интеграции

• Веб-каналы NuGet: подключение к NuGet.exe или dotnet CLI.
• Публикация Marketplace: публикация расширений с помощью командной строки.
• Azure Pipelines: создание подключений служб , поддерживаемых управляемыми удостоверениями.
• Операции Git: клонирование репозиториев с помощью диспетчера учетных данных Git.

Полные примеры кода см. в примерах приложений.

Рекомендации по управлению

Субъекты-службы и управляемые удостоверения имеют разные характеристики управления по сравнению с учетными записями пользователей.

Лицензирование

• Для каждого удостоверения требуется лицензия в каждой организации, к ней присоединяется.
• Выставление счетов в нескольких организациях не применяется к субъектам-службам.
• Правила лицензирования на основе групп не применяются автоматически. Необходимо назначить лицензии напрямую.

Управление идентичностью

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

Членство в группах

• Можно добавить в группы Microsoft Entra и группы Azure DevOps.
• Имеет техническое ограничение, которое предотвращает отображение списков членов группы Microsoft Entra (только ограничение пользовательского интерфейса).
• Может по-прежнему наследовать разрешения от групп Microsoft Entra, к которым они относятся.

Материализация

• Необходимо явно добавить в организации (без автоматической материализации, например пользователей).
• Требуется, так как субъекты-службы не могут выполнять интерактивный вход.

Основные отличия от учетных записей пользователей

Субъекты-службы и управляемые удостоверения имеют определенные ограничения по сравнению с обычными пользователями.

Capabilities

• ✅ Создайте маркеры Microsoft Entra для доступа к API.
• ✅ Доступ к ресурсам Azure DevOps с соответствующими разрешениями.
• ✅ Присоединяйтесь к группам безопасности и командам.
• ❌ Создание pats или ключей Secure Shell.
• ❌ Войдите в интерактивном режиме или получите доступ через веб-интерфейс.
• ❌ Создание или владение организациями.
• ❌ Поддержка потоков OAuth в Azure DevOps .

Выставление счетов

• Считается отдельной лицензией в каждой организации. (Скидка с несколькими организациями отсутствует.)
• Необходимо назначить уровень доступа напрямую. (Правила группы не применяются автоматически.)

Часто задаваемые вопросы

Q. Почему вместо PAT следует использовать субъект-службу или управляемое удостоверение?

А. Субъекты-службы и управляемые удостоверения обеспечивают значительные преимущества безопасности по сравнению с PAT.

Преимущества безопасности:

• Более короткий срок жизни: срок действия маркеров Microsoft Entra истекает почасово по сравнению с PATs, что может длиться до года.
• Автоматическая смена: управляемые удостоверения автоматически поворачивают учетные данные.
• Нет общих секретов: риск хранения или случайного предоставления долгосрочных маркеров устраняется.
• Централизованный элемент управления: управляемый с помощью идентификатора Microsoft Entra с помощью корпоративных политик безопасности.

Операционные преимущества:

• Путь аудита: полностью журналы проверки подлинности и доступа.
• Условный доступ: применяет политики на основе расположения, устройства и факторов риска.
• Нет учетных записей служб. Устраняет зависимость от отдельных учетных записей пользователей для автоматизации.

Примеры миграции см. в статье "Замена PATs маркерами Microsoft Entra".

Q. Каковы ограничения скорости для субъектов-служб и управляемых удостоверений?

А. Субъекты-службы и управляемые удостоверения имеют те же ограничения скорости , что и пользователи.

Q. Будет ли использовать эту функцию дороже?

А. Субъекты-службы и управляемые удостоверения оцениваются как пользователи на основе уровня доступа. Основные различия:

• Нет скидки на выставление счетов в нескольких организациях: каждое удостоверение считается отдельной лицензией в каждой организации.
• Назначение лицензий. Уровни доступа должны быть назначены напрямую. (Правила группы не применяются автоматически.)
• Одни и те же ценовые категории: базовые, базовые и тестовые планы и тарифы подписчиков Visual Studio применяются.

Q. Можно ли добавить управляемое удостоверение из другого клиента в мою организацию?

А. Вы можете добавлять удостоверения непосредственно из подключенного клиента вашей организации. Для сценариев между клиентами используйте это решение.

Чтобы настроить управляемое удостоверение между клиентами, выполните приведенные действия.

1. Создайте управляемое удостоверение, назначаемое пользователем, в клиенте ресурсов.
2. Назначьте его ресурсу Azure, например виртуальной машине или приложению Функций).
3. Создайте хранилище ключей и создайте сертификат (формат, отличный от PEM).
4. Предоставьте управляемому удостоверению доступ к хранилищу ключей с разрешениями "Получить и вывод списка секретов".
5. Скачайте сертификат в формате CER (только открытый ключ).
6. Зарегистрируйте приложение в целевом клиенте.
7. Отправьте сертификат в регистрацию приложения.
8. Добавьте субъект-службу в организацию Azure DevOps.
9. Настройте проверку подлинности с помощью сертификата из хранилища ключей.

// Example: Acquire token using managed identity certificate
public static async Task<string> GetSecret(string keyVaultName, string secretName)
{
    var keyVaultUri = new Uri($"https://{keyVaultName}.vault.azure.net");
    var client = new SecretClient(keyVaultUri, new ManagedIdentityCredential());
    var keyVaultSecret = await client.GetSecretAsync(secretName);
    return keyVaultSecret.Value.Value;
}

private static async Task<AuthenticationResult> GetAppRegistrationAADAccessToken(
    string applicationClientID, string appTenantId)
{
    byte[] privateKeyBytes = Convert.FromBase64String(await GetSecret(keyVaultName, secretName));
    var certificate = new X509Certificate2(privateKeyBytes, (string)null, X509KeyStorageFlags.MachineKeySet);

    var app = ConfidentialClientApplicationBuilder.Create(applicationClientID)
        .WithCertificate(certificate)
        .WithAuthority(new Uri($"https://login.microsoftonline.com/{appTenantId}"))
        .Build();

    var result = await app.AcquireTokenForClient(
        new[] { "499b84ac-1321-427f-aa17-267ca6975798/.default" })
        .ExecuteAsync();

    return result;
}

Распространенные ошибки и способы их устранения

Репозиторий Git с именем или идентификатором не существует или у вас нет разрешений

Решение: Убедитесь, что субъект-служба имеет по крайней мере базовую лицензию. Лицензии заинтересованных лиц не предоставляют доступ к репозиторию.

Не удалось создать субъект-службу с идентификатором объекта

Решение: Убедитесь, что вы используете идентификатор объекта субъекта-службы из области корпоративных приложений , а не идентификатор объекта регистрации приложения.

Чтобы найти правильный идентификатор, выполните следующие действия.

1. Перейдите кприложениям Центра >администрирования Microsoft EntraEnterprise.
2. Найдите имя приложения.
3. Используйте идентификатор объекта на панели корпоративных приложений .

Доступ запрещен: требуются разрешения для добавления пользователей

Возможные причины и решения:

• Недостаточно роли: должен быть администратором коллекции проектов (PCA) или администратором проекта или команды с включенными разрешениями на приглашение.
• Ограничение политики. Проверьте, включена ли группа и администраторы проектов, чтобы пригласить новую политику пользователей .
• Назначение лицензий: администраторы проектов не могут назначать лицензии во время приглашения. Обратитесь к PCA за изменениями лицензий.

API списка списков Azure DevOps Graphs возвращает пустой список

Решение: Используется continuationToken для итерации на всех страницах. Субъекты-службы могут отображаться на последующих страницах из-за поведения разбиения на страницы API.

TF401444: ошибка: требуется вход

Решение: Убедитесь, что субъект-служба добавляется правильно в организацию с необходимыми разрешениями. Эта ошибка означает, что удостоверение не распознается в организации.

Связанный контент

• Примеры приложений и примеров кода
• Справочник по API предоставления прав для служебных субъектов
• Справочник по API Graph субъекта-службы
• Параметры проверки подлинности Microsoft Entra
• Руководство по проверке подлинности для Azure DevOps