Как запросить токены доступа и коды авторизации

Вы просматриваете документацию по 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 обратного вызова, которое было указано при регистрации приложения разработчика.

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

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

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

Идентификатор клиента и секретный код клиента необходимо передать либо в виде заголовка базовой аутентификации (в кодировке 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 – строка, которая будет отправлена обратно в ответе. Обычно используется для предотвращения атак с подделкой межсайтовых запросов.
  • scope – позволяет фильтровать список продуктов 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.

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

Пример запроса

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

$ 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 – строка, которая будет отправлена обратно в ответе. Обычно используется для предотвращения атак с подделкой межсайтовых запросов.
  • scope – позволяет фильтровать список продуктов 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.

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

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

  • state – строка, которая будет отправлена обратно в ответе. Обычно используется для предотвращения атак с подделкой межсайтовых запросов.
  • scope – позволяет фильтровать список продуктов 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…

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

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

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

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

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

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

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