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

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

В этом разделе мы покажем вам, как запрашивать токены доступа и коды авторизации, настраивать конечные точки OAuth 2.0 и настраивать политики для каждого поддерживаемого типа предоставления .

Пример кода

Для вашего удобства политики и конечные точки, обсуждаемые в этом разделе, доступны на GitHub в проекте oauth-doc-examples в репозитории Apigee api-platform-samples. Вы можете развернуть пример кода и опробовать примеры запросов, показанные в этом разделе. Подробности смотрите в README проекта.

Запрос токена доступа: тип предоставления кода авторизации

В этом разделе объясняется, как запросить токен доступа с помощью потока типа предоставления кода авторизации. Общие сведения о типах разрешений OAuth 2.0 см. в разделе Знакомство с OAuth 2.0 .

Образец запроса 

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
   -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
   -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
   -d 'code=I9dMGHAN&grant_type=authorization_code&redirect_uri=http://example-callback.com'

Обязательные параметры

По умолчанию эти параметры должны иметь x-www-form-urlencoded и указываться в теле запроса (как показано в примере выше); однако это значение по умолчанию можно изменить, настроив элементы <GrantType> , <Code> и <RedirectUri> в политике OAuthV2, которая прикреплена к этой конечной точке /accesstoken . Подробности см. в политике OAuthV2 .

  • Grant_type — должно быть установлено authorization_code .
  • code — код авторизации, полученный от конечной точки /authorize (или как вы его назовете). Чтобы запросить токен доступа в потоке типа предоставления кода авторизации, необходимо сначала получить код авторизации. См. раздел «Запрос кодов авторизации» ниже. См. также Реализация типа предоставления кода авторизации .
  • redirect_uri — этот параметр необходимо указать, если параметр redirect_uri был включен в предыдущий запрос кода авторизации. Если параметр redirect_uri не был включен в запрос кода авторизации и вы не предоставили этот параметр, эта политика использует значение URL-адреса обратного вызова, которое было предоставлено при регистрации приложения разработчика.

Дополнительные параметры

  • состояние — строка, которая будет отправлена ​​обратно вместе с ответом. Обычно используется для предотвращения атак с подделкой межсайтовых запросов.
  • область действия — позволяет фильтровать список продуктов API, с которыми можно использовать отчеканенный токен. Подробную информацию об области см. в разделе Работа с областями OAuth2 .

Аутентификация

Идентификатор клиента и секрет клиента необходимо передать либо в виде заголовка базовой аутентификации (в кодировке Base64), либо в качестве параметров формы client_id и client_secret . Вы получаете эти значения из зарегистрированного приложения разработчика. См. также « Кодирование учетных данных базовой аутентификации ».

Пример конечной точки

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

...
       <Flow name="generate-access-token">
            <Description>Generate a token</Description>
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Образец политики

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

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn>
    <RefreshTokenExpiresIn>86400000</RefreshTokenExpiresIn>
    <SupportedGrantTypes>
      <GrantType>authorization_code</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Возврат

Если <GenerateResponse> включен, политика возвращает ответ JSON, содержащий токен доступа, как показано ниже. Тип предоставления authorization_code создает токен доступа и токены обновления, поэтому ответ может выглядеть следующим образом:

{
    "issued_at": "1420262924658",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420262924658",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "fYACGW7OCPtCNDEnRSnqFlEgogboFPMm",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "2l4IQtZXbn5WBJdL6EF7uenOWRsi",
    "organization_name": "docs",
    "refresh_token_expires_in": "86399", //--in seconds
    "refresh_count": "0"
}

Если для <GenerateResponse> установлено значение false, политика не возвращает ответ. Вместо этого он заполняет следующий набор переменных потока данными, относящимися к предоставлению токена доступа.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Например: 

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

Запрос токена доступа: тип предоставления учетных данных клиента

В этом разделе объясняется, как запросить токен доступа с помощью потока типа предоставления учетных данных клиента. Общие сведения о типах разрешений OAuth 2.0 см. в разделе Знакомство с OAuth 2.0 .

