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

Azure DevOps Services

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

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

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

Управляемые удостоверения — это еще одна функция Microsoft Entra, которая действует аналогично субъектам-службам приложения. Эти объекты предоставляют удостоверения для ресурсов Azure и позволяют легко использовать службы, поддерживающие проверку подлинности Microsoft Entra для предоставления общего доступа к учетным данным. Это привлекательный вариант, так как идентификатор Microsoft Entra id заботится об управлении учетными данными и смене учетных данных. Хотя настройка управляемого удостоверения может отличаться на портале Azure, Azure DevOps обрабатывает оба объекта безопасности так же, как новое удостоверение приложения в организации с определенными разрешениями. В остальной части этой статьи мы ссылаемся на управляемые удостоверения и субъекты-службы взаимозаменяемо в качестве субъекта-службы, если они не указаны.

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

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

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

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

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

Вариант 1: Создайте учетную запись службы для приложения

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

Дополнительные сведения:

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

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

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

• Назначаемое системой управляемое удостоверение: некоторые службы Azure позволяют включить управляемое удостоверение непосредственно в экземпляре службы. При включении управляемого удостоверения, назначаемого системой, удостоверение создается в идентификаторе Microsoft Entra. Это удостоверение привязано к жизненному циклу этого экземпляра службы. Поэтому при удалении ресурса Azure автоматически удаляет удостоверение. Только один конкретный ресурс Azure может использовать это удостоверение для получения токенов Microsoft Entra ID.
• Назначаемое пользователем управляемое удостоверение можно также создать управляемое удостоверение как автономный ресурс Azure, создав управляемое удостоверение, назначаемое пользователем, и назначив его одному или нескольким экземплярам службы Azure. Если используются управляемые удостоверения, назначаемые пользователем, управление таким удостоверением осуществляется отдельно от ресурсов, которые его используют.

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

• Что такое управляемые удостоверения для ресурсов Azure?
• Управление управляемыми удостоверениями, назначаемыми пользователем
• Настройка управляемых удостоверений для ресурсов Azure на виртуальной машине с помощью портал Azure

2. Добавление субъекта-службы в организацию Azure DevOps

После настройки субъектов-служб в Центре администрирования Microsoft Entra необходимо сделать то же самое в Azure DevOps, добавив субъекты-службы в вашу организацию. Их можно добавить на странице "Пользователи" или с помощью API ServicePrincipalEntitlements. Так как они не могут входить в интерактивном режиме, учетная запись пользователя, которая может добавлять пользователей в организацию, проект или команду, должна добавить их. Такие пользователи включают администраторов коллекции проектов (PCA) или администраторов проектов и администраторов команд, когда включена политика "Разрешить администраторам команд и проектов приглашать новых пользователей".

Если вы являетесь PCA, вы также можете предоставить субъекту-службе доступ к определенным проектам и назначить лицензию. Если вы не pcA, необходимо обратиться к PCA, чтобы обновить все членства в проекте или уровни доступа к лицензиям.

3. Настройте разрешения для служебного принципала

После добавления субъектов-служб в организацию их можно обрабатывать аналогично стандартным учетным записям пользователей. Вы можете назначить разрешения непосредственно субъекту-службе, добавить его в группы безопасности и команды, назначить его любому уровню доступа и удалить его из организации. Можно также использовать Service Principal Graph APIs для выполнения операций CRUD с субъектами-службами.

Настройка этих разрешений может отличаться от способа настройки разрешений приложения в приложении Microsoft Entra для других ресурсов Azure. Azure DevOps не зависит от настройки "Разрешения приложения", доступной для регистрации приложений через портал Azure. Эти разрешения приложения применяются к основному компоненту службы во всех организациях, связанных с тенантом, и не учитывают разрешения организации, проекта или объекта, доступные в Azure DevOps. Чтобы предложить субъекты-службы более детализированные разрешения, мы опираемся на собственную модель разрешений вместо идентификаторов Microsoft Entra.

4. Управление субъектом-службой

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

