Авторизация доступа к REST API с помощью OAuth 2.0

Azure DevOps Services

Из этой статьи вы узнаете, как проверить подлинность пользователей веб-приложения для доступа к REST API, чтобы приложение не продолжало запрашивать имена пользователей и пароли.

Примечание

Следующее руководство предназначено для Azure DevOps Services пользователей, так как OAuth 2.0 не поддерживается в Azure DevOps Server. Клиентские библиотеки — это серия пакетов, созданных специально для расширения функциональных возможностей Azure DevOps Server. Для локальных пользователей рекомендуется использовать клиентские библиотеки, проверку подлинности Windows или личные маркеры доступа (PAT) для проверки подлинности от имени пользователя.

Azure DevOps Services использует протокол OAuth 2.0 для авторизации приложения для пользователя и создания маркера доступа. Используйте этот маркер при вызове REST API из приложения.

При вызове Azure DevOps Services API для этого пользователя используйте маркер доступа этого пользователя. Срок действия маркеров доступа истекает, поэтому обновите маркер доступа, если срок его действия истек.

Процесс получения авторизации.

Пример C# общего потока см. в примерах vsts-auth-samples.

Примечание

Вы можете зарегистрировать приложение в экземпляре Azure Active Directory (Azure AD). Дополнительные сведения см. в разделе проверки подлинности OAuth 2.0 с помощью протокола Azure AD и OpenID Connect.

1. Регистрация приложения

  1. Перейдите к https://app.vsaex.visualstudio.com/app/register регистрации приложения.

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

  3. Выберите "Создать приложение".

    Откроется страница параметров приложения.

    Снимок экрана: параметры приложений для приложения.

    • Когда Azure DevOps Services представляет пользователю страницу утверждения авторизации, она использует название вашей компании, имя приложения и описания. Он также использует URL-адреса веб-сайта компании, веб-сайта приложения, а также условия обслуживания и заявления о конфиденциальности.

      Снимок экрана: страница авторизации Visual Studio Codespaces со сведениями о компании и приложении.

    • Когда Azure DevOps Services запрашивает авторизацию пользователя и предоставляет его, браузер пользователя перенаправляется на URL-адрес обратного вызова авторизации с кодом авторизации. URL-адрес обратного вызова должен быть безопасным подключением (https), чтобы передать код обратно в приложение и точно совпадать с URL-адресом, зарегистрированным в приложении. Если это не так, отображается страница ошибки 400 вместо страницы с просьбой предоставить пользователю авторизацию вашему приложению.

  4. Вызовите URL-адрес авторизации и передайте идентификатор приложения и авторизованные области, если вы хотите, чтобы пользователь авторизировал приложение для доступа к своей организации. Вызовите URL-адрес маркера доступа, если вы хотите получить маркер доступа для вызова Azure DevOps Services REST API.

Параметры каждого зарегистрированного приложения доступны в профиле https://app.vssps.visualstudio.com/profile/view.

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

  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 GUID Идентификатор, назначенный приложению при регистрации.
response_type строка Assertion
Состояние строка Может быть любым значением. Как правило, созданное строковое значение, которое сопоставляет обратный вызов со связанной авторизацией. Запрос.
область строка Области, зарегистрированные в приложении. Пространство разделено. См. доступные области.
redirect_uri URL-адрес URL-адрес обратного вызова для приложения. Должен точно совпадать с URL-адресом, зарегистрированным в приложении.
  1. Добавьте ссылку или кнопку на сайт, который принимает пользователя в конечную точку авторизации Azure DevOps Services:
https://app.vssps.visualstudio.com/oauth2/authorize
        ?client_id=88e2dd5f-4e34-45c6-a75d-524eb2a0399e
        &response_type=Assertion
        &state=User1
        &scope=vso.work%20vso.code_write
        &redirect_uri=https://fabrikam.azurewebsites.net/myapp/oauth-callback

Azure DevOps Services просит пользователя авторизовать приложение.