Образец запроса

Информацию о кодировании заголовка базовой аутентификации в следующем вызове см. в разделе « Кодирование учетных данных базовой аутентификации ». 

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic c3FIOG9vSGV4VHoAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

Обязательные параметры

По умолчанию требуемый параметр Grant_type должен иметь x-www-form-urlencoded и быть указан в теле запроса (как показано в примере выше); однако это значение по умолчанию можно изменить, настроив элемент <GrantType> в политике OAuthV2, прикрепленной к этой конечной точке /accesstoken . Например, вы можете выбрать передачу параметра в параметре запроса. Подробности см. в политике OAuthV2 .

  • grant_type — должно быть установлено значение client_credentials .

Дополнительные параметры

  • состояние — строка, которая будет отправлена ​​обратно вместе с ответом. Обычно используется для предотвращения атак с подделкой межсайтовых запросов.
  • область действия — позволяет фильтровать список продуктов API, с которыми можно использовать отчеканенный токен. Подробную информацию об области см. в разделе Работа с областями OAuth2 .

Аутентификация

Идентификатор клиента и секрет клиента необходимо передать либо в виде заголовка базовой аутентификации (в кодировке Base64), либо в качестве параметров формы client_id и client_secret . Вы получаете эти значения из зарегистрированного приложения разработчика, связанного с запросом. См. также « Кодирование учетных данных базовой аутентификации ».

Пример конечной точки

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

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Образец политики

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

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <SupportedGrantTypes>
      <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Возврат

Если <GenerateResponse> включен, политика возвращает ответ в формате JSON. Обратите внимание, что при использовании типа предоставления client_credentials токены обновления не поддерживаются. Чеканится только токен доступа. Например:

{
    "issued_at": "1420260525643",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "XkhU2DFnMGIVL2hvsRHLM00hRWav",
    "organization_name": "docs"
}

Если для <GenerateResponse> установлено значение false, политика не возвращает ответ. Вместо этого он заполняет следующий набор переменных потока данными, относящимися к предоставлению токена доступа.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds

Например: 

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in     //--in seconds

Запрос токена доступа: тип предоставления пароля

В этом разделе объясняется, как запросить токен доступа с использованием потока типа предоставления учетных данных (пароля) владельца ресурса. Общие сведения о типах разрешений OAuth 2.0 см. в разделе Знакомство с OAuth 2.0 .

Дополнительные сведения о типе предоставления пароля, включая 4-минутное видео, показывающее, как его реализовать, см. в разделе Реализация типа предоставления пароля .

Образец запроса

Информацию о кодировании заголовка базовой аутентификации в следующем вызове см. в разделе « Кодирование учетных данных базовой аутентификации ». 

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  -X POST https://docs-test.apigee.net/oauth/token \
  -d 'grant_type=password&username=the-user-name&password=the-users-password'

Обязательные параметры

По умолчанию эти параметры должны иметь x-www-form-urlencoded и указываться в теле запроса (как показано в примере выше); однако это значение по умолчанию можно изменить, настроив элементы <GrantType> , <Username> и <Password> в политике OAuthV2, которая прикреплена к этой конечной точке /token . Подробности см. в политике OAuthV2 .

Учетные данные пользователя обычно проверяются по хранилищу учетных данных с использованием политики LDAP или JavaScript.

  • Grant_type — должно быть установлено значение password .
  • username — имя пользователя владельца ресурса.
  • пароль — пароль владельца ресурса.

Дополнительные параметры

  • состояние — строка, которая будет отправлена ​​обратно вместе с ответом. Обычно используется для предотвращения атак с подделкой межсайтовых запросов.
  • область действия — позволяет фильтровать список продуктов API, с которыми можно использовать отчеканенный токен. Подробную информацию об области см. в разделе Работа с областями OAuth2 .

Аутентификация

