Политика OAuthV2

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

Что

OAuthV2 — это многофункциональная политика для выполнения операций предоставления доступа по протоколу OAuth 2.0. Это основная политика, используемая для настройки конечных точек OAuth 2.0 на Apigee Edge.

Совет: Если вы хотите узнать больше об OAuth в Apigee Edge, посетите домашнюю страницу OAuth . Там вы найдете ссылки на ресурсы, примеры, видео и многое другое. Для наглядной демонстрации использования этой политики в работающем приложении см. расширенный пример OAuth на GitHub.

Образцы

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuth-v20-2">
    <DisplayName>OAuth v2.0 2</DisplayName>
    <Operation>VerifyAccessToken</Operation>
    <AccessTokenPrefix>Bearer</AccessTokenPrefix> <!-- Optional, default is Bearer -->
</OAuthV2>

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

<OAuthV2 enabled="true" continueOnError="false" async="false" name="generateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <AppEndUser>Doe</AppEndUser>
    <UserName>jdoe</UserName>
    <PassWord>jdoe</PassWord>
    <GrantType>grant_type</GrantType>
    <ClientId>a_valid_client_id</ClientId>
    <SupportedGrantTypes>
        <GrantType>password</GrantType>
    </SupportedGrantTypes>
</OAuthV2>

var client_id = context.getVariable("local_clientid");
var client_secret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(client_id + ':' + client_secret)));

См. также « Кодирование базовых учетных данных для аутентификации ».

Ссылка на элемент

В справочном документе по политике описаны элементы и атрибуты политики OAuthV2.

Приведенный ниже пример политики — это одна из многих возможных конфигураций. В этом примере показана политика OAuthV2, настроенная для операции GenerateAccessToken. Она включает обязательные и необязательные элементы. Подробности см. в описаниях элементов в этом разделе.

<OAuthV2 name="GenerateAccessToken">
  <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
  <Operation>GenerateAccessToken</Operation>
  <!-- This is in millseconds, so expire in an hour -->
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <GenerateResponse/>
</OAuthV2>

атрибуты <OAuthV2>

<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">

В следующей таблице описаны атрибуты, общие для всех родительских элементов политики:

Элемент <DisplayName>

Используйте в дополнение к атрибуту name , чтобы пометить политику в редакторе прокси-сервера пользовательского интерфейса управления другим именем на естественном языке.

<DisplayName>Policy Display Name</DisplayName>

элемент <AccessToken>

<AccessToken>request.header.access_token</AccessToken>

По умолчанию VerifyAccessToken ожидает, что токен доступа будет отправлен в заголовке Authorization . Вы можете изменить это значение по умолчанию, используя этот элемент. Например, request.queryparam.access_token указывает, что токен доступа должен присутствовать в качестве параметра запроса с именем access_token .

curl https://myorg-myenv.apigee.net/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

curl "https://myorg-myenv.apigee.net/oauth2/validate?access_token:Rft3dqrs56Blirls56a"

<AccessTokenPrefix> элемент

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

По умолчанию VerifyAccessToken ожидает, что токен доступа будет отправлен в заголовке Authorization в виде токена Bearer. Например:

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

В настоящее время поддерживается только префикс Bearer.

<AppEndUser> элемент

<AppEndUser>request.queryparam.app_enduser</AppEndUser>

В случаях, когда идентификатор конечного пользователя приложения необходимо отправить на сервер авторизации, этот элемент позволяет указать, где Edge должен искать идентификатор конечного пользователя. Например, его можно отправить в качестве параметра запроса или в заголовке HTTP.

Например request.queryparam.app_enduser указывает, что AppEndUser должен присутствовать в качестве параметра запроса, например, ?app_enduser=ntesla@theramin.com . Чтобы потребовать указания AppEndUser в заголовке HTTP, например, установите это значение равным request.header.app_enduser .

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

<Атрибуты/Атрибут>