Если пользователь принимает это, Azure DevOps Services перенаправляет браузер пользователя по URL-адресу обратного вызова, включая код авторизации с коротким сроком действия и значение состояния, указанное в URL-адресе авторизации:

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

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

Используйте код авторизации для запроса маркера доступа (и маркера обновления) для пользователя. Служба должна выполнить HTTP-запрос между службами для Azure DevOps Services.

URL-адрес — авторизация приложения

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

Заголовки HTTP-запросов — авторизация приложения

Заголовок Значение
Content-Type application/x-www-form-urlencoded
Content-Length Вычисляемая длина строки текста запроса (см. следующий пример)
Content-Type: application/x-www-form-urlencoded
Content-Length: 1322

Текст HTTP-запроса — авторизация приложения

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-адрес в кодировке "код", предоставленный code с помощью параметра запроса для 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 }
}

Важно!

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

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

Чтобы использовать маркер доступа, добавьте его в качестве маркера носителя в заголовок авторизации HTTP-запроса:

Authorization: Bearer {access_token}

Например, HTTP-запрос для получения последних сборок для проекта:

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

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

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

URL-адрес — маркер обновления

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

Заголовки HTTP-запросов — маркер обновления

Заголовок Значение
Content-Type application/x-www-form-urlencoded
Content-Length Вычисляемая длина строки текста запроса (см. следующий пример)
Content-Type: application/x-www-form-urlencoded
Content-Length: 1654

Текст HTTP-запроса — маркер обновления

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": { access token for this user },
    "token_type": { type of token },
    "expires_in": { time in seconds that the token remains valid },
    "refresh_token": { new refresh token to use when the token has timed out }
}

Важно!

Новый маркер обновления выдается для пользователя. Сохраните этот новый маркер и используйте его при следующем получении нового маркера доступа для пользователя.

Области действия

Важно!

Области разрешают доступ только к REST API и выбирают конечные точки Git. Доступ к API SOAP не поддерживается.

