Политика 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 в политике генерации токена доступа — настраиваемый атрибут просто является частью метаданных токена доступа.

То же самое поведение произойдёт, если вы добавите пользовательские атрибуты к коду авторизации: при генерации токена доступа с использованием этого кода эти пользовательские атрибуты будут отображаться в ответе токена доступа. Опять же, это может быть не то поведение, которое вы ожидали.

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

• Явно сбросьте настраиваемые атрибуты в политике обновления токена и установите для них значение 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 expiration . Если <ExpiresIn> не указано, система применяет значение по умолчанию, настроенное на системном уровне.

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

С помощью Apigee Edge для публичного облака 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 for Private Cloud значение по умолчанию задаётся свойством 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>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>

<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 присутствует в запросе, то эти два URL-адреса должны полностью совпадать. В противном случае возвращается ошибка. Сведения о регистрации приложений разработчиков в 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 for Private Cloud значение по умолчанию задаётся свойством 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>

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

Если этот элемент присутствует в одной из политик GenerateAccessToken или GenerateAuthorizationCode, он используется для указания областей действия, которым должен быть предоставлен токен или код. Эти значения обычно передаются в политику в запросе из клиентского приложения. Вы можете настроить элемент на прием переменной потока, что даст вам возможность выбрать способ передачи областей действия в запросе. В следующем примере 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 одному из поддерживаемых типов грантов).

Элемент <Tokens>/<Token>

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

Элемент <ИмяПользователя>

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

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

For example, you can pass the username in a query parameter and set the <UserName> element like this: <UserName>request.queryparam.username</UserName> . To require the username in an HTTP header, set this value to request.header.username .

The OAuthV2 policy doesn't do anything else with these credential values; Edge is simply verifying that they are present. It is up to the API developer to retrieve the values request and send them to an identity provider before the token generation policy executes.

See also Requesting access tokens and authorization codes .

Verifying access tokens

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.

Переменные потока

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>

Policy schema

Каждый тип политики определяется XML-схемой ( .xsd ). Схемы политик доступны на 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"}

Похожие темы

• Introduction to OAuth 2.0