<Attributes>
    <Attribute name="attr_name1" ref="flow.variable" display="true|false">value1</Attribute>
    <Attribute name="attr_name2" ref="flow.variable" display="true|false">value2</Attribute>
</Attributes>

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

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

Для получения дополнительной информации об использовании этого элемента см. раздел «Настройка токенов и кодов авторизации» .

Отображение или скрытие пользовательских атрибутов в ответе

Помните, что если вы установите для элемента GenerateResponse этой политики значение true , в ответе будет возвращено полное JSON-представление токена, включая любые заданные вами пользовательские атрибуты. В некоторых случаях может потребоваться скрыть некоторые или все пользовательские атрибуты в ответе, чтобы они не были видны клиентским приложениям.

По умолчанию пользовательские атрибуты отображаются в ответе. Если вы хотите их скрыть, установите параметр display в значение false . Например:

<Attributes>
    <Attribute name="employee_id" ref="employee.id" display="false"/>
    <Attribute name="employee_name" ref="employee.name" display="false"/>
</Attributes>

Значение атрибута display не сохраняется. Допустим, вы генерируете токен доступа с пользовательскими атрибутами, которые хотите скрыть в сгенерированном ответе. Установка display=false позволяет достичь этой цели. Однако, если позже будет сгенерирован новый токен доступа с использованием токена обновления, исходные пользовательские атрибуты из токена доступа отобразятся в ответе токена обновления. Это происходит потому, что Edge не запоминает, что атрибут display изначально был установлен в false в политике генерации токена доступа — пользовательский атрибут просто является частью метаданных токена доступа.

Аналогичное поведение вы увидите, если добавите пользовательские атрибуты к коду авторизации — при генерации токена доступа с использованием этого кода эти пользовательские атрибуты отобразятся в ответе с токеном доступа. Опять же, это может быть не то поведение, которое вы ожидаете.

Чтобы скрыть пользовательские атрибуты в таких случаях, у вас есть следующие варианты:

• Явно сбросьте пользовательские атрибуты в политике обновления токена и установите для них параметр display в значение false. В этом случае вам может потребоваться получить исходные пользовательские значения из исходного токена доступа с помощью политики GetOAuthV2Info.
• Используйте политику постобработки JavaScript для ручного извлечения любых пользовательских атрибутов, которые вы не хотите видеть в ответе.

См. также раздел «Настройка токенов и кодов авторизации» .

элемент <ClientId>

<ClientId>request.formparam.client_id</ClientId>

В ряде случаев клиентское приложение должно отправлять идентификатор клиента на сервер авторизации. Этот элемент указывает, что Apigee должен искать идентификатор клиента в переменной потока request.formparam.client_id . Присвоение ClientId любого другого значения не поддерживается. См. также Запрос токенов доступа и кодов авторизации .

<Код> элемент

<Code>request.queryparam.code</Code>

В потоке авторизации клиент должен отправить код авторизации на сервер авторизации (Apigee Edge). Этот элемент позволяет указать, где Edge должен искать код авторизации. Например, он может быть отправлен в качестве параметра запроса, заголовка HTTP или параметра формы (по умолчанию).

Переменная request.queryparam.auth_code указывает, что код авторизации должен присутствовать в качестве параметра запроса, например, ?auth_code=AfGlvs9 . Чтобы потребовать указания кода авторизации в заголовке HTTP, например, установите это значение равным request.header.auth_code . См. также Запрос токенов доступа и кодов авторизации .

<ExpiresIn> элемент

<ExpiresIn>10000</ExpiresIn>

Устанавливает время истечения срока действия токенов доступа и кодов авторизации в миллисекундах. (Для токенов обновления используйте <RefreshTokenExpiresIn> .) Значение времени истечения срока действия представляет собой сгенерированное системой значение плюс значение <ExpiresIn> . Если <ExpiresIn> установлено на -1 , токен или код истекает в соответствии с максимальным сроком действия токенов доступа OAuth . Если <ExpiresIn> не указано, система применяет значение по умолчанию, настроенное на системном уровне.