Категория Область Имя Описание
Пулы агентов vso.agentpools Пулы агентов (чтение) Предоставляет возможность просмотра задач, пулов, очередей, агентов и текущих или недавно выполненных заданий для агентов.
vso.agentpools_manage Пулы агентов (чтение, управление) Предоставляет возможность управлять пулами, очередями и агентами.
vso.environment_manage Среда (чтение, управление) Предоставляет возможность управлять пулами, очередями, агентами и средами.
Аналитика vso.analytics Аналитика (чтение) Предоставляет возможность запрашивать аналитические данные.
Журнал аудита vso.auditlog Журнал аудита (чтение) Предоставляет пользователям возможность считывать журнал аудита.
Сборка vso.build Сборка (чтение) Предоставляет возможность доступа к артефактам сборки, включая результаты сборки, определения и запросы, а также возможность получать уведомления о событиях сборки с помощью обработчиков служб.
vso.build_execute Сборка (чтение и выполнение) Предоставляет возможность доступа к артефактам сборки, включая результаты сборки, определения и запросы, а также возможность постановки в очередь сборки, обновления свойств сборки и возможность получать уведомления о событиях сборки с помощью перехватчиков служб.
Код vso.code Код (чтение) Предоставляет возможность считывать исходный код и метаданные о фиксациях, наборах изменений, ветвях и других артефактах управления версиями. Кроме того, предоставляет возможность поиска кода и получения уведомлений о событиях управления версиями с помощью обработчиков служб.
vso.code_write Код (чтение и запись) Предоставляет возможность чтения, обновления и удаления исходного кода, доступа к метаданным о фиксациях, наборах изменений, ветвях и других артефактах управления версиями. Кроме того, предоставляет возможность создавать запросы на вытягивание и проверки кода и управлять ими, а также получать уведомления о событиях управления версиями с помощью обработчиков служб.
vso.code_manage Код (чтение, запись и управление ими) Предоставляет возможность чтения, обновления и удаления исходного кода, доступа к метаданным о фиксациях, наборах изменений, ветвях и других артефактах управления версиями. Кроме того, предоставляет возможность создавать репозитории кода и управлять ими, создавать запросы на вытягивание и проверки кода, а также получать уведомления о событиях управления версиями через обработчики служб.
vso.code_full Код (полный) Предоставляет полный доступ к исходному коду, метаданным о фиксациях, наборах изменений, ветвях и других артефактах управления версиями. Кроме того, предоставляет возможность создавать репозитории кода и управлять ими, создавать запросы на вытягивание и проверки кода, а также получать уведомления о событиях управления версиями через обработчики служб. Также включает ограниченную поддержку КЛИЕНТСКИх API-интерфейсов OM.
vso.code_status Код (состояние) Предоставляет возможность чтения и записи состояния фиксации и запроса на вытягивание.
Объемы обслуживания vso.entitlements Права (чтение) Предоставляет доступ только для чтения к конечной точке лицензирования для получения прав учетной записи.
vso.memberentitlementmanagement Управление MemberEntitlement (чтение) Предоставляет возможность читать пользователей, их лицензии, а также проекты и расширения, к которые они могут получить доступ.
vso.memberentitlementmanagement_write Управление MemberEntitlement (запись) Предоставляет возможность управлять пользователями, их лицензиями, а также проектами и расширениями, к которым они могут получить доступ.
Расширения vso.extension Расширения (чтение) Предоставляет возможность чтения установленных расширений.
vso.extension_manage Расширения (чтение и управление) Предоставляет возможность устанавливать, удалять и выполнять другие административные действия с установленными расширениями.
vso.extension.data Данные расширения (чтение) Предоставляет возможность считывать данные (параметры и документы), хранящиеся в установленных расширениях.
vso.extension.data_write Данные расширения (чтение и запись) Предоставляет возможность чтения и записи данных (параметров и документов), хранящихся в установленных расширениях.
Удостоверение графа & vso.graph Graph (чтение) Предоставляет возможность считывать сведения о членстве пользователей, групп, областей и групп.
vso.graph_manage Graph (управление) Предоставляет возможность читать сведения о членстве пользователей, групп, областей и групп, а также добавлять пользователей, группы и управлять членством в группах.
vso.identity Удостоверение (чтение) Предоставляет возможность чтения удостоверений и групп.
vso.identity_manage Удостоверение (управление) Предоставляет возможность чтения, записи и управления удостоверениями и группами.
Загрузить тест vso.loadtest Нагрузочный тест (чтение) Предоставляет возможность считывать запуски нагрузочного теста, результаты тестирования и артефакты APM.
vso.loadtest_write Нагрузочный тест (чтение и запись) Предоставляет возможность создавать и обновлять запуски нагрузочных тестов, а также считывать метаданные, включая результаты теста и артефакты APM.
Группа компьютеров vso.machinegroup_manage Группа развертывания (чтение, управление) Предоставляет возможность управления группами развертывания и пулами агентов.
Marketplace vso.gallery Marketplace Предоставляет доступ на чтение общедоступным и частным элементам и издателям.
vso.gallery_acquire Marketplace (приобретение) Предоставляет доступ на чтение и возможность получения элементов.
vso.gallery_publish Marketplace (публикация) Предоставляет доступ на чтение и возможность отправки, обновления и предоставления общего доступа к элементам.
vso.gallery_manage Marketplace (управление) Предоставляет доступ на чтение и возможность публикации элементов и издателей и управления ими.
Уведомления vso.notification Уведомления (чтение) Предоставляет доступ на чтение к подпискам и метаданным событий, включая фильтруемые значения полей.
vso.notification_write Уведомления (запись) Предоставляет доступ на чтение и запись к подпискам и доступ на чтение к метаданным событий, включая фильтруемые значения полей.
vso.notification_manage Уведомления (управление) Предоставляет доступ на чтение, запись и управление подписками и доступ на чтение к метаданным событий, включая фильтруемые значения полей.
vso.notification_diagnostics Уведомления (диагностика) Предоставляет доступ к журналам диагностики, связанным с уведомлениями, и позволяет включить диагностику для отдельных подписок.
Упаковка vso.packaging Упаковка (чтение) Предоставляет возможность чтения веб-каналов и пакетов.
vso.packaging_write Упаковка (чтение и запись) Предоставляет возможность создавать и читать веб-каналы и пакеты.
vso.packaging_manage Упаковка (чтение, запись и управление) Предоставляет возможность создавать, читать, обновлять и удалять веб-каналы и пакеты.
Проект и команда vso.project Проект и команда (чтение) Предоставляет возможность читать проекты и команды.
vso.project_write Проект и команда (чтение и запись) Предоставляет возможность читать и обновлять проекты и команды.
vso.project_manage Проект и команда (чтение, запись и управление) Предоставляет возможность создавать, читать, обновлять и удалять проекты и команды.
Выпуск vso.release Выпуск (чтение) Предоставляет возможность считывать артефакты выпуска, включая выпуски, определения выпусков и среду выпуска.
vso.release_execute Выпуск (чтение, запись и выполнение) Предоставляет возможность считывать и обновлять артефакты выпуска, включая выпуски, определения выпусков и среду выпуска, а также возможность постановки в очередь нового выпуска.
vso.release_manage Выпуск (чтение, запись, выполнение и управление) Предоставляет возможность считывания, обновления и удаления артефактов выпуска, включая выпуски, определения выпусков и среду выпуска, а также возможность очереди и утверждения нового выпуска.
Безопасность vso.security_manage Безопасность (управление) Предоставляет возможность чтения, записи и управления разрешениями безопасности.
Подключения службы vso.serviceendpoint Конечные точки службы (чтение) Предоставляет возможность чтения конечных точек службы.
vso.serviceendpoint_query Конечные точки службы (чтение и запрос) Предоставляет возможность чтения и запроса конечных точек службы.
vso.serviceendpoint_manage Конечные точки службы (чтение, запрос и управление) Предоставляет возможность чтения, запроса и управления конечными точками службы.
Параметры vso.settings Параметры (чтение) Предоставляет возможность чтения параметров.
vso.settings_write Параметры (чтение и запись) Предоставляет возможность создавать и читать параметры.
Символы vso.symbols Символы (чтение) Предоставляет возможность чтения символов.
vso.symbols_write Символы (чтение и запись) Предоставляет возможность чтения и записи символов.
vso.symbols_manage Символы (чтение, запись и управление) Предоставляет возможность чтения, записи и управления символами.
Группы задач vso.taskgroups_read Группы задач (чтение) Предоставляет возможность чтения групп задач.
vso.taskgroups_write Группы задач (чтение, создание) Предоставляет возможность чтения и создания групп задач.
vso.taskgroups_manage Группы задач (чтение, создание и управление) Предоставляет возможность чтения, создания групп задач и управления ими.
Панель мониторинга группы vso.dashboards Панели мониторинга группы (чтение) Предоставляет возможность считывать сведения о панели мониторинга группы.
vso.dashboards_manage Панели мониторинга группы (управление) Предоставляет возможность управлять сведениями панели мониторинга группы.
Управление тестами vso.test Управление тестированием (чтение) Предоставляет возможность считывать планы тестирования, варианты, результаты и другие артефакты, связанные с управлением тестами.
vso.test_write Управление тестированием (чтение и запись) Предоставляет возможность читать, создавать и обновлять планы тестирования, варианты, результаты и другие артефакты, связанные с управлением тестами.
Лексемы vso.tokens Делегированные маркеры авторизации Предоставляет пользователям возможность управлять делегированными маркерами авторизации.
vso.tokenadministration Администрирование маркеров Предоставляет возможность управлять существующими токенами (просматривать и отзывать) администраторам организации.
Профиль пользователя vso.profile Профиль пользователя (чтение) Предоставляет возможность считывания профиля, учетных записей, коллекций, проектов, команд и других артефактов организации верхнего уровня.
vso.profile_write Профиль пользователя (запись) Предоставляет возможность записи в профиль.
Группы переменных vso.variablegroups_read Группы переменных (чтение) Предоставляет возможность чтения групп переменных.
vso.variablegroups_write Группы переменных (чтение, создание) Предоставляет возможность чтения и создания групп переменных.
vso.variablegroups_manage Группы переменных (чтение, создание и управление) Предоставляет возможность чтения, создания групп переменных и управления ими.
Вики vso.wiki Вики-сайт (чтение) Предоставляет возможность читать вики-страницы, вики-страницы и вики-вложения. Кроме того, предоставляет возможность поиска на вики-страниц.
vso.wiki_write Вики-сайт (чтение и запись) Предоставляет возможность читать, создавать и обновлять вики-страницы, вики-страницы и вики-вложения.
Рабочие элементы vso.work Рабочие элементы (чтение) Предоставляет возможность считывания рабочих элементов, запросов, досок, областей и итераций, а также других связанных метаданных отслеживания рабочих элементов. Кроме того, предоставляет возможность выполнять запросы, искать рабочие элементы и получать уведомления о событиях рабочих элементов через перехватчики службы.
vso.work_write Рабочие элементы (чтение и запись) Предоставляет возможность считывать, создавать и обновлять рабочие элементы и запросы, обновлять метаданные доски, области чтения и итерации пути к другим связанным метаданным, выполнять запросы и получать уведомления о событиях рабочих элементов через перехватчики службы.
vso.work_full Рабочие элементы (полные) Предоставляет полный доступ к рабочим элементам, запросам, невыполненной работе, планам и метаданным отслеживания рабочих элементов. Кроме того, предоставляет возможность получать уведомления о событиях рабочих элементов с помощью перехватчиков служб.

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

