Управление личными маркерами доступа (PATs) с помощью REST API

Статья
10/24/2024

Azure DevOps Services

При работе с большим набором личных маркеров доступа (PATS) вы владеете, это может стать сложным для управления обслуживанием этих маркеров только с помощью пользовательского интерфейса.

С помощью API управления жизненным циклом личных маркеров доступа вы можете легко управлять маркерами, связанными с вашими организациями, используя автоматизированные процессы. Этот широкий набор API позволяет управлять pats, позволяя создавать новые PATs и обновлять или истекать срок действия существующих PAT.

В этой статье мы рассказываем, как настроить приложение, которое использует токен Microsoft Entra для проверки подлинности и PAT Lifecycle API для обработки вызовов. Если вы хотите просто просмотреть полный список доступных конечных точек, ознакомьтесь со справочником по API.

Необходимые компоненты

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

Проверка подлинности:
- Чтобы использовать API, выполните проверку подлинности с помощью маркера Microsoft Entra с помощью OAuth идентификатора Microsoft Entra. Дополнительные сведения см. в разделе проверки подлинности.
- У вас есть клиент Microsoft Entra с активной подпиской Azure.

Примечание.

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

Проверка подлинности с помощью токенов Microsoft Entra

В отличие от других API Azure DevOps Services, пользователи должны предоставить маркер доступа Microsoft Entra для использования этого API вместо PAT. Токены Microsoft Entra — это более безопасный механизм проверки подлинности, чем использование PATs. Учитывая возможность создания и отзыва PATS этого API, мы хотим убедиться, что такая мощная функциональность предоставляется только разрешенным пользователям.

Чтобы получить и обновить маркеры доступа Microsoft Entra, выполните следующие задачи:

Внимание

Решения "От имени приложения" (например, поток учетных данных клиента) и любой поток проверки подлинности, который не выдает маркер доступа Microsoft Entra, является недопустимым для использования с этим API. Если многофакторная проверка подлинности включена в клиенте Microsoft Entra, необходимо определенно использовать поток авторизации.

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

Чтобы вызвать API напрямую, предоставьте маркер доступа Microsoft Entra в качестве Bearer маркера в Authorization заголовке запроса. Дополнительные сведения и полный список доступных запросов см. в справочнике по API PAT.

В следующем разделе показано, как создать приложение, которое проверяет подлинность пользователя с помощью маркера доступа Microsoft Entra. Приложение использует библиотеку Библиотеки проверки подлинности Майкрософт (MSAL) и вызывает API управления жизненным циклом PAT.

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

Чтобы приступить к работе, ознакомьтесь с одним из следующих примеров:

Клонируйте пример приложения Python Flask и настройте его с помощью клиента и организации ADO
Создайте пример приложения в портал Azure для выбранного языка и настройте его для API управления жизненным циклом PAT

Клонирование веб-приложения Python Flask

Мы предоставили пример веб-приложения Python Flask для этого API, которое можно скачать на GitHub и настроить для использования с клиентом Microsoft Entra и организацией Azure DevOps. Пример приложения использует поток кода проверки подлинности MSAL для получения маркера доступа Microsoft Entra.

Внимание

Рекомендуется приступить к работе с примером веб-приложения Python Flask на GitHub, но если вы предпочитаете использовать другой язык или тип приложения, используйте параметр быстрого запуска для повторного создания эквивалентного тестового приложения.

После клонирования примера приложения следуйте инструкциям в репозитории README. ReadME объясняет, как зарегистрировать приложение в клиенте Microsoft Entra, настроить пример для использования клиента Microsoft Entra и запустить клонируемое приложение.

Создание приложения портал Azure краткого руководства

Вместо этого можно создать пример приложения с созданным кодом MSAL с помощью параметра быстрого запуска на странице приложения в портал Azure. Тестовое приложение быстрого запуска следует потоку кода авторизации, но делает это с конечной точкой API Microsoft Graph. Пользователям необходимо обновить конфигурацию приложения, чтобы указать конечную точку для API управления жизненным циклом PAT.