Идентификатор клиента и секрет клиента необходимо передать либо в виде заголовка базовой аутентификации (в кодировке Base64), либо в качестве параметров формы client_id и client_secret . Вы получаете эти значения из зарегистрированного приложения разработчика, связанного с запросом. См. также « Кодирование учетных данных базовой аутентификации ».

Пример конечной точки

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

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Образец политики

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

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
    <SupportedGrantTypes>
      <GrantType>password</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Возврат

Если <GenerateResponse> включен, политика возвращает ответ в формате JSON. Обратите внимание, что при выборе типа предоставления пароля создаются как токен доступа, так и токен обновления. Например:

{
    "issued_at": "1420258685042",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420258685042",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "IFl7jlijYuexu6XVSSjLMJq8SVXGOAAq",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "I6daIgMSiUgYX1K2qgQWPi37ztS6",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "0"
}

Если для <GenerateResponse> установлено значение false, политика не возвращает ответ. Вместо этого он заполняет следующий набор переменных потока данными, относящимися к предоставлению токена доступа.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Например: 

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

Запрос токена доступа: неявный тип предоставления

В этом разделе объясняется, как запросить токен доступа, используя поток неявного типа предоставления. Общие сведения о типах разрешений OAuth 2.0 см. в разделе Знакомство с OAuth 2.0 .

Образец запроса 

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'https://docs-test.apigee.net/oauth/implicit?response_type=token&client_id=ABC123&redirect_uri=http://callback-example.com'

Обязательные параметры

По умолчанию эти параметры должны быть параметрами запроса (как показано в примере выше); однако это значение по умолчанию можно изменить, настроив элементы <ResponseType> , <ClientId> и <RedirectUri> в политике OAuthV2, прикрепленной к этой конечной точке /token . Подробности см. в политике OAuthV2 .

Учетные данные пользователя обычно проверяются по хранилищу учетных данных с помощью вызова службы LDAP или политики JavaScript.

  • тип_ответа — должен быть установлен в значение token .
  • client_id — идентификатор клиента зарегистрированного приложения разработчика.
  • redirect_uri — этот параметр является обязательным, если URI обратного вызова не был указан при регистрации приложения разработчика клиента. Если URL-адрес обратного вызова был указан при регистрации клиента, он будет сравниваться с этим значением и должен точно совпадать.

Дополнительные параметры

  • состояние — строка, которая будет отправлена ​​обратно вместе с ответом. Обычно используется для предотвращения атак с подделкой межсайтовых запросов.
  • область действия — позволяет фильтровать список продуктов API, с которыми можно использовать отчеканенный токен. Подробную информацию об области см. в разделе Работа с областями OAuth2 .

Аутентификация

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

Пример конечной точки

Ниже приведен пример конфигурации конечной точки для создания токена доступа. Он выполнит политику GenerateAccessTokenImplicitGrant. 

...
       <Flow name="generate-access-token-implicit">
            <Request>
                <Step>
                    <Name>GenerateAccessTokenImplicitGrant</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/implicit") and (request.verb = "POST")</Condition>
        </Flow>
...

Образец политики

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="GenerateAccessTokenImplicit">
    <DisplayName>GenerateAccessTokenImplicit</DisplayName>
    <Operation>GenerateAccessTokenImplicitGrant</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Возврат

Если <GenerateResponse> включен, политика возвращает перенаправление 302 Location в заголовке ответа. Перенаправление указывает на URL-адрес, указанный в параметре redirect_uri , и к нему добавляется токен доступа и время истечения срока действия токена. Обратите внимание, что тип неявного предоставления не поддерживает токены обновления. Например:

https://callback-example.com#expires_in=1799&access_token=In4dKm4ueoGZRbIYJhC9yZCmTFw5

Если для <GenerateResponse> установлено значение false, политика не возвращает ответ. Вместо этого он заполняет следующий набор переменных потока данными, относящимися к предоставлению токена доступа.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in  //--in seconds

Например: 

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in   //--in seconds

Запрос кода авторизации

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

Образец запроса

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code'

