Авторизация доступа к 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. Регистрация приложения
Перейдите к
https://app.vsaex.visualstudio.com/app/registerрегистрации приложения.Выберите области , необходимые приложению, а затем используйте те же области при авторизации приложения. Если вы зарегистрировали приложение с помощью API предварительной версии, повторно зарегистрируйтесь, так как используемые области теперь устарели.
Выберите "Создать приложение".
Откроется страница параметров приложения.
Когда Azure DevOps Services представляет пользователю страницу утверждения авторизации, она использует название вашей компании, имя приложения и описания. Он также использует URL-адреса веб-сайта компании, веб-сайта приложения, а также условия обслуживания и заявления о конфиденциальности.
Когда Azure DevOps Services запрашивает авторизацию пользователя и предоставляет его, браузер пользователя перенаправляется на URL-адрес обратного вызова авторизации с кодом авторизации. URL-адрес обратного вызова должен быть безопасным подключением (https), чтобы передать код обратно в приложение и точно совпадать с URL-адресом, зарегистрированным в приложении. Если это не так, отображается страница ошибки 400 вместо страницы с просьбой предоставить пользователю авторизацию вашему приложению.
Вызовите URL-адрес авторизации и передайте идентификатор приложения и авторизованные области, если вы хотите, чтобы пользователь авторизировал приложение для доступа к своей организации. Вызовите URL-адрес маркера доступа, если вы хотите получить маркер доступа для вызова Azure DevOps Services REST API.
Параметры каждого зарегистрированного приложения доступны в профиле https://app.vssps.visualstudio.com/profile/view.
2. Авторизация приложения
- Если пользователь еще не предоставил приложению доступ к своей организации, вызовите 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-адресом, зарегистрированным в приложении. |
- Добавьте ссылку или кнопку на сайт, который принимает пользователя в конечную точку авторизации 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