OAuth

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

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>

Настройки политики

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

Из списка API-прокси выберите weatherapi .

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

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

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

Присвойте своей политике описательное имя и обязательно выберите параметры прикрепления политики: «Прикрепить политику» , «Предварительный поток» и «Запрос» .

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

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

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

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

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

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

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

Теперь, когда weatherapi защищен с помощью OAuth 2.0, приложениям необходимо предоставлять токены доступа для использования API. Для доступа к защищенному ресурсу приложение предоставляет токен доступа в запросе в заголовке HTTP "Authorization" следующим образом:

$ 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» .)

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

В подробном представлении выбранного вами приложения обратите внимание на поля «Ключ потребителя» и «Секрет потребителя» . Эти два значения представляют собой учетные данные клиента , которые вы будете использовать для получения токена доступа 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.)

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

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

$ 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-адрес, который разработчики используют для получения токенов доступа.

3-этапные конфигурации OAuth

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

OAuth 1.0a

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

Обратитесь за помощью

За помощью обращайтесь в службу поддержки клиентов Apigee .