Использование Azure DevOps OAuth 2.0

Azure DevOps Services

В этой статье объясняется, как работает Azure DevOps OAuth 2.0 для существующих приложений и предоставляет рекомендации по обслуживанию и переносу приложений.

Обзор

Azure DevOps OAuth 2.0 позволяет приложениям получать доступ к ресурсам Azure DevOps от имени пользователей. Хотя эта служба не рекомендуется, существующие приложения продолжают работать до 2026 года.

Рекомендация по миграции: Начните планировать миграцию на Microsoft Entra ID OAuth, чтобы обеспечить постоянную службу и доступ к расширенным функциям безопасности.

Предпосылки

Прежде чем работать с приложениями OAuth Azure DevOps, выполните приведенные выше действия.

Работа с существующими приложениями OAuth Azure DevOps

1. Управление существующей регистрацией приложения

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

1. Перейдите к профилю Visual Studio , чтобы получить доступ к регистрации приложений.

2. Просмотрите настроенные области и убедитесь, что они соответствуют потребностям приложения.

3. Проверьте конфигурацию URL-адреса обратного вызова и при необходимости обновите его.

   

4. Запланируйте план миграции на OAuth идентификатора Microsoft Entra ID до срока прекращения поддержки в 2026 году.

2. Авторизация приложения

Поток авторизации остается неизменным для существующих приложений OAuth Azure DevOps:

1. Перенаправьте пользователей на URL-адрес авторизации с параметрами приложения:

   https://app.vssps.visualstudio.com/oauth2/authorize
           ?client_id={app ID}
           &response_type=Assertion
           &state={state}
           &scope={scope}
           &redirect_uri={callback URL}
   

   Параметр	Тип	Описание
   client_id	ГУИД	Идентификатор, назначенный приложению при регистрации
   response_type	строка	Должен содержать значение Assertion.
   state	строка	Созданное строковое значение, которое сопоставляет обратный вызов с запросом авторизации
   scope	строка	Области, разделенные пробелами, зарегистрированные в приложении. См. доступные области видимости
   redirect_uri	URL-адрес	URL-адрес обратного вызова для приложения. Должен точно совпадать с URL-адресом, зарегистрированным в приложении

   Пример URL-адреса авторизации:

   https://app.vssps.visualstudio.com/oauth2/authorize
           ?client_id=00001111-aaaa-2222-bbbb-3333cccc4444
           &response_type=Assertion
           &state=User1
           &scope=vso.work%20vso.code_write
           &redirect_uri=https://fabrikam.azurewebsites.net/myapp/oauth-callback
   

   После авторизации пользователя Azure DevOps перенаправляется на URL-адрес обратного вызова с кодом авторизации:

   https://fabrikam.azurewebsites.net/myapp/oauth-callback
           ?code={authorization code}
           &state=User1
   

3. Обменять код авторизации на токен доступа

Используйте код авторизации для запроса токена доступа и токена обновления.

Сведения о запросе

URL-адрес

POST https://app.vssps.visualstudio.com/oauth2/token

Заголовки

Content-Type: application/x-www-form-urlencoded

текст запроса

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={1}&redirect_uri={2}

Подстановка параметров:

• {0}: секрет клиента, закодированный в формате URL, при регистрации приложения
• {1}: код авторизации в кодировке URL из обратного вызова
• {2}: URL-адрес обратного вызова, зарегистрированный в приложении

Пример реализации C#

public string GenerateRequestPostData(string appSecret, string authCode, string callbackUrl)
{
   return String.Format("client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion={1}&redirect_uri={2}",
               HttpUtility.UrlEncode(appSecret),
               HttpUtility.UrlEncode(authCode),
               callbackUrl
        );
}

Ответ

{
    "access_token": "{ access token for the user }",
    "token_type": "{ type of token }",
    "expires_in": "{ time in seconds that the token remains valid }",
    "refresh_token": "{ refresh token to use to acquire a new access token }"
}

4. Использование маркера доступа

Включите токен доступа как Bearer токен в ваши API-запросы.

Формат заголовка авторизации:

Authorization: Bearer {access_token}

Пример запроса API:

GET https://dev.azure.com/myaccount/myproject/_apis/build-release/builds?api-version=3.0
Authorization: Bearer {access_token}

5. Обновление маркеров доступа с истекшим сроком действия

После истечения срока действия маркеров доступа используйте маркер обновления для получения нового маркера доступа:

Просьба:

POST https://app.vssps.visualstudio.com/oauth2/token
Content-Type: application/x-www-form-urlencoded
Content-Length: 1654

client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={0}&grant_type=refresh_token&assertion={1}&redirect_uri={2}

Подстановка параметров:

• {0}: секрет клиента в кодировке URL
• {1}: маркер обновления, закодированный URL-адресом
• {2}: URL-адрес обратного вызова, зарегистрированный в приложении

Ответ.

{
    "access_token": "{ new access token }",
    "token_type": "{ type of token }",
    "expires_in": "{ time in seconds that the token remains valid }",
    "refresh_token": "{ new refresh token }"
}

