OAuth

Вы просматриваете документацию Apigee Edge .
Перейдите к документации Apigee X. информация

OAuth стал ведущим протоколом авторизации для API. Версия OAuth, подробно описанная в этом разделе, определяется в Спецификация OAuth 2.0 .

OAuth — это протокол, который позволяет конечным пользователям приложений разрешать приложениям действовать от их имени. Приложения делают это, получая токены доступа от поставщиков API . Поставщик API проверяет подлинность учетных данных конечного пользователя приложения, гарантирует, что пользователь авторизовал приложение, а затем выдает токен доступа к приложению. Когда приложение использует защищенный API, Apigee Edge проверяет токен доступа, чтобы убедиться, что он действителен и не истек срок его действия. Как поставщику API вам необходимо предоставить конечные точки, которые позволяют приложениям получать токены доступа.

Чтобы облегчить вам начало использования OAuth, Apigee Edge позволяет вам настраивать и применять OAuth с помощью политик , не требуя от вас написания какого-либо кода. В этом разделе вы узнаете, как защитить свои API, как получить токены доступа и как использовать эти токены доступа для доступа к защищенным API.

Конфигурация OAuth по умолчанию для вашей организации.

Для удобства все организации в Apigee Edge предварительно настроены с набором конечных точек OAuth 2.0, которые реализуют тип предоставления учетных данных клиента . Тип предоставления учетных данных клиента определяет процедуру выдачи токенов доступа в обмен на учетные данные приложения . Эти учетные данные приложения представляют собой просто пару потребительского ключа и секрета, которую Apigee Edge выдает для каждого приложения, зарегистрированного в организации. «Учетные данные клиента» относятся к самой паре ключа потребителя и секрета.

Дополнительные сведения о выдаче учетных данных приложениям с помощью Edge Developer Services см. в разделе Регистрация приложений и управление ключами .

По этой причине относительно просто «улучшить» вашу схему безопасности API от проверки ключа API до учетных данных клиента OAuth. Обе схемы используют один и тот же потребительский ключ и секрет для проверки клиентского приложения. Разница в том, что учетные данные клиента обеспечивают дополнительный уровень контроля, поскольку при необходимости вы можете легко отозвать токен доступа, не требуя отзыва потребительского ключа приложения. Чтобы работать с конечными точками OAuth по умолчанию, вы можете использовать любой потребительский ключ и секрет, созданные для приложения в вашей организации, для получения токенов доступа из конечной точки токена. (Вы даже можете включить учетные данные клиента для приложений, у которых уже есть пользовательские ключи и секреты.)

Полную спецификацию предоставления учетных данных клиента можно найти в спецификации OAuth 2.0 .

Защитите свой API с помощью политики

Прежде чем вы сможете использовать токены доступа, вам необходимо настроить API для проверки токенов доступа OAuth во время выполнения. Для этого вы настраиваете прокси-сервер API для проверки токенов доступа. Это означает, что каждый раз, когда приложение отправляет запрос на использование одного из ваших API, приложение должно предоставить действительный токен доступа вместе с запросом API. Apigee Edge решает сложные задачи создания, хранения и проверки представленных токенов доступа.

Вы можете легко добавить проверку OAuth в API при создании нового прокси-сервера API. Когда вы создаете новый прокси-сервер API, вы можете добавить функции . Как показано ниже, вы можете добавить проверку токенов доступа OAuth 2.0, установив переключатель рядом с пунктом «Защитить с помощью токенов доступа OAuth v2.0» . Если вы выберете этот параметр, к вновь созданному прокси-серверу API будут прикреплены две политики: одна для проверки токенов доступа, а другая — для удаления токена доступа после его проверки.

Кроме того, когда вы выбираете параметр «Защитить с помощью токенов доступа OAuth v2.0» , флажок «Опубликовать продукт API» становится доступным для выбора и устанавливается автоматически. Установите этот флажок, если хотите автоматически создавать продукт при создании нового прокси-сервера API. Автоматически созданный продукт будет создан с привязкой к новому прокси-серверу API. Если у вас есть существующий продукт, с которым вы хотите связать этот новый API, обязательно снимите этот флажок, чтобы не создавать ненужный продукт. Информацию о продуктах см. в разделе Что такое продукт API?

Если вам нужно включить проверку токена доступа для уже существующего прокси-сервера API, все, что вам нужно сделать, — это прикрепить политику типа OAuthV2 к API, который вы хотите защитить. Политики OAuthV2 работают путем указания операции . Если вы хотите проверить токены доступа, вы указываете операцию VerifyAccessToken . (Другими типами операций, поддерживаемыми типом политики OAuthV2, являются GenerateAccessToken и GenerateRefreshToken. Вы узнаете об этих операциях при настройке конечных точек OAuth.)