Чтобы следовать этому подходу, следуйте инструкциям по типу приложения, выбранному на домашней странице разработки документов Microsoft Entra ID. Мы рассмотрим следующий пример с приложением быстрого запуска Python Flask.

Пример. Начало работы с приложением быстрого запуска Python Flask

После регистрации приложения в клиенте Microsoft Entra с активной подпиской Azure перейдите к зарегистрированным приложениям в разделе "Идентификатор приложения Майкрософт ->Регистрация приложений" в портал Azure.
Выберите приложение и перейдите к разрешениям API.
Выберите "Добавить разрешение" и выберите Azure DevOps —> проверьте user_impersonation.> Выберите "Добавить разрешения".
Выберите краткое руководство.
Выберите тип приложения: для Python Flask выберите веб-приложение.
Выберите платформу приложения. Для работы с этим учебником выберите Python.
Убедитесь, что выполнены необходимые предварительные требования, а затем разрешите портал Azure внести необходимые изменения для настройки приложения. URL-адрес ответа — это URL-адрес перенаправления, заданный при создании приложения + "/getAToken".
Скачайте приложение быстрого запуска и извлеките файлы.
Установите требования к приложению и запустите приложение, чтобы убедиться, что у вас есть все необходимые зависимости. Приложение изначально настроено для попадания в конечную точку в API Microsoft Graph. Узнайте, как изменить эту конечную точку на базовую конечную точку API управления жизненным циклом PAT, следуя инструкциям по настройке в следующем разделе.

Настройка приложения быстрого запуска

После скачивания и установки приложения быстрого запуска пользователь настраивается для использования тестовой конечной точки API из Microsoft Graph. Измените созданный файл конфигурации, чтобы он вызвал API управления жизненным циклом PAT.

Совет

Мы используем коллекцию и организацию взаимозаменяемо в этих документах. Если для переменной конфигурации требуется имя коллекции, замените ее именем организации.

Сделайте следующее:

Обновление переменной конфигурации ENDPOINT до https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview API управления жизненным циклом PAT
Измените переменную конфигурации SCOPE на "499b84ac-1321-427f-aa17-267ca6975798/.default" , чтобы ссылаться на ресурс Azure DevOps и все его области.

В следующем примере показано, как мы сделали эту конфигурацию для приложения Python Flask для быстрого запуска Python Flask, созданного с помощью портал Azure в предыдущем разделе.

Следуйте инструкциям по защите секрета клиента, который изначально вставляется в файл конфигурации приложения в виде обычного текста. Рекомендуется удалить переменную обычного текста из файла конфигурации и использовать переменную среды или Azure KeyVault для защиты секрета приложения.

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

Внимание

Никогда не оставляйте секрет клиента обычного текста в рабочем коде приложения.

Пример. Настройка приложения Быстрого запуска Python Flask для API управления жизненным циклом PAT

После скачивания приложения быстрого запуска установите его зависимости и проверьте его запуск в вашей среде, откройте app_config.py файл в выбранном редакторе. Файл должен выглядеть следующим фрагментом кода; Для ясности комментарии, ссылающиеся на конфигурацию API Microsoft Graph по умолчанию, были удалены:

import os

CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

CLIENT_SECRET = "YOUR_CLIENT_SECRET_HERE" 
# Placeholder - for use ONLY during testing.
# In a production app, we recommend you use a more secure method of storing your secret,
# like Azure Key Vault. Or, use an environment variable as described in Flask's documentation:
# https://flask.palletsprojects.com/en/1.1.x/config/#configuring-from-environment-variables
# CLIENT_SECRET = os.getenv("CLIENT_SECRET")
# if not CLIENT_SECRET:
#     raise ValueError("Need to define CLIENT_SECRET environment variable")

AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"  # For multi-tenant app
# AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"

REDIRECT_PATH = "/getAToken"  
# Used for forming an absolute URL to your redirect URI.
# The absolute URL must match the redirect URI you set
# in the app's registration in the Azure portal.

ENDPOINT = 'https://graph.microsoft.com/v1.0/users'  

