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

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

В этой теме мы покажем вам, как запрашивать токены доступа и коды авторизации, настраивать конечные точки 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 .
  • код — код авторизации, полученный от конечной точки /authorize (или как вы его назовете). Чтобы запросить токен доступа в потоке предоставления кода авторизации, необходимо сначала получить код авторизации. См. раздел «Запрос кодов авторизации» ниже. См. также раздел «Реализация типа предоставления кода авторизации» .
  • redirect_uri — Этот параметр необходимо указать redirect_uri redirect_uri был включен в запрос кода авторизации и вы не указываете этот параметр, то в данной политике используется значение URL-адреса обратного вызова, предоставленного при регистрации приложения разработчика.

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

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

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

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

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

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

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

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

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

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

Необходимо передать идентификатор клиента (Client ID) и секретный ключ клиента (Client Secret) либо в заголовке базовой аутентификации (закодированном в 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 — имя пользователя, являющегося владельцем ресурса.
  • password — Пароль владельца ресурса.

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

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

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

Необходимо передать идентификатор клиента (Client ID) и секретный ключ клиента (Client Secret) либо в заголовке базовой аутентификации (закодированном в 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.

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

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

  • state — строка, которая будет отправлена ​​вместе с ответом. Обычно используется для предотвращения атак типа межсайтовой подделки запросов (CSRF).
  • scope — Позволяет фильтровать список продуктов API, с которыми можно использовать выпущенный токен. Подробную информацию о scope см. в разделе «Работа с scope 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> политика возвращает в заголовке ответа перенаправление Location с кодом 302. Перенаправление указывает на 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» .

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

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

  • redirect_uri — Если в зарегистрированном клиентском приложении указан полный (а не частичный) URI обратного вызова, этот параметр является необязательным; в противном случае он обязателен. Обратный вызов — это URL-адрес, куда Edge отправляет вновь созданный код авторизации. См. также раздел «Регистрация приложений и управление ключами API» .
  • state — строка, которая будет отправлена ​​вместе с ответом. Обычно используется для предотвращения атак типа межсайтовой подделки запросов (CSRF).
  • scope — Позволяет фильтровать список продуктов API, с которыми можно использовать выпущенный токен. Подробную информацию о scope см. в разделе «Работа с scope 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 .
  • refresh_token — Токен обновления, связанный с токеном доступа, который вы хотите обновить.

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

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

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

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

  • client_id
  • клиент_секрет

Идентификатор клиента (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, как описано в RFC 2617 IETF . Для этого необходимо закодировать результат объединения двух значений в 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 , чтобы настроить эти параметры для вашей организации и, при необходимости, выполнить хеширование существующих токенов в пакетном режиме.

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