Дополнительные сведения см. в разделе "Создание отслеживания и вложений рабочих элементов".

Примеры

Пример C#, реализующий OAuth для вызова Azure DevOps Services REST API, можно найти в нашем примере OAuth GitHub C#.

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

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

Ответ. Нет. Azure DevOps Services поддерживает только поток веб-сервера, поэтому невозможно реализовать OAuth, так как вы не можете безопасно хранить секрет приложения.

Вопрос. Какие ошибки или особые условия необходимо обрабатывать в коде?

Ответ. Убедитесь, что вы обрабатываете следующие условия:

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

Вопрос. Я хочу выполнить локальную отладку веб-приложения. Можно ли использовать localhost для URL-адреса обратного вызова при регистрации приложения?

Ответ. Да. Azure DevOps Services теперь разрешает localhost в URL-адресе обратного вызова. Убедитесь, что вы используете https://localhost в качестве начала URL-адреса обратного вызова при регистрации приложения.

Вопрос. При попытке получить маркер доступа возникает ошибка HTTP 400. Что может быть неправильно?

Ответ. Убедитесь, что для типа контента задано значение application/x-www-form-urlencoded в заголовке запроса.

Вопрос. При использовании маркера доступа на основе OAuth возникает ошибка HTTP 401, но PAT с той же областью работает нормально. Почему?

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

В этом сценарии поток для авторизации приложения и создания маркера доступа работает, но все REST API возвращают только ошибку, например TF400813: The user "<GUID>" is not authorized to access this resource.

Вопрос. Можно ли использовать OAuth с конечными точками SOAP и REST API?

Ответ. Нет. OAuth поддерживается только в REST API на данный момент.

Вопрос. Как получить сведения о вложениях для рабочего элемента с помощью REST API Azure DevOps?

Ответ. Сначала получите сведения о рабочем элементе с помощью рабочих элементов— REST API получения рабочих элементов :

GET https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id}

Чтобы получить сведения о вложениях, необходимо добавить следующий параметр в URL-адрес:

$expand=all

С результатами вы получите свойство связей. Здесь можно найти URL-адрес вложений, а в URL-адресе можно найти идентификатор. Пример:

$url = https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/434?$expand=all&api-version=5.0

$workItem = Invoke-RestMethod -Uri $url -Method Get -ContentType application/json

$split = ($workitem.relations.url).Split('/')

$attachmentId = $split[$split.count - 1]

# Result: 1244nhsfs-ff3f-25gg-j64t-fahs23vfs