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

Статья
10/23/2023

Azure DevOps Services

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

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

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

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

Чтобы использовать API, необходимо пройти проверку подлинности с помощью маркера Microsoft Entra, который можно сделать через OAuth идентификатора Microsoft Entra. Дополнительные сведения о том, как это сделать, см. в следующем разделе проверки подлинности.

Для этого необходимо выполнить несколько предварительных требований:

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

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

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

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

Важно!

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

Внимание

Наличие клиента Microsoft Entra с активной подпиской Azure является обязательным условием для использования этого API.

После того как у вас есть приложение с рабочим потоком проверки подлинности для обработки маркеров 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 перейдите к зарегистрированным приложениям в разделе "Регистрация приложений Microsoft Entra"> в портал 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 и отменять существующие PATs. В неправильных руках этот API может использоваться злоумышленниками для создания нескольких точек входа в ресурсы ADO вашей организации. Применяя проверку подлинности 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