где политика OAuthV2 GenerateAuthorizationCode прикреплена к конечной точке прокси-сервера /oauth/authorize (см. пример конечной точки ниже).

Обязательные параметры

По умолчанию эти параметры должны быть параметрами запроса (как показано в примере выше); однако это значение по умолчанию можно изменить, настроив элементы <ResponseType> , <ClientId> и <RedirectUri> в политике OAuthV2, прикрепленной к этой конечной точке /authorize . Подробности см. в политике OAuthV2 .

  • тип_ответа — должен быть установлен в значение code .
  • client_id — идентификатор клиента зарегистрированного приложения разработчика.

Дополнительные параметры

  • redirect_uri — если в зарегистрированном клиентском приложении указан полный (не частичный) URI обратного вызова, этот параметр является необязательным; в противном случае это необходимо. Обратный вызов — это URL-адрес, по которому Edge отправляет новый код аутентификации. См. также Регистрация приложений и управление ключами API .
  • состояние — строка, которая будет отправлена ​​обратно вместе с ответом. Обычно используется для предотвращения атак с подделкой межсайтовых запросов.
  • область действия — позволяет фильтровать список продуктов API, с которыми можно использовать отчеканенный токен. Подробную информацию об области см. в разделе Работа с областями OAuth2 .

Аутентификация

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

Пример конечной точки

Вот пример конфигурации конечной точки для создания кода авторизации: 


<OAuthV2 name="GenerateAuthorizationCode">
  <Operation>GenerateAuthorizationCode</Operation>
    <!--
    ExpiresIn, in milliseconds. The ref is optional. The explicitly specified
    value is the default, when the variable reference cannot be resolved.
        60000 = 1 minute
       120000 = 2 minutes
    -->
  <ExpiresIn>60000</ExpiresIn>
  <GenerateResponse enabled="true"/>
</OAuthV2>

Образец политики

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

<OAuthV2 name="GenerateAuthorizationCode">
    <Operation>GenerateAuthorizationCode</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Возврат

Если <GenerateResponse> включен, политика возвращает параметр запроса ?code в расположение redirect_uri (URI обратного вызова) с прикрепленным кодом авторизации. Он отправляется через перенаправление браузера 302 с URL-адресом в заголовке Location ответа. Например: ?code=123456 .

Если для <GenerateResponse> установлено значение false , политика не возвращает ответ. Вместо этого он заполняет следующий набор переменных потока данными, относящимися к коду авторизации.

oauthv2authcode.{policy-name}.code
oauthv2authcode.{policy-name}.scope
oauthv2authcode.{policy-name}.redirect_uri
oauthv2authcode.{policy-name}.client_id

Например:

oauthv2authcode.GenerateAuthorizationCode.code
oauthv2authcode.GenerateAuthorizationCode.scope
oauthv2authcode.GenerateAuthorizationCode.redirect_uri
oauthv2authcode.GenerateAuthorizationCode.client_id

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

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

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

Образец запроса

Информацию о кодировании заголовка базовой аутентификации в следующем вызове см. в разделе « Кодирование учетных данных базовой аутентификации ». 

$ curl -X POST \
  -H "Content-type: application/x-www-form-urlencoded" \
  -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  https://myorg-test.apigee.net/my_oauth_endpoint/refresh_accesstoken \
  -d 'grant_type=refresh_token&refresh_token=my-refresh-token'

Обязательные параметры

  • grant_type — должно быть установлено refresh_token .
  • обновить_токен — токен обновления, связанный с токеном доступа, который вы хотите продлить.

По умолчанию политика ищет их как параметры x-www-form-urlencoded указанные в теле запроса, как показано в примере выше. Чтобы настроить альтернативное расположение для этих входных данных, вы можете использовать элементы <GrantType> и <RefreshToken> в политике OAuthV2. Подробности см. в политике OAuthV2 .