Политика VerifyOAuthTokens типа OAuthV2

Пример политики проверки токенов доступа выглядит следующим образом. (Настройки описаны в таблице ниже.)

<OAuthV2 name="VerifyOAuthTokens">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

Параметры политики

Имя Описание По умолчанию Необходимый?
OAuthV2 Тип политики
name Имя политики, на которую есть ссылка в конфигурации конечной точки прокси-сервера API. Н/Д Да
Operation Операция, выполняемая политикой OAuthV2. Указывая VerifyAccessToken, вы настраиваете политику для проверки запросов на токены доступа и проверки того, что токен доступа действителен, не истек и одобрен для использования запрошенного ресурса API (URI). (Чтобы выполнить эту проверку, политика считывает продукт API, который разрешено использовать приложению.) Н/Д Да

Чтобы создать эту политику в пользовательском интерфейсе управления, перейдите в раздел API > Прокси-серверы API .

В списке прокси-серверов API выберите Weatherapi .

В обзоре Weatherapi выберите представление « Разработка» .

В раскрывающемся меню выберите «Новая политика» > «OAuth v2.0».

После выбора политики OAuth v2.0 отобразится меню конфигурации новой политики .

Дайте вашей политике описательное имя и обязательно выберите «Прикрепить политику» , «Поток PreFlow » и «Запрос» в качестве параметров вложения политики.

Выберите «Добавить» , и политика будет создана и прикреплена к запросу PreFlow от Weatherapi.

После добавления политики приведенная ниже конфигурация PreFlow запроса отобразится на панели «Дизайнер» .

Если вы работаете локально в текстовом редакторе или IDE, вы прикрепляете Политику к запросу PreFlow прокси-сервера API, который хотите защитить:

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthTokens</Name></Step>
  </Request>
</PreFlow>

Прикрепляя политику к запросу PreFlow, вы гарантируете, что политика всегда применяется ко всем сообщениям с запросами.

Теперь вы защитили API с помощью учетных данных клиента OAuth 2.0. Следующий шаг — узнать, как получить токен доступа и использовать его для доступа к безопасному API.

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

Теперь, когда Weatherapi защищен с помощью OAuth 2.0, приложения должны предоставлять токены доступа для использования API. Для доступа к защищенному ресурсу приложение представляет токен доступа в запросе в виде HTTP-заголовка «Авторизация» следующим образом:

$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

Поскольку к API прикреплена политика OAuthV2, Apigee Edge проверит, что представленный токен доступа действителен, а затем предоставит доступ к API, вернув отчет о погоде приложению, которое сделало запрос.

Но как приложения получают токены доступа? Мы рассмотрим это в следующем разделе.

Как обменять учетные данные клиента на токен доступа

Приложения получают токены доступа, предоставляя свои пары потребительский ключ/секрет конечной точке токена . Конечная точка токена настраивается в прокси-сервере API под названием oauth . Поэтому приложениям необходимо вызывать API, предоставляемый прокси-сервером API oauth , чтобы получить токен доступа. После того, как приложение получит токен доступа, оно может повторно вызывать Weatherapi до тех пор, пока не истечет срок действия токена доступа или пока токен доступа не будет отозван.

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

Вы можете получить потребительский ключ и секрет, зарегистрировав приложение в своей организации на Apigee Edge.

Вы можете увидеть все приложения в вашей организации в пользовательском интерфейсе управления Apigee Edge.

Отобразится список приложений, зарегистрированных в вашей организации.

(Если приложения не отображаются, вы можете узнать, как зарегистрировать приложение, в разделе « Регистрация приложений и управление ключами API» .)

Выберите приложение из списка, чтобы просмотреть его подробный профиль.

В подробном представлении выбранного вами приложения обратите внимание на поля Consumer Key и Consumer Secret . Эти два значения представляют собой учетные данные клиента , которые вы будете использовать для получения токена доступа OAuth. 

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps \
-u myname:mypass

Этот вызов возвращает список приложений по идентификатору приложения .

[ "da496fae-2a04-4a5c-b2d0-709278a6f9db", "50e3e831-175b-4a05-8fb6-05a54701af6e" ]

Вы можете получить профиль приложения, выполнив простой вызов GET по идентификатору приложения:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/{app_id} \
-u myname:mypass

Например:

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/da496fae-2a04-4a5c-b2d0-709278a6f9db \
-u myname:mypass

Вызов API возвращает профиль указанного вами приложения. Например, профиль приложения WeatherApp имеет следующее представление JSON:

{
  "accessType" : "read",
  "apiProducts" : [ ],
  "appFamily" : "default",
  "appId" : "da496fae-2a04-4a5c-b2d0-709278a6f9db",
  "attributes" : [ ],
  "callbackUrl" : "http://weatherapp.com",
  "createdAt" : 1380290158713,
  "createdBy" : "noreply_admin@apigee.com",
  "credentials" : [ {
    "apiProducts" : [ {
      "apiproduct" : "PremiumWeatherAPI",
      "status" : "approved"
    } ],
    "attributes" : [ ],
    "consumerKey" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
    "consumerSecret" : "hAr4Gn0gA9vAyvI4",
    "expiresAt" : -1,
    "issuedAt" : 1380290161417,
    "scopes" : [ ],
    "status" : "approved"
  } ],
  "developerId" : "5w95xGkpnjzJDBT4",
  "lastModifiedAt" : 1380290158713,
  "lastModifiedBy" : "noreply_admin@apigee.com",
  "name" : "weatherapp",
  "scopes" : [ ],
  "status" : "approved"
}

Обратите внимание на значения consumerKey и consumerSecret . Вы используете эти учетные данные для получения токена доступа, представляя их как учетные данные базовой аутентификации в HTTP-запросе, как показано ниже. Тип гранта представлен как параметр запроса. (Обязательно измените значение переменной {org_name}, чтобы оно отражало название вашей организации в Apigee Edge.)

Создайте запрос на получение токена доступа

В следующем запросе замените значение вашего consumerKey на client_id . Замените значение связанного consumerSecret на client_secret .

$ curl https://{org_name}-test.apigee.net/oauth/client_credential/accesstoken?grant_type=client_credentials -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'

Службы API проверяют ключ и секрет потребителя, а затем генерируют ответ, содержащий токен доступа для этого приложения: 

{
  "issued_at" : "1380892555397",
  "application_name" : "957aa73f-25c2-4ead-8021-adc01f0d2c6b",
  "scope" : "",
  "status" : "approved",
  "api_product_list" : "[oauth-test]",
  "expires_in" : "3599",
  "developer.email" : "tesla@weathersample.com",
  "organization_id" : "0",
  "client_id" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
  "access_token" : "ylSkZIjbdWybfs4fUQe9BqP0LH5Z",
  "organization_name" : "rqa",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

Обратите внимание на значение access_token в ответе выше. Это токен доступа, который приложение будет использовать для получения доступа к защищенным ресурсам во время выполнения. Токен доступа для этого приложения — ylSkZIjbdWybfs4fUQe9BqP0LH5Z .

Теперь у вас есть действительный токен доступа ylSkZIjbdWybfs4fUQe9BqP0LH5Z , который можно использовать для доступа к защищенным API.

Работа с конфигурацией OAuth по умолчанию.

Каждая организация (даже организация с бесплатной пробной версией) в Apigee Edge имеет конечную точку токена OAuth. Конечная точка предварительно настроена с помощью политик в прокси-сервере API под названием oauth . Вы можете начать использовать конечную точку токена, как только создадите учетную запись в Apigee Edge .

Конечная точка OAuth по умолчанию предоставляет следующий URI конечной точки: 

/oauth/client_credential/accesstoken

Опубликуйте этот URI для разработчиков, которым необходимо получить токены доступа. Разработчики приложений настраивают свои приложения для вызова этой конечной точки, предоставляя свои пары потребительского ключа и секрета для получения токенов доступа.

Конечная точка токена учетных данных клиента по умолчанию предоставляется в сети по следующему URL-адресу: 

https://{org_name}-{env_name}.apigee.net/oauth/client_credential/accesstoken

Например, если название вашей организации — «apimakers», URL-адрес будет таким: 

https://apimakers-test.apigee.net/oauth/client_credential/accesstoken

Это URL-адрес, по которому разработчики обращаются для получения токенов доступа.

Трехсторонние конфигурации OAuth

Трехсторонние конфигурации OAuth ( код авторизации, неявное предоставление пароля и типы предоставления пароля ) требуют, чтобы вы, поставщик API, аутентифицировали конечных пользователей приложения. Поскольку каждая организация аутентифицирует пользователей по-разному, для интеграции OAuth с вашим хранилищем пользователей требуется некоторая настройка политики или код. Например, все ваши пользователи могут храниться в Active Directory, LDAP или каком-либо другом хранилище пользователей. Чтобы запустить трехсторонний OAuth, вам необходимо интегрировать проверку этого хранилища пользователей в общий поток OAuth.

ОАут 1.0а

Подробную информацию о политике OAuth 1.0a см. в разделе Политика OAuth v1.0a .

Получить помощь

Для получения помощи см. Службу поддержки клиентов Apigee .