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

Azure DevOps Services

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

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

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

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

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

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

• Использование клиента Microsoft Entra с активной подпиской Azure
• Регистрация приложения в клиенте Microsoft Entra
• Добавление разрешений Azure DevOps в приложение
• Получение согласия от администратора клиента. В зависимости от политик безопасности клиента ваше приложение может потребовать разрешения на доступ к ресурсам в организации. Попросите администратора клиента предоставить приложению разрешение на его использование в клиенте.

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

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

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

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

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

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

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

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

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

1. После регистрации вашего приложения в клиенте Microsoft Entra с активной подпиской Azure перейдите к вашему зарегистрированному приложению в разделе Microsoft Entra ID ->Регистрация приложений на портале Azure .

   

2. Выберите приложение и перейдите к разрешениям API.

   

3. Выберите Добавить разрешение и выберите Azure DevOps —> выберите необходимые области. В этом случае API управления жизненным циклом PAT поддерживают только user_impersonation, но другие API могут запрашивать другие более детализированные области, которые можно найти на отдельной справочной странице каждого API. После выбора всех областей доступа щелкните Добавить разрешения.

   

4. Выберите краткое руководство.

5. Выберите тип приложения: для Python Flask выберите веб-приложение.

6. Выберите платформу приложения. Для работы с этим учебником выберите Python.

7. Убедитесь, что выполнены необходимые предварительные требования, а затем разрешите портал Azure внести необходимые изменения для настройки приложения. URL-адрес ответа — это URL-адрес перенаправления, заданный при создании приложения + "/getAToken".

   

8. Скачайте приложение быстрого запуска и извлеките файлы.

   

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

   

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

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

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

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

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

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

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

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

2. Обновите идентификатор клиента или секрет клиента для приложения с помощью идентификатора клиента регистрации приложения и секрета клиента. В рабочей среде обязательно защитите секрет клиента с помощью переменной среды, 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.
   

3. Измените переменную на 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'
   

4. Измените SCOPE переменную, чтобы ссылаться на ресурс API Azure DevOps; символьная строка — это идентификатор ресурса ДЛЯ API Azure DevOps, а область .default — все области для этого идентификатора ресурса.

   SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
   

5. Если приложение настроено для определенного клиента (а не мультитенантной конфигурации), используйте альтернативное значение переменной, добавив имя конкретного 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"
   

6. Убедитесь, что окончательный 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
   

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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