Дополнительные параметры

  • состояние — строка, которая будет отправлена ​​обратно вместе с ответом. Обычно используется для предотвращения атак с подделкой межсайтовых запросов.
  • область действия — позволяет фильтровать список продуктов API, с которыми можно использовать отчеканенный токен. Подробную информацию об области см. в разделе Работа с областями OAuth2 .

Аутентификация

  • client_id
  • client_secret

Идентификатор клиента и секрет клиента необходимо передать либо в виде заголовка базовой аутентификации (в кодировке Base64), либо в качестве параметров формы client_id и client_secret . См. также « Кодирование учетных данных базовой аутентификации ».

При обновлении токена доступа повторная аутентификация пользователя не выполняется.

Ниже приведен пример конфигурации конечной точки для создания токена доступа с использованием токена обновления. Он выполнит политику RefreshAccessToken. 

 ...
       <Flow name="generate-refresh-token">
            <Request>
                <Step>
                    <Name>RefreshAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/refresh") and (request.verb = "POST")</Condition>
       </Flow>
...

Образец политики

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
</OAuthV2>

Возврат

Если <GenerateResponse> включен, политика возвращает ответ JSON, содержащий новый токен доступа. Тип refresh_token поддерживает создание как доступа, так и новых токенов обновления. Например:

{
    "issued_at": "1420301470489",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "refresh_token_issued_at": "1420301470489",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "token_type": "BearerToken",
    "refresh_token": "8fKDHLryAD9KFBsrpixlq3qPJnG2fdZ5",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "jmZ2Hqv3iNsABUtAAsfWR3QGNctw",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "2"
}

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

Приведенный выше ответ вы получите, если для <GenerateResponse> установлено значение true. Если для <GenerateResponse> установлено значение false, политика не возвращает ответ. Вместо этого он заполняет следующий набор переменных контекста (потока) данными, относящимися к предоставлению токена доступа.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Например: 

oauthv2accesstoken.RefreshAccessToken.access_token
oauthv2accesstoken.RefreshAccessToken.expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token
oauthv2accesstoken.RefreshAccessToken.refresh_token_expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token_issued_at
oauthv2accesstoken.RefreshAccessToken.refresh_token_status

Кодирование базовых учетных данных аутентификации

Когда вы совершаете вызов API для запроса токена или кода аутентификации, рекомендуется передавать значения client_id и client_secret в качестве заголовка HTTP-Basic Authentication, как описано в IETF RFC 2617. Спецификация OAuth 2.0 рекомендует передавать значения client_id и client_secret в качестве заголовка HTTP-Basic Authentication. Для этого вы должны закодировать в Base64 результат объединения двух значений вместе с двоеточием, разделяющим их.

В псевдокоде:

result = Base64Encode(concat('ns4fQc14Zg4hKFCNaSzArVuwszX95X', ':', 'ZIjFyTsNgQNyxI'))

В этом примере ns4fQc14Zg4hKFCNaSzArVuwszX95X — это client_id, а ZIjFyTsNgQNyxI — это секрет клиента.

Независимо от языка программирования, который вы используете для вычисления значения в кодировке Base64, для данных учетных данных клиента результат в кодировке Base64 будет следующим: bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==

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

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

Утилита curl фактически создаст для вас заголовок HTTP Basic, если вы используете опцию -u. Следующее эквивалентно приведенному выше:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -u 'ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

Другие среды программирования могут иметь аналогичные ярлыки, которые автоматически генерируют заголовок в кодировке Base64.

Хеширование токенов в базе данных

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

Следующие свойства уровня организации управляют хешированием токена OAuth.

features.isOAuthTokenHashingEnabled = true
features.OAuthTokenHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

Если у вас есть существующие хешированные токены и вы хотите сохранить их до истечения срока их действия, установите следующие свойства в своей организации, где алгоритм хеширования соответствует существующему алгоритму (например, SHA1, бывший вариант Edge по умолчанию). Если токены не были хешированы, используйте PLAIN.

features.isOAuthTokenFallbackHashingEnabled = true
features.OAuthTokenFallbackHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

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

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