Примеры кода

Примеры работы можно найти в нашем репозитории примеров проверки подлинности Azure DevOps.

Управление секретами приложений

Приложения OAuth Azure DevOps поддерживают двойные ключи для обеспечения ротации без простоя.

Ротация секретов

1. Создайте новый секрет в профиле Visual Studio или через API секрета регистрации.

   

2. Подтвердите действие в модальном диалоговом окне.

   

3. Обновите приложение , чтобы использовать новый секрет до истечения срока действия старого.

4. Тщательно проверьте новый секрет до истечения срока действия старого секрета.

5. Повторите процесс , когда срок действия нового секрета приближается к истечении срока действия.

Отмена секретного реагирования на чрезвычайные ситуации

Если секрет скомпрометирован:

1. Немедленно перегенерируйте секрет в вашем профиле.
2. Обновите приложение с помощью нового секрета.
3. Отслеживайте несанкционированный доступ в журналах приложений.

Удаление приложения

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

1. Перейдите к профилю Visual Studio.

2. Выберите нужного арендатора из раскрывающегося списка.

3. Найдите приложение в разделе "Приложения и службы".

4. Выберите "Удалить " на странице регистрации приложения.

   

5. Подтвердите удаление в модальном диалоговом окне.

После удаления приложение и все его маркеры немедленно перестают работать.

Планирование миграции

Контрольный список действий по миграции

• [ ] Ознакомьтесь с документацией по OAuth для идентификатора Microsoft Entra ID
• [ ] Определение всех приложений с помощью Azure DevOps OAuth в вашей организации
• [ ] Планирование временной шкалы миграции , позволяющей достаточное время тестирования
• [ ] Обновление архитектуры приложения для поддержки OAuth идентификатора Microsoft Entra
• [ ] Тестирование миграции в непроизводственных средах
• [ ] Обмен данными об изменениях для пользователей и заинтересованных лиц
• [ ] Завершение миграции до крайнего срока 2026 г.

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

Расширенные функции безопасности:

• Поддержка многофакторной проверки подлинности
• Политики условного доступа
• Расширенная защита от угроз
• Интеграция идентификаций предприятия

Лучший интерфейс разработчика:

• Современные библиотеки проверки подлинности (MSAL)
• Согласованная платформа удостоверений в службах Майкрософт
• Улучшено управление маркерами и кэширование

Долгосрочная поддержка:

• Продолжение инвестирования и разработки функций
• Функции соответствия и управления предприятиями

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

Вопрос. Могу ли я создать новые приложения OAuth для Azure DevOps?

Ответ. Нет. Новые регистрации приложений остановились в апреле 2025 года. Используйте идентификатор Microsoft Entra ID OAuth для новых приложений.

Вопрос. Когда мое существующее приложение Azure DevOps OAuth перестанет работать?

A: Существующие приложения продолжают функционировать до тех пор, пока Azure DevOps OAuth полностью не устарели в 2026 году. Запланируйте миграцию до этого крайнего срока.

Вопрос. Можно ли использовать OAuth с мобильными приложениями?

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

Вопрос. Что делать, если при запросе токенов возникает ошибка HTTP 400?

Ответ. Распространенные причины:

• Неправильный Content-Type заголовок (должен быть application/x-www-form-urlencoded)
• Неправильные параметры текста запроса
• Недопустимый или просроченный код авторизации
• НЕсогласованный URL-адрес обратного вызова

Вопрос: Почему возникают ошибки HTTP 401 с токенами OAuth, но не с PAT?

Ответ. Проверьте, отключен ли администратор вашей организации доступ к сторонним приложениям через OAuth по адресу: https://dev.azure.com/{your-org-name}/_settings/organizationPolicy

При отключении потоки авторизации OAuth работают, но вызовы API возвращаются TF400813: The user "<GUID>" is not authorized to access this resource.

Вопрос. Можно ли использовать localhost для тестирования?

Ответ. Да. Azure DevOps OAuth поддерживает https://localhost URL-адреса обратного вызова для локальной разработки и тестирования.

Вопрос: Как обрабатывать отказы и аннулирование авторизации?

Ответ. Реализуйте правильную обработку ошибок для:

• Отказ в авторизации: код авторизации не возвращается в обратном вызове
• Отозванная авторизация: вызовы API возвращают ошибки 401; повторная авторизация от пользователя

Вопрос: В чем разница между OAuth Azure DevOps и Microsoft Entra ID OAuth?

A.

• Azure DevOps OAuth: устарело, Azure DevOps, ограниченные функции безопасности
• Идентификатор Microsoft Entra ID OAuth: современный, корпоративный уровень, улучшенная безопасность, долгосрочная поддержка

Дальнейшие шаги

Для существующих приложений:

Для новых приложений:

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

• Выбор метода проверки подлинности
• Миграция на OAuth с идентификатором Microsoft Entra
• Просмотр областей OAuth 2.0 для Azure DevOps
• Управление авторизацией приложений
• Изучите справочник по REST API Azure DevOps
• Сведения о безопасности и удостоверении в Azure DevOps