Время истечения срока действия также можно установить во время выполнения, используя либо жестко заданное значение по умолчанию, либо ссылку на переменную потока. Например, вы можете сохранить значение срока действия токена в карте ключ-значение, получить его, присвоить переменной и сослаться на него в политике. Например, kvm.oauth.expires_in .

В Apigee Edge for Public Cloud Edge хранит следующие объекты в кэше как минимум 180 секунд после обращения к ним.

• Токены доступа OAuth. Это означает, что отозванный токен может оставаться активным в течение до трех минут, пока не истечет лимит его кэширования.
• Сущности службы управления ключами (KMS) (приложения, разработчики, API-продукты).
• Пользовательские атрибуты для токенов OAuth и сущностей KMS.

В следующем фрагменте кода задается переменная потока, а также значение по умолчанию. Обратите внимание, что значение переменной потока имеет приоритет над указанным значением по умолчанию.

<ExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</ExpiresIn>

Edge не поддерживает способ принудительного истечения срока действия токена после его создания. Если вам необходимо принудительно истечь сроком действия токена (например, на основе определенного условия), возможное решение описано в этом сообщении на форуме сообщества Apigee .

По умолчанию просроченные токены доступа автоматически удаляются из системы Apigee Edge через 3 дня после истечения срока действия. См. также раздел «Удаление токенов доступа».

Частное облако: Для установки Edge для частного облака значение по умолчанию задается свойством conf_keymanagement_oauth_auth_code_expiry_time_in_millis . Чтобы установить это свойство:

1. Откройте файл message-processor.properties в текстовом редакторе. Если файл не существует, создайте его:

   vi /opt/apigee/customer/application/message-processor.properties

2. Настройте свойство по своему усмотрению:

   conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000

3. Убедитесь, что файл свойств принадлежит пользователю "apigee":

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

4. Перезапустите обработчик сообщений.

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

<ExternalAccessToken> элемент

<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>

Указывает Apigee Edge, где найти внешний токен доступа (токен доступа, не сгенерированный Apigee Edge).

Переменная request.queryparam.external_access_token указывает, что внешний токен доступа должен присутствовать в качестве параметра запроса, например, ?external_access_token=12345678 . Чтобы потребовать указания внешнего токена доступа в заголовке HTTP, например, установите это значение равным request.header.external_access_token . См. также раздел «Использование сторонних токенов OAuth» .

элемент <ExternalAuthorization>

<ExternalAuthorization>true</ExternalAuthorization>

Если этот элемент имеет значение false или отсутствует, Edge выполняет обычную проверку client_id и client_secret в хранилище авторизации Apigee Edge. Используйте этот элемент, если хотите работать с токенами OAuth сторонних производителей. Подробную информацию об использовании этого элемента см. в разделе «Использование токенов OAuth сторонних производителей» .

<ExternalAuthorizationCode> элемент

<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>

Указывает Apigee Edge, где найти внешний код авторизации (код авторизации, не сгенерированный Apigee Edge).

Переменная request.queryparam.external_auth_code указывает, что код внешней аутентификации должен присутствовать в качестве параметра запроса, например, ?external_auth_code=12345678 . Чтобы потребовать указания кода внешней аутентификации в заголовке HTTP, например, установите это значение равным request.header.external_auth_code . См. также раздел «Использование сторонних токенов OAuth» .

Элемент <ExternalRefreshToken>

<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>

Указывает Apigee Edge, где найти внешний токен обновления (токен обновления, не сгенерированный Apigee Edge).

Переменная request.queryparam.external_refresh_token указывает, что внешний токен обновления должен присутствовать в качестве параметра запроса, например, ?external_refresh_token=12345678 . Чтобы потребовать указания внешнего токена обновления в заголовке HTTP, например, установите это значение равным request.header.external_refresh_token . См. также раздел «Использование сторонних токенов OAuth» .

элемент <GenerateResponse>

<GenerateResponse enabled='true'/>

Если установлено значение true , политика генерирует и возвращает ответ. Например, для параметра GenerateAccessToken ответ может выглядеть следующим образом:

{
  "issued_at" : "1467841035013",
  "scope" : "read",
  "application_name" : "e31b8d06-d538-4f6b-9fe3-8796c11dc930",
  "refresh_token_issued_at" : "1467841035013",
  "status" : "approved",
  "refresh_token_status" : "approved",
  "api_product_list" : "[Product1, nhl_product]",
  "expires_in" : "1799",
  "developer.email" : "edward@slalom.org",
  "token_type" : "BearerToken",
  "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj",
  "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a",
  "organization_name" : "cerruti",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

Если false , ответ не отправляется. Вместо этого набор переменных потока заполняется значениями, связанными с функцией политики. Например, переменная потока с именем oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code заполняется вновь сгенерированным кодом авторизации. Обратите внимание, что expires_in в ответе выражается в секундах.

элемент <GenerateErrorResponse>

<GenerateErrorResponse enabled='true'/>

Если установлено значение true , политика генерирует и возвращает ответ, если атрибут ContinueOnError имеет значение true. Если false (по умолчанию), ответ не отправляется. Вместо этого набор переменных потока заполняется значениями, связанными с функцией политики.

<GrantType>

<GrantType>request.queryparam.grant_type</GrantType>

Указывает политике, где найти параметр типа предоставления доступа, передаваемый в запросе. В соответствии со спецификацией OAuth 2.0, тип предоставления доступа должен быть указан в запросах на токены доступа и коды авторизации. Переменная может быть заголовком, параметром запроса или параметром формы (по умолчанию).

Например request.queryparam.grant_type указывает, что пароль должен присутствовать в качестве параметра запроса, например, ?grant_type=password . Чтобы потребовать указания типа предоставления доступа в заголовке HTTP, установите это значение равным request.header.grant_type . См. также Запрос токенов доступа и кодов авторизации .

Элемент <Операция>

<Operation>GenerateAuthorizationCode</Operation>

Операция OAuth 2.0, выполняемая политикой.

<Пароль> элемент

<PassWord>request.queryparam.password</PassWord>

Этот элемент используется только с типом предоставления пароля . При использовании типа предоставления пароля учетные данные пользователя (пароль и имя пользователя) должны быть доступны политике OAuthV2. Элементы <PassWord> и <UserName> используются для указания переменных, в которых Edge может найти эти значения. Если эти элементы не указаны, политика ожидает найти значения (по умолчанию) в параметрах формы с именами username и password . Если значения не найдены, политика выдает ошибку. Вы можете использовать элементы <PassWord> и <UserName> для ссылки на любую переменную потока, содержащую учетные данные.

Например, вы можете передать пароль в запросе токена, используя параметр запроса, и установить элемент следующим образом: <PassWord>request.queryparam.password</PassWord> . Чтобы пароль требовался в заголовке HTTP, установите это значение равным request.header.password .

Политика OAuthV2 не выполняет никаких других действий с этими значениями учетных данных; Edge просто проверяет их наличие. Задача разработчика API — получить запрошенные значения и отправить их поставщику идентификации до выполнения политики генерации токенов.

См. также Запрос токенов доступа и кодов авторизации .

элемент <RedirectUri>

<RedirectUri>request.queryparam.redirect_uri</RedirectUri>

Указывает, где Edge должен искать параметр redirect_uri в запросе.

О URI перенаправления

URI перенаправления используются с типами авторизации «код авторизации» и «неявное предоставление доступа». URI перенаправления указывает серверу авторизации (Edge), куда отправить код авторизации (для типа предоставления доступа «код авторизации») или токен доступа (для типа неявного предоставления доступа). Важно понимать, когда этот параметр является обязательным, когда он необязателен и как он используется:

• (обязательно) Если URL-адрес обратного вызова зарегистрирован в приложении разработчика, связанном с ключами клиента запроса, и если параметр redirect_uri присутствует в запросе, то они должны точно совпадать. Если они не совпадают, возвращается ошибка. Информацию о регистрации приложений разработчика в Edge и указании URL-адреса обратного вызова см. в разделе «Регистрация приложений и управление ключами API» .

• (необязательно) Если URL-адрес обратного вызова зарегистрирован, но параметр redirect_uri отсутствует в запросе, Edge перенаправляет запрос на зарегистрированный URL-адрес обратного вызова.
• (обязательно) Если URL-адрес обратного вызова не зарегистрирован, то требуется указать redirect_uri . Обратите внимание, что в этом случае Edge примет ЛЮБОЙ URL-адрес. Этот случай может представлять угрозу безопасности, поэтому его следует использовать только с доверенными клиентскими приложениями. Если клиентские приложения не являются доверенными, то лучшей практикой является всегда требовать регистрации URL-адреса обратного вызова.

Этот параметр можно передать в качестве параметра запроса или в заголовке. Переменная request.queryparam.redirect_uri указывает, что RedirectUri должен присутствовать в качестве параметра запроса, например, ?redirect_uri=login.myapp.com . Чтобы потребовать указания RedirectUri в заголовке HTTP, например, установите это значение равным request.header.redirect_uri . См. также Запрос токенов доступа и кодов авторизации .

<RefreshToken> элемент

<RefreshToken>request.queryparam.refreshtoken</RefreshToken>

При запросе токена доступа с использованием токена обновления необходимо указать токен обновления в запросе. Этот элемент позволяет указать, где Edge должен искать токен обновления. Например, он может быть отправлен в качестве параметра запроса, заголовка HTTP или параметра формы (по умолчанию).

Переменная request.queryparam.refreshtoken указывает, что токен обновления должен присутствовать в качестве параметра запроса, например, ?refresh_token=login.myapp.com . Чтобы потребовать RefreshToken в заголовке HTTP, например, установите это значение равным request.header.refresh_token . См. также Запрос токенов доступа и кодов авторизации .

<RefreshTokenExpiresIn> элемент

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

Устанавливает время истечения срока действия токенов обновления в миллисекундах. Значение времени истечения срока действия представляет собой системное значение плюс значение <RefreshTokenExpiresIn> . Если <RefreshTokenExpiresIn> установлено в -1 , срок действия токена обновления истекает в соответствии с максимальным сроком действия токена обновления OAuth . Если <RefreshTokenExpiresIn> не указан, система применяет значение по умолчанию, заданное на системном уровне. Для получения дополнительной информации о настройках системы по умолчанию обратитесь в службу поддержки Apigee Edge .

Время истечения срока действия также можно установить во время выполнения, используя либо жестко заданное значение по умолчанию, либо ссылку на переменную потока. Например, вы можете сохранить значение срока действия токена в карте ключ-значение, получить его, присвоить переменной и сослаться на него в политике. Например, kvm.oauth.expires_in .

В следующем фрагменте кода задается переменная потока, а также значение по умолчанию. Обратите внимание, что значение переменной потока имеет приоритет над указанным значением по умолчанию.

<RefreshTokenExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</RefreshTokenExpiresIn>

Частное облако: Для установки Edge для частного облака значение по умолчанию задается свойством conf_keymanagement_oauth_refresh_token_expiry_time_in_millis . Чтобы установить это свойство:

1. Откройте файл message-processor.properties в текстовом редакторе. Если файл не существует, создайте его:

   vi /opt/apigee/customer/application/message-processor.properties

2. Настройте свойство по своему усмотрению:

   conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000

3. Убедитесь, что файл свойств принадлежит пользователю "apigee":

   chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

4. Перезапустите обработчик сообщений.

   /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

элемент <ResponseType>

<ResponseType>request.queryparam.response_type</ResponseType>

Этот элемент сообщает Edge, какой тип предоставления прав запрашивает клиентское приложение. Он используется только с потоками, содержащими код авторизации и неявный тип предоставления прав.

По умолчанию Edge ищет значение типа ответа в параметре запроса response_type . Если вы хотите изменить это поведение по умолчанию, используйте элемент <ResponseType> для настройки переменной потока, содержащей значение типа ответа. Например, если вы установите для этого элемента значение request.header.response_type , Edge будет искать тип ответа, передаваемый в заголовке запроса. См. также Запрос токенов доступа и кодов авторизации .

<ReuseRefreshToken> элемент

<ReuseRefreshToken>true</ReuseRefreshToken>

Если установлено значение true , существующий токен обновления используется повторно до истечения срока его действия. Если false , Apigee Edge выдает новый токен обновления при предъявлении действительного токена обновления.

<Область> элемент

<Scope>request.queryparam.scope</Scope>

Если этот элемент присутствует в одной из политик GenerateAccessToken или GenerateAuthorizationCode, он используется для указания областей действия (scopes), которые следует предоставить токену или коду. Эти значения обычно передаются в политику в запросе от клиентского приложения. Вы можете настроить элемент так, чтобы он принимал переменную потока, что позволит вам выбрать способ передачи областей действия в запросе. В следующем примере request.queryparam.scope указывает, что область действия должна присутствовать в качестве параметра запроса, например, ?scope=READ . Чтобы, например, указать область действия в заголовке HTTP, установите это значение равным request.header.scope .

Если этот элемент присутствует в политике "VerifyAccessToken", то он используется для указания областей действия, которые должна применять политика. В политике такого типа значение должно быть "жестко заданным" именем области действия — использование переменных невозможно. Например:

<Scope>A B</Scope>

См. также разделы «Работа с областями действия OAuth2» и «Запрос токенов доступа и кодов авторизации» .

элемент <State>

<State>request.queryparam.state</State>

В случаях, когда клиентское приложение должно отправлять информацию о состоянии на сервер авторизации, этот элемент позволяет указать, где Edge должен искать значения состояния. Например, его можно отправить в качестве параметра запроса или в заголовке HTTP. Значение состояния обычно используется в качестве меры безопасности для предотвращения CSRF-атак.

Например, request.queryparam.state указывает, что состояние должно присутствовать в качестве параметра запроса, например, ?state=HjoiuKJH32 . Чтобы потребовать указания состояния в заголовке HTTP, установите это значение равным request.header.state . См. также Запрос токенов доступа и кодов авторизации .

<StoreToken> элемент

 <StoreToken>true</StoreToken>

Установите для этого элемента значение true , если элемент <ExternalAuthorization> имеет true . Элемент <StoreToken> указывает Apigee Edge сохранять внешний токен доступа. В противном случае он не будет сохранен.

элемент <SupportedGrantTypes>/<GrantType>

<SupportedGrantTypes>
    <GrantType>authorization_code</GrantType>
    <GrantType>client_credentials</GrantType>
    <GrantType>implicit</GrantType>
    <GrantType>password</GrantType>
</SupportedGrantTypes>

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

Если поддерживаемые типы предоставления доступа не указаны, то разрешены только типы authorization_code и implicit . См. также элемент <GrantType> (это элемент более высокого уровня, используемый для указания того, где Apigee Edge должен искать параметр grant_type , передаваемый в запросе клиента. Edge убедится, что значение параметра grant_type соответствует одному из поддерживаемых типов предоставления доступа).

элемент <Токены>/<Токен>

Используется с операциями ValidateToken и InvalidateToken. См. также раздел «Утверждение и аннулирование токенов доступа» . Элемент <Token> определяет переменную потока, которая определяет источник аннулируемого токена. Если от разработчиков ожидается отправка токенов доступа в качестве параметров запроса, например, с именем access_token , используйте request.queryparam.access_token .

элемент <UserName>

<UserName>request.queryparam.user_name</UserName>

Этот элемент используется только с типом предоставления пароля . При использовании типа предоставления пароля учетные данные пользователя (пароль и имя пользователя) должны быть доступны политике OAuthV2. Элементы <PassWord> и <UserName> используются для указания переменных, в которых Edge может найти эти значения. Если эти элементы не указаны, политика ожидает найти значения (по умолчанию) в параметрах формы с именами username и password . Если значения не найдены, политика выдает ошибку. Вы можете использовать элементы <PassWord> и <UserName> для ссылки на любую переменную потока, содержащую учетные данные.

Например, вы можете передать имя пользователя в качестве параметра запроса и установить элемент <UserName> следующим образом: <UserName>request.queryparam.username</UserName> . Чтобы имя пользователя обязательно присутствовало в заголовке HTTP, установите это значение равным request.header.username .

Политика OAuthV2 не выполняет никаких других действий с этими значениями учетных данных; Edge просто проверяет их наличие. Задача разработчика API — получить запрошенные значения и отправить их поставщику идентификации до выполнения политики генерации токенов.

См. также Запрос токенов доступа и кодов авторизации .

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

Once a token endpoint is set up for an API proxy, a corresponding OAuthV2 policy that specifies the VerifyAccessToken operation is attached to the Flow that exposes the protected resource.

For example, to ensure that all requests to an API are authorized, the following policy enforces access token verification:

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

The policy is attached to the API resource to be protected. To ensure that all requests to an API are verified, attach the policy to the ProxyEndpoint request PreFlow, as follows:

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthAccessToken</Name></Step>
  </Request>
</PreFlow>

The following optional elements can be used to override the default settings for the VerifyAccessToken operation.

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>

See also Verifying access tokens and Requesting access tokens and authorization codes .

Specifying request variable locations

For each grant type, the policy makes assumptions about the location or required information in request messages. These assumptions are based on the OAuth 2.0 specification. If your apps need to deviate from the OAuth 2.0 specification, then you can specify the expected locations for each parameter. For example, when handling an authorization code, you can specify the location of the authorization code, the client ID, the redirect URI, and the scope. These can be specified as HTTP headers, query parameters, or form parameters.

The example below demonstrates how you can specify the location of required authorization code parameters as HTTP headers:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.header.client_id</ClientId>
  <RedirectUri>request.header.redirect_uri</RedirectUri>
  <Scope>request.header.scope</Scope>
  ...

Or, if necessary to support your client app base, you can mix and match headers and query parameters:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.queryparam.client_id</ClientId>
  <RedirectUri>request.queryparam.redirect_uri</RedirectUri>
  <Scope>request.queryparam.scope</Scope>
  ...

Only one location can be configured per parameter.

Flow variables

The flow variables defined in this table are populated when the respective OAuth policies are executed, and hence are available to other policies or applications executing in the API proxy flow.

VerifyAccessToken operation

The VerifyAccessToken operation executes, a large number of flow variables are populated in the proxy's execution context. These variables give you properties related to the access token, developer app, developer, and company. You can use an AssignMessage or JavaScript policy, for example, to read any of these variables and use them as needed later in the flow. These variables can also be useful for debugging purposes.

Token-specific variables

App-specific variables

These variables are related to the Developer App that is associated with the token.

Developer-specific variables

If the app.appType is "Company", then company attributes are populated and if app.appType is "Developer", then developer attributes are populated.

Company-specific variables

If the app.appType is "Company", then company attributes are populated and if app.appType is "Developer", then developer attributes are populated.

GenerateAuthorizationCode operation

These variables are set when the GenerateAuthorizationCode operation executes successfully:

Prefix: oauthv2authcode.{policy_name}.{variable_name}

Example: oauthv2authcode.GenerateCodePolicy.code

GenerateAccessToken and RefreshAccessToken operations

These variables are set when the GenerateAccessToken and RefreshAccessToken operations execute successfully. Note that refresh token variables do not apply for the client credentials grant type flow.

Prefix: oauthv2accesstoken.{policy_name}.{variable_name}

Example: oauthv2accesstoken.GenerateTokenPolicy.access_token

GenerateAccessTokenImplicitGrant

These variables are set when the GenerateAccessTokenImplicit operation executes successfully for the implicit grant type flow.

Prefix: oauthv2accesstoken.{policy_name}.{variable_name}

Example: oauthv2accesstoken.RefreshTokenPolicy.access_token

Ссылка на ошибку

В этом разделе описаны коды ошибок и сообщения об ошибках, которые возвращаются, а также переменные ошибок, которые устанавливаются Edge, когда эта политика вызывает ошибку. Эту информацию важно знать, если вы разрабатываете правила обработки ошибок. Дополнительные сведения см. в разделах Что нужно знать об ошибках политики и Обработка ошибок .

Ошибки выполнения

Эти ошибки могут возникнуть при выполнении политики.

Ошибки развертывания

Эти ошибки могут возникнуть при развертывании прокси-сервера, содержащего эту политику.

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

Эти переменные устанавливаются, когда эта политика вызывает ошибку во время выполнения.

Пример ответа об ошибке

Эти ответы отправляются обратно клиенту, если элемент <GenerateResponse> имеет значение true .

Если <GenerateResponse> имеет значение true , политика возвращает ошибки в этом формате для операций, генерирующих токены и коды. Полный список см. в разделе «Справочник по ответам на ошибки HTTP OAuth» .

{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}

Если <GenerateResponse> имеет значение true , политика возвращает ошибки в этом формате для операций проверки и проверки. Полный список см. в разделе «Справочник по ответам на ошибки HTTP OAuth» .

{  
   {  
      "fault":{  
         "faultstring":"Invalid Access Token",
         "detail":{  
            "errorcode":"keymanagement.service.invalid_access_token"
         }
      }
   }

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

<FaultRule name=OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientResponse</Name>
        <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition>
    </Step>
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

Схема политики

Each policy type is defined by an XML schema ( .xsd ). For reference, policy schemas are available on GitHub.

Working with the default OAuth configuration

Each organization (even a free trial org) on Apigee Edge is provisioned with an OAuth token endpoint. The endpoint is preconfigured with policies in the API proxy called oauth . You can begin using the token endpoint as soon as you create an account on Apigee Edge . For details, see Understanding OAuth endpoints .

Purging access tokens

By default, OAuth2 tokens are purged from the Apigee Edge system 3 days (259200 seconds) after both the access token and refresh token (if it exists) have expired. In some cases, you may want to change this default. For example, you may want to shorten the purge time to save disk space if a large number of tokens are being generated.

If you are on Edge for Private Cloud , you can change this default by setting organization properties as explained in this section. (The 3-day purge of expired tokens applies to Edge for Private Cloud version 4.19.01 and later. For earlier versions, the default purge interval is 180 days.)

Updating purge settings for Edge Private Cloud 4.16.01 and later versions

Note: Only tokens generated after these settings are applied are affected; the settings do not apply to tokens that were generated earlier.

Updating purge settings for Edge Private Cloud 4.15.07

Note: Only tokens generated after these settings are applied are affected; the settings do not apply to tokens that were generated earlier.

Non-RFC-compliant behavior

The OAuthV2 policy returns a token response that contains certain non- RFC-compliant properties. The following table shows the non-compliant properties returned by the OAuthV2 policy and the corresponding compliant properties.

Also, the error response for an expired refresh token when grant_type = refresh_token is:

{"ErrorCode" : "InvalidRequest", "Error" :"Refresh Token expired"}

However, the RFC-compliant response is:

{"error" : "invalid_grant", "error_description" :"refresh token expired"}

Связанные темы

• Введение в OAuth 2.0