Правила OAuthV2

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

Что

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. Чтобы требовать от конечного пользователя приложения указывать заголовок HTTP, например, задайте значение request.header.app_enduser.

Если вы зададите этот параметр, в токене доступа будет содержаться идентификатор конечного пользователя приложения. Эта функция полезна, если вы хотите иметь возможность получать или отзывать токены доступа OAuth 2.0 по идентификатору конечного пользователя. Подробнее о том, как разрешить получение и отзыв токенов доступа OAuth 2.0 по идентификатору конечного пользователя, идентификатору приложения или обоим этим параметрам…

<Attributes/Attribute>

<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>

<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 для общедоступного облака Edge хранит в кеше следующие объекты не менее 180 секунд после того, как к ним был получен доступ.

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

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

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

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

По умолчанию срок действия токенов доступа истекает через три дня после их создания. См. также Удаление токенов доступа.

Частное облако. Для установки 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. Перезапустите Message Processor.

   /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>

<Operation>GenerateAuthorizationCode</Operation>

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

Элемент <PassWord>

<PassWord>request.queryparam.password</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>

Устанавливает срок действия токенов обновления в миллисекундах. Срок действия файла cookie – это значение, сгенерированное системой, плюс значение переменной <RefreshTokenExpiresIn>. Если для параметра <RefreshTokenExpiresIn> задано значение -1, срок действия токена обновления истекает в соответствии с максимальным сроком действия токена обновления OAuth. Если значение <RefreshTokenExpiresIn> не указано, система применяет значение по умолчанию, заданное на уровне системы. Чтобы узнать больше о системных настройках по умолчанию, обратитесь в службу поддержки Apigee Edge.

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

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

<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. Перезапустите Message Processor.

   /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>

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

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

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

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

Также ознакомьтесь с информацией о том, как запросить токены доступа и коды авторизации.

Как подтверждать токены доступа

После того как для прокси-сервера API будет настроена конечная точка токена, к потоку, который предоставляет защищенный ресурс, будет прикреплено соответствующее правило OAuthV2, указывающее операцию VerifyAccessToken.

Например, чтобы все запросы к API были авторизованы, можно использовать следующее правило, которое обеспечивает проверку токена доступа:

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

Правило прикрепляется к ресурсу API, который нужно защитить. Чтобы все запросы к API проходили проверку, прикрепите правило к PreFlow запроса ProxyEndpoint, как показано ниже.

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

Следующие необязательные элементы можно использовать, чтобы переопределить настройки по умолчанию для операции VerifyAccessToken.

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

Также ознакомьтесь с разделами Как проверить токены доступа и Как запросить токены доступа и коды авторизации.

Как указать местоположение переменных запроса

Для каждого типа гранта в правилах есть предположения о местоположении или необходимой информации в запросах. Эти предположения основаны на спецификации OAuth 2.0. Если ваши приложения должны отклоняться от спецификации OAuth 2.0, вы можете указать ожидаемые местоположения для каждого параметра. Например, при обработке кода авторизации можно указать местоположение кода авторизации, идентификатора клиента, URI перенаправления и области действия. Их можно указать в виде заголовков HTTP, параметров запроса или параметров формы.

В примере ниже показано, как указать местоположение обязательных параметров кода авторизации в виде заголовков HTTP:

  ...
  <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>
  ...

Или, если это необходимо для поддержки клиентского приложения, можно комбинировать заголовки и параметры запроса:

  ...
  <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>
  ...

Для каждого параметра можно настроить только одно местоположение.

Переменные Flow

Переменные потока, определенные в этой таблице, заполняются при выполнении соответствующих правил OAuth и поэтому доступны для других правил или приложений, выполняемых в потоке прокси-сервера API.

Операция VerifyAccessToken

Выполняется операция VerifyAccessToken, и в контексте выполнения прокси-сервера заполняется большое количество переменных потока. Эти переменные содержат свойства, связанные с токеном доступа, приложением разработчика, самим разработчиком и компанией. Вы можете использовать, например, правило AssignMessage или JavaScript, чтобы прочитать любую из этих переменных и использовать ее по мере необходимости в дальнейшем в рабочем процессе. Эти переменные также могут быть полезны при отладке.

Переменные, относящиеся к токену

Переменные для приложений

Эти переменные связаны с приложением разработчика, с которым связан токен.

Переменные для разработчиков

Если app.appType имеет значение Company, заполняются атрибуты компании, а если Developer – атрибуты разработчика.

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

Если app.appType имеет значение Company, заполняются атрибуты компании, а если Developer – атрибуты разработчика.

Операция GenerateAuthorizationCode

Эти переменные задаются, когда операция GenerateAuthorizationCode выполняется успешно:

Префикс: oauthv2authcode.{policy_name}.{variable_name}

Пример: oauthv2authcode.GenerateCodePolicy.code.

Операции GenerateAccessToken и RefreshAccessToken

Эти переменные задаются, когда операции GenerateAccessToken и RefreshAccessToken выполняются успешно. Обратите внимание, что переменные токена обновления не применяются к потоку типа "Предоставление учетных данных клиента".

Префикс: oauthv2accesstoken.{policy_name}.{variable_name}

Пример: oauthv2accesstoken.GenerateTokenPolicy.access_token.

GenerateAccessTokenImplicitGrant

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

Префикс: oauthv2accesstoken.{policy_name}.{variable_name}

Пример: 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>

Схема правил

Каждый тип правил определяется схемой XML (.xsd). Схемы правил доступны на GitHub.

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

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

Удаление токенов доступа

По умолчанию токены OAuth2 удаляются из системы Apigee Edge через 3 дня (259 200 секунд) после истечения срока действия токена доступа и токена обновления (если он существует). В некоторых случаях вам может понадобиться изменить настройки по умолчанию. Например, если создается большое количество токенов, вы можете сократить время удаления, чтобы сэкономить место на диске.

Если вы используете Edge для частного облака, вы можете изменить значение по умолчанию, задав свойства организации, как описано в этом разделе. (Трехдневная очистка просроченных токенов применяется к Edge для частного облака версии 4.19.01 и более поздних версий. В более ранних версиях интервал удаления по умолчанию составляет 180 дней.

Как изменить настройки удаления для Edge Private Cloud 4.16.01 и более поздних версий

Примечание. Эти настройки применяются только к токенам, сгенерированным после их применения.

Обновление настроек удаления для Edge Private Cloud 4.15.07

Примечание. Эти настройки применяются только к токенам, сгенерированным после их применения.

Несоответствие RFC

Правило OAuthV2 возвращает ответ с токеном, который содержит определенные свойства, не соответствующие RFC. В таблице ниже перечислены несовместимые свойства, возвращаемые правилом OAuthV2, и соответствующие им совместимые свойства.

Кроме того, ответ об ошибке для просроченного токена обновления при использовании grant_type = refresh_token выглядит следующим образом:

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

Однако ответ, соответствующий RFC, выглядит так:

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

Статьи по теме

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