• Субъекты-службы не имеют сообщений электронной почты и таким образом, они не могут быть приглашены в организацию по электронной почте.
• Правила групп для лицензирования в настоящее время не применяются к субъектам-службам. Если вы хотите назначить уровень доступа субъекту-службе, лучше всего сделать это напрямую.
• Субъекты-службы можно добавить в группы Microsoft Entra (на портале Azure). В настоящее время существует техническое ограничение, запрещающее нам отображать их в списке участников группы Microsoft Entra. Это ограничение не верно для групп Azure DevOps. Это говорится, что субъект-служба по-прежнему наследует все разрешения группы, заданные на основе группы Microsoft Entra, к которой они принадлежат.
• Пользователи в группе Microsoft Entra не являются частью организации Azure DevOps сразу же, так как администратор создает группу и добавляет в нее группу Microsoft Entra. У нас есть процесс под названием "материализация", который происходит после первого входа пользователя из группы Microsoft Entra в организацию. Пользователь, войдите в организацию, позволяет определить, какие пользователи должны предоставлять лицензию. Так как вход недоступна для субъектов-служб, администратор должен явно добавить его в организацию, как описано ранее.
• Вы не можете изменить отображаемое имя субъекта-службы или аватар в Azure DevOps.
• Служебные принципы получают лицензии в каждой организации, к которой они добавляются, даже если выбрано выставление счетов в нескольких организациях.

5. Получение токена идентификатора Microsoft Entra

(a) Получение токена идентификатора Microsoft Entra программно

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

Возвращаемый токен доступа — это веб-токен JSON (JWT) с определёнными ролями, которые можно использовать для доступа к ресурсам организации, используя токен как Bearer.

(b) Получите токен идентификатора Microsoft Entra с помощью Azure CLI

Для разовых операций может быть проще получить разовый токен идентификации Microsoft Entra с помощью Azure CLI. Этот подход предпочтителен для операций, которые не нуждаются в регулярном повороте постоянного маркера, например вызовов API или операций клонирования git.

Предварительные требования

• идентификатор клиента Azure и идентификатор подписки. Убедитесь, что подписка связана с клиентом, подключенным к организации Azure DevOps, к которому вы пытаетесь получить доступ. Если вы не знаете идентификатор клиента или подписки, его можно найти на портале Azure.
• идентификатор клиента приложения Azure и секрет клиента
• Azure CLI

Эти инструкции представлены в документации Databricks, а подробности можно найти на их странице.

1. Войдите в Azure CLI как служебный принципал, используя команду az devops login.
2. Следуйте инструкциям на экране и завершите вход.

# To authenticate a service principal with a password or cert:
az login --service-principal -u <app-id> -p <password-or-cert> --tenant <tenant>

# To authenticate a managed identity:
az login --identity

3. Задайте правильную подписку для субъекта-службы, вошедшего в систему, введя команду:

az account set -s <subscription-id>

4. Создайте токен доступа Microsoft Entra ID с идентификатором ресурса Azure DevOps az account get-access-token: 499b84ac-1321-427f-aa17-267ca6975798.

$accessToken = az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query "accessToken" --output tsv

5. Теперь вы можете использовать az cli команды для обычных. Давайте попытаемся вызвать API Azure DevOps, передав его в заголовки в виде маркера Bearer:

$apiVersion = "7.1-preview.1"
$uri = "https://dev.azure.com/${yourOrgname}/_apis/projects?api-version=${apiVersion}"
$headers = @{
    Accept = "application/json"
    Authorization = "Bearer $accessToken"
}
Invoke-RestMethod -Uri $uri -Headers $headers -Method Get | Select-Object -ExpandProperty value ` | Select-Object id, name

6. Используйте маркер идентификатора Microsoft Entra для проверки подлинности в ресурсах Azure DevOps

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

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

Следуйте этим примерам, найдя код приложения в нашей коллекции примеров приложений.

Некоторые распространенные сценарии проверки подлинности с помощью субъектов-служб, помимо вызова REST API Azure DevOps, можно найти в следующих документах:

• Подключите служебный принципал к каналу NuGet с Nuget.exe или dotnet.
• Опубликовать расширения в Visual Studio Marketplace через командную строку с вашим принципалом службы.
• Создайте подключения к службам без секретов в Azure Pipelines на основе служебных принципалов или управляемых удостоверений.
• Клонирование репозиториев с использованием учетной записи службы и Git Credential Manager

Как субъекты-службы отличаются от пользователей

• Вы не можете изменить отображаемое имя субъекта-службы или аватар в Azure DevOps.
• Субъект-служба считается лицензией для каждой организации, к ней присоединяется, даже если выставление счетов в нескольких организациях.
• Субъекты-службы не могут быть владелец организации или создавать организации.
• Субъекты-службы не могут создавать такие маркеры, как личные маркеры доступа или ключи SSH. Они могут создавать собственные токены идентификаторов Microsoft Entra для вызова REST API Azure DevOps.
• Субъекты-службы не поддерживают Azure DevOps OAuth.

Вопросы и ответы

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

Ответ. Многие из наших клиентов ищут субъект-службу или управляемое удостоверение, чтобы заменить существующий PAT (личный маркер доступа). Такие PAT часто принадлежат учетной записи службы (общей учетной записи группы), которая использует их для проверки подлинности приложения с помощью ресурсов Azure DevOps. PaTs должны быть трудоемко поворачиваются каждые так часто (минимум 180 дней). Неправильно сохраненные персональные аутентификационные токены могут попасть в неправильные руки и обеспечивать его часто более длительный срок действия. Токены Microsoft Entra истекают каждый час, ограничивая общий фактор риска при утечке. Для распространенных сценариев PAT мы делимся некоторыми примерами о том, как можно использовать токен Microsoft Entra вместо.

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

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

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

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

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

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

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

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

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);

	var secret = keyVaultSecret.Value;
	return secret.Value;
}

private static async Task<AuthenticationResult> GetAppRegistrationAADAccessToken(string applicationClientID, string appTenantId)
{
	IConfidentialClientApplication app;

	byte[] privateKeyBytes = Convert.FromBase64String(GetSecret(keyVaultName, secretName));
	X509Certificate2 certificateWithPrivateKey = new X509Certificate2(privateKeyBytes, (string)null, X509KeyStorageFlags.MachineKeySet);

	app = ConfidentialClientApplicationBuilder.Create(applicationClientID)
		.WithCertificate(certificateWithPrivateKey)
		.WithAuthority(new Uri(string.Format(CultureInfo.InvariantCulture, "https://login.microsoftonline.com/{0}", appTenantId)))
		.Build();
	app.AddInMemoryTokenCache();

	string AdoAppClientID = "499b84ac-1321-427f-aa17-267ca6975798/.default";
	string[] scopes = new string[] { AdoAppClientID };

	var result = await app.AcquireTokenForClient(scopes).ExecuteAsync();

	return result;
}

Потенциальные ошибки

Репозиторий Git с именем или идентификатором "{repoName}" не существует или у вас нет разрешений для операции, которую вы пытаетесь выполнить.

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

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

Субъект-служба отсутствует в provided objectId клиенте, подключенном к вашей организации. Одна из распространенных причин заключается в том, что вы передаете идентификатор объекта регистрации приложения, а не идентификатор объекта субъекта-службы. Помните, что субъект-служба — это объект, представляющий приложение для данного клиента, это не само приложение. Его service principal object ID можно найти на странице корпоративных приложений клиента. Найдите имя приложения и выберите результат Enterprise Application, который возвращается. Этот результат является страницей субъекта-службы или корпоративного приложения, и вы можете использовать идентификатор объекта, найденный на этой странице, для создания субъекта-службы в Azure DevOps.

Доступ запрещен: {ID of the caller identity} требуется следующие разрешения для пользователей ресурсов для выполнения этого действия: добавление пользователей

Эта ошибка может быть вызвана одной из следующих причин:

• Вы не являетесь владельцем организации, администратора коллекции проектов или администратора группы.
• Вы являетесь администратором проекта или команды, но политика "Разрешить администраторам команд и проектов приглашать новых пользователей" отключена.
• Вы являетесь администратором проекта или команды, который может пригласить новых пользователей, но вы пытаетесь назначить лицензию при приглашении нового пользователя. Администраторы проекта или команды не могут назначать лицензию новым пользователям. Любой новый приглашенный пользователь добавляется на уровне доступа по умолчанию для новых пользователей. Обратитесь к PCA, чтобы изменить уровень доступа к лицензии.

Graph API Azure DevOps возвращает пустой список, даже если мы знаем, что в организации есть служебные принципы.

API списка графов Azure DevOps может возвращать пустой список, даже если для возврата все еще есть больше страниц пользователей. continuationToken Используйте для итерации по спискам, и вы можете в конечном итоге найти страницу, на которой возвращаются субъекты-службы. continuationToken Если возвращается, это означает, что через API доступны дополнительные результаты. Хотя у нас есть планы улучшить эту логику, на данный момент возможно, что первые результаты X возвращают пустые.

TF401444. Войдите по крайней мере один раз как {tenantId'tenantId\servicePrincipalObjectId'} в веб-браузере, чтобы включить доступ к службе.

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

Связанные статьи

• Изучение примеров приложений
• Ознакомьтесь со справочной документацией по API разрешений принципов обслуживания
• Ознакомьтесь со справочником по Graph API для Service Principal