SCOPE = ["User.ReadBasic.All"]

SESSION_TYPE = "filesystem"  
# Specifies the token cache should be stored in server-side session

Обновите идентификатор клиента или секрет клиента для приложения с помощью идентификатора клиента регистрации приложения и секрета клиента. В рабочей среде обязательно защитите секрет клиента с помощью переменной среды, Azure KeyVault или переключения на сертификат.
```
CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

CLIENT_SECRET = "YOUR_CLIENT_SECRET_HERE" 
# Placeholder - for use ONLY during testing.
# In a production app, we recommend you use a more secure method of storing your secret.
```
Измените переменную на ENDPOINT URL-адрес коллекции Azure DevOps и конечную точку API. Например, для коллекции с именем TestCollection значение будет:
```
# Fill in the url to the user's ADO collection + the PAT lifecycle management API endpoint here

ENDPOINT = 'https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview'
```
Для коллекции с именем TestCollection эта конечная точка будет:
```
ENDPOINT = 'https://vssps.dev.azure.com/testCollection/_apis/Tokens/Pats?api-version=6.1-preview'
```
Измените SCOPE переменную, чтобы ссылаться на ресурс API Azure DevOps; символьная строка — это идентификатор ресурса ДЛЯ API Azure DevOps, а область .default — все области для этого идентификатора ресурса.
```
SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
```
Если приложение настроено для определенного клиента (а не мультитенантной конфигурации), используйте альтернативное значение переменной, добавив имя конкретного AUTHORITY клиента в "Enter_the_Tenant_Name_Here".
```
# For single-tenant app:
AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"

# For multi-tenant app:
AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"
```

Убедитесь, что окончательный app_config.py файл соответствует следующему, с CLIENT_ID, идентификатором клиента и URL-адресом коллекции. По соображениям безопасности убедитесь, что CLIENT_SECRET был перемещен в переменную среды, Azure KeyVault или переключился на сертификат для зарегистрированного приложения:

import os

CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

# Note that the CLIENT_SECRET has been removed and moved to an environment variable or Azure KeyVault

AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"  # For multi-tenant app
# AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"

REDIRECT_PATH = "/getAToken"  
# Used for forming an absolute URL to your redirect URI.
# The absolute URL must match the redirect URI you set in the app's registration in the Azure portal.

ENDPOINT = 'https://vssps.dev.azure.com/testCollection/_apis/Tokens/Pats?api-version=6.1-preview' 
# Used to configure user's collection URL and the desired API endpoint

SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
# Means "All scopes for the Azure DevOps API resource"

SESSION_TYPE = "filesystem"  
# Specifies the token cache should be stored in server-side session

Повторно запустите приложение, чтобы проверить, что вы можете ПОЛУЧИТЬ все маркеры PAT для запрашивающего пользователя. После проверки можно изменить содержимое 'app.py' и 'ms-identity-python-webapp-master\templates' каталог для поддержки отправки запросов на остальные конечные точки API управления жизненным циклом PAT. Пример приложения быстрого запуска Python Flask, которое было изменено для поддержки запросов ко всем конечным точкам API управления жизненным циклом PAT, см. в этом примере репозитория на сайте GitHub.

Автоматическое обновление маркера доступа Microsoft Entra

После правильной настройки приложения и получения маркера доступа пользователь может использоваться до часа. Код MSAL, предоставленный в обоих предыдущих примерах, автоматически обновляет маркер после истечения срока действия. Обновление маркера предотвращает повторного входа пользователя и получения нового кода авторизации. Однако пользователям может потребоваться снова войти через 90 дней после истечения срока действия маркера обновления.

Изучение API управления жизненным циклом PAT

В предыдущих примерах приложений GitHub и кратком руководстве приложение предварительно настроено для выполнения запросов с приобретенными токенами Microsoft Entra. Дополнительные сведения см. в документации по API Reference.

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

Вопрос. Почему необходимо выполнить проверку подлинности с помощью маркера Microsoft Entra? Почему ПЭТ недостаточно?

Ответ. С помощью этого API управления жизненным циклом PAT мы открыли возможность создавать новые PATs и отменять существующие PAT. В неправильных руках злоумышленники могут использовать этот API для создания нескольких точек входа в ресурсы Azure DevOps вашей организации. Применяя проверку подлинности Microsoft Entra, мы надеемся, что этот мощный API будет более безопасным для этого несанкционированного использования.

Вопрос. Нужно ли иметь клиент Microsoft Entra с активной подпиской Azure для использования этого API?

Ответ. К сожалению, этот API доступен только пользователям, которые являются частью клиента Microsoft Entra с активной подпиской Azure.

Вопрос. Можно ли получить пример этого примера приложения для другого языка или платформы или типа приложения?

Ответ. Мы любим, что вы хотите использовать API на выбранном языке! Если у вас есть запрос на пример, перейдите к нашему сообществу разработчиков, чтобы узнать, есть ли кто-то другой пример для совместного использования. Если у вас есть пример приложения, по которому вы хотите предоставить общий доступ к большей аудитории Azure DevOps, сообщите нам, и мы можем ознакомиться с этим документом более широко!

Вопрос. В чем разница между этим API токенов и API администратора маркеров?

Ответ. Этот API токена и API администратора маркеров, в то время как аналогичные, служат различным вариантам использования и аудиториям:

Этот API маркеров в основном предназначен для пользователей, которым требуется управлять paTs, принадлежащими им в автоматизированном конвейере. Этот API позволяет. Это дает возможность создавать новые маркеры и обновлять существующие.
API администратора маркеров предназначен для администраторов организации. Администраторы могут использовать этот API для получения и отмены авторизации OAuth, включая личные маркеры доступа (PATs) и самоописывание маркеров сеансов пользователей в своих организациях.

Вопрос. Как повторно создать или повернуть PATs через API? Я видел этот параметр в пользовательском интерфейсе, но в API не отображается аналогичный метод.

Ответ: Большой вопрос! Функция "Повторное создание", доступная в пользовательском интерфейсе, фактически выполняет несколько действий, которые полностью реплицируются через API.

Чтобы повернуть PAT, сделайте следующее:

Общие сведения о метаданных PAT с помощью вызова GET
Создайте новый PAT со старыми метаданными PAT с помощью вызова POST .
Отзыв старого PAT с помощью вызова DELETE

Вопрос. При попытке продолжить работу с этим приложением отображается всплывающее окно "Требуется утверждение администратора". Как использовать это приложение без утверждения администратора?

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

Вопрос. Почему я вижу ошибку, например "Субъекты-службы не разрешены для выполнения этого действия", когда я пытаюсь вызвать API управления жизненным циклом PAT с помощью субъекта-службы или управляемого удостоверения?

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

Следующие шаги

Сведения о конечных точках API управления жизненным циклом PAT

Поделиться через

Управление личными маркерами доступа (PATs) с помощью REST API

Необходимые компоненты

Проверка подлинности с помощью токенов Microsoft Entra

Клонирование веб-приложения Python Flask

Создание приложения портал Azure краткого руководства

Пример. Начало работы с приложением быстрого запуска Python Flask

Настройка приложения быстрого запуска

Пример. Настройка приложения Быстрого запуска Python Flask для API управления жизненным циклом PAT

Автоматическое обновление маркера доступа Microsoft Entra

Изучение API управления жизненным циклом PAT

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

Вопрос. Почему необходимо выполнить проверку подлинности с помощью маркера Microsoft Entra? Почему ПЭТ недостаточно?

Вопрос. Нужно ли иметь клиент Microsoft Entra с активной подпиской Azure для использования этого API?

Вопрос. Можно ли получить пример этого примера приложения для другого языка или платформы или типа приложения?

Вопрос. В чем разница между этим API токенов и API администратора маркеров?

Вопрос. Как повторно создать или повернуть PATs через API? Я видел этот параметр в пользовательском интерфейсе, но в API не отображается аналогичный метод.

Следующие шаги

Обратная связь

Дополнительные ресурсы