Вы просматриваете документацию по Apigee Edge.
Перейдите к документации по Apigee X. Информация
В этой статье рассказывается, как использовать области действия OAuth 2.0 в Apigee Edge.
Что такое область действия OAuth2?
Области действия OAuth 2.0 позволяют ограничить объем доступа, предоставляемого токену доступа. Например, токен доступа, выданный клиентскому приложению, может предоставлять доступ READ и WRITE к защищенным ресурсам или только доступ READ. Вы можете реализовать API так, чтобы они обеспечивали соблюдение любой области действия или сочетания областей действия. Поэтому, если клиент получит токен с областью действия READ и попытается вызвать конечную точку API, для которой требуется доступ WRITE, вызов завершится неудачей.
В этой статье рассказывается, как области действия назначаются токенам доступа и как Apigee Edge применяет области действия OAuth 2.0. Прочитав эту статью, вы сможете уверенно использовать области действия.
Как области действия назначаются токенам доступа?
Когда Edge создает токен доступа, он может назначить ему область действия. Чтобы понять, как это происходит, сначала нужно ознакомиться с такими объектами Apigee Edge, как продукты API, разработчики и приложения разработчиков. Подробнее о том, как публиковать приложения… Если вам нужно, ознакомьтесь с этими материалами, прежде чем продолжить.
Токен доступа – это длинная строка случайных символов, которая позволяет Edge проверять входящие запросы API (считайте, что это замена обычных учетных данных, таких как имя пользователя и пароль). Технически токен – это ключ, который относится к набору метаданных, выглядящих следующим образом:
{ "issued_at" : "1416962591727", "application_name" : "0d3e1d41-a59f-4d74-957e-d4e3275d4781", "scope" : "A", "status" : "approved", "api_product_list" : "[scopecheck1-bs0cSuqS9y]", "expires_in" : "1799", //--in seconds "developer.email" : "scopecheck1-AdBmANhsag@apigee.com", "organization_id" : "0", "token_type" : "BearerToken", "client_id" : "eTtB7w5lvk3DnOZNGReBlvGvIAeAywun", "access_token" : "ODm47ris5AlEty8TDc1itwYPe5MW", "organization_name" : "wwitman", "refresh_token_expires_in" : "0", //--in seconds "refresh_count" : "0" }
Метаданные токена включают строку токена доступа, информацию о сроке действия, а также идентификаторы приложения разработчика, самого разработчика и продуктов, связанных с токеном. Вы также заметите, что метаданные включают параметр "Область действия".
Как токен получает область действия?
Первое, что нужно знать об областях действия, – это то, что каждому продукту в приложении разработчика может быть назначено ноль или более областей действия. Эти области можно назначить при создании продукта или добавить позже. Они представлены в виде списка названий и включены в метаданные, связанные с каждым товаром.
Когда вы создаете приложение для разработчиков и добавляете в него продукты, Edge просматривает все продукты в приложении и создает список всех областей действия для этих продуктов (основной или глобальный список областей действия приложения – объединение всех распознанных областей действия).
Когда клиентское приложение запрашивает у Apigee Edge токен доступа, оно может указать, какие области действия должны быть связаны с этим токеном. Например, в следующем запросе запрашивается область действия "A". То есть клиент запрашивает у сервера авторизации (Edge) токен доступа с областью действия "A" (дающий приложению право вызывать API с областью действия "A"). Приложение отправляет запрос POST следующего вида:
curl -i -X POST -H Authorization: Basic Mg12YTk2UkEIyIBCrtro1QpIG -H content-type:application/x-www-form-urlencoded http://myorg-test.apigee.net/oauth/token?grant_type=client_credentials&scope=A
Что происходит
Когда Edge получает этот запрос, он знает, какое приложение его отправило, и какое приложение разработчика зарегистрировал клиент (идентификатор и секретный ключ клиента закодированы в заголовке базовой аутентификации). Поскольку в запрос включен параметр scope, Edge должен определить, есть ли у каких-либо продуктов API, связанных с приложением разработчика, область действия "A". Если да, то создается токен доступа с областью действия "A". Другими словами, параметр запроса scope – это своего рода фильтр. Если приложение разработчика распознает области "A, B, X", а в параметре запроса указано "scope=X Y Z", то токену будет назначена только область "X".
Что произойдет, если клиент не добавит параметр области действия? В этом случае Edge генерирует токен, который включает все области действия, распознаваемые приложением разработчика. Важно понимать, что по умолчанию возвращается токен доступа, содержащий объединение всех областей действия для всех продуктов, включенных в приложение разработчика.
Если ни один из товаров, связанных с приложением разработчика, не указывает области действия, а у токена есть область действия, то вызовы, выполненные с помощью этого токена, завершатся неудачно.
Допустим, приложение разработчика распознает следующие области действия: A, B, C, D. Это основной список областей действия приложения. Например, у одного товара в приложении могут быть области A и B, а у другого – C и D. Если клиент не указывает параметр scope (или указывает параметр области действия без значения), токену будут предоставлены все четыре области действия: A, B, C и D. Токен получает набор областей действия, представляющий собой объединение всех областей действия, распознаваемых приложением разработчика.
Ещё один случай, когда по умолчанию возвращается токен доступа со всеми распознанными областями действия, – если в правиле GenerateAccessToken (правиле Apigee Edge, которое генерирует токены доступа) не указан элемент <Scope>.
Например, ниже приведено правило GenerateAccessToken, в котором указано значение <Scope>
is. Если элемент <Scope> отсутствует или пуст, выполняется поведение по умолчанию.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-GenerateAccessToken"> <DisplayName>OAuthV2 - Generate Access Token</DisplayName> <Attributes> <Attribute name='hello' ref='system.time' display='false'>value1</Attribute> </Attributes> <Scope>request.queryparam.scope</Scope> <GrantType>request.formparam.grant_type</GrantType> <ExternalAuthorization>false</ExternalAuthorization> <Operation>GenerateAccessToken</Operation> <SupportedGrantTypes> <GrantType>client_credentials</GrantType> </SupportedGrantTypes> <GenerateResponse enabled="true"/> </OAuthV2>
Как применяются области действия?
Прежде всего, помните, что в Apigee Edge токены доступа проверяются с помощью правила OAuthV2 (обычно оно размещается в самом начале потока прокси). В правиле должна быть указана операция VerifyAccessToken. Вот пример правила:
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
<DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
<ExternalAuthorization>false</ExternalAuthorization>
<Operation>VerifyAccessToken</Operation>
<Scope>A</Scope> <!-- Optional: space-separated list of scope names. -->
<GenerateResponse enabled="true"/>
</OAuthV2>Обратите внимание на элемент <Scope>. Он используется для указания областей действия, которые будут приниматься правилом.
В этом примере правило будет выполнено, только если токен доступа включает область действия "A". Если элемент <Scope> отсутствует или не имеет значения, правило игнорирует область действия токена доступа.
Теперь вы можете проверять токены доступа на основе области действия и настраивать API так, чтобы они применяли определенные области действия. Для этого нужно создать специальные потоки с прикрепленными к ним правилами VerifyAccessToken, учитывающими область действия.
Предположим, что в вашем API для конечной точки /resourceA определен следующий поток:
<Flow name="resourceA">
<Condition>(proxy.pathsuffix MatchesPath "/resourceA") and (request.verb = "GET")</Condition>
<Description>Get a resource A</Description>
<Request>
<Step>
<Name>OAuthV2-VerifyAccessTokenA</Name>
</Step>
</Request>
<Response>
<Step>
<Name>AssignMessage-CreateResponse</Name>
</Step>
</Response>
</Flow>Когда запускается этот процесс (поступает запрос с /resourceA в суффиксе пути), сразу вызывается правило OAuthV2-VerifyAccessTokenA. Это правило проверяет, действителен ли токен доступа, и определяет, какие области действия он поддерживает. Если правило настроено так, как показано в примере ниже, с параметром <Scope>A</Scope>, оно будет выполнено только в том случае, если у токена доступа есть область действия "A". В противном случае будет возвращена ошибка.
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
<DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
<ExternalAuthorization>false</ExternalAuthorization>
<Operation>VerifyAccessToken</Operation>
<Scope>A</Scope>
<GenerateResponse enabled="true"/>
</OAuthV2>Таким образом, разработчики API должны сами реализовать в них проверку областей действия. Для этого они создают специальные потоки для обработки определенных областей действия и прикрепляют правила VerifyAccessToken, чтобы обеспечить соблюдение этих областей действия.
Примеры кода
Наконец, давайте рассмотрим несколько примеров вызовов API, чтобы понять, как токенам назначаются области действия и как они применяются.
Вариант по умолчанию
Предположим, у вас есть приложение для разработчиков с товарами, и объединение областей действия этих товаров включает A, B и C. Этот вызов API запрашивает токен доступа, но не указывает параметр запроса области действия.
curl -X POST -H content-type:application/x-www-form-urlencoded http://wwitman-test.apigee.net/scopecheck1/token?grant_type=client_credentials
В этом случае сгенерированный токен получит области действия A, B и C (поведение по умолчанию). Метаданные токена будут выглядеть примерно так:
{ "issued_at" : "1417016208588", "application_name" : "eb1a0333-5775-4116-9eb2-c36075ddc360", "scope" : "A B C", "status" : "approved", "api_product_list" : "[scopecheck1-yEgQbQqjRR]", "expires_in" : "1799", //--in seconds "developer.email" : "scopecheck1-yxiuHuZcDW@apigee.com", "organization_id" : "0", "token_type" : "BearerToken", "client_id" : "atGFvl3jgA0pJd05rXKHeNAC69naDmpW", "access_token" : "MveXpj4UYXol38thNoJYIa8fBGlI", "organization_name" : "wwitman", "refresh_token_expires_in" : "0", //--in seconds "refresh_count" : "0" }
Предположим, у вас есть конечная точка API с областью действия "A" (то есть для VerifyAccessToken требуется область действия "A"). Вот правила VerifyAccessToken:
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
<DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
<ExternalAuthorization>false</ExternalAuthorization>
<Operation>VerifyAccessToken</Operation>
<Scope>A</Scope>
<GenerateResponse enabled="true"/>
</OAuthV2>Вот пример вызова конечной точки, которая обеспечивает соблюдение области действия A:
curl -X GET -H Authorization: Bearer MveXpj4UYXol38thNoJYIa8fBGlI http://wwitman-test.apigee.net/scopecheck1/resourceA
Вызов GET выполнен успешно:
{
"hello" : "Tue, 25 Nov 2014 01:35:53 UTC"
}Запрос выполняется успешно, поскольку правило VerifyAccessToken, которое активируется при вызове конечной точки, требует область действия A, а маркеру доступа были предоставлены области действия A, B и C (поведение по умолчанию).
Фильтрация запросов
Предположим, у вас есть приложение для разработчиков с продуктами, у которых есть области действия A, B, C и X. Вы запрашиваете токен доступа и включаете параметр запроса scope, как показано ниже:
curl -i -X POST -H content-type:application/x-www-form-urlencoded 'http://myorg-test.apigee.net/oauth/token?grant_type=client_credentials&scope=A X'
В этом случае сгенерированный маркер получит области действия A и X, поскольку обе они действительны. Помните, что приложение разработчика распознает области A, B, C и X. В этом случае вы фильтруете список продуктов API на основе этих областей действия. Если у продукта есть область действия A или X, вы можете настроить конечные точки API, которые будут обеспечивать соблюдение этих областей действия. Если у продукта нет области действия A или X (например, есть B, C и Z), то API, которые требуют области действия A или X, нельзя вызывать с помощью токена.
При вызове API с новым токеном:
curl -X GET -H Authorization: Bearer Rkmqo2UkEIyIBCrtro1QpIG http://wwitman-test.apigee.net/scopecheck1/resourceX
Токен доступа проверяется прокси-сервером API. Пример:
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenX">
<DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
<ExternalAuthorization>false</ExternalAuthorization>
<Operation>VerifyAccessToken</Operation>
<Scope>A X</Scope>
<GenerateResponse enabled="true"/>
</OAuthV2>Вызов GET выполняется успешно и возвращает ответ. Пример:
{
"hello" : "Tue, 25 Nov 2014 01:35:53 UTC"
}
Операция выполнена успешно, поскольку правила VerifyAccessToken требуют область действия A или X, а маркер доступа включает области действия A и X. Если бы элемент <Scope> был задан как "B", этот вызов завершился бы ошибкой.
Сводка
Важно понимать, как Apigee Edge обрабатывает области действия OAuth 2.0. Вот основные выводы:
- Приложение разработчика "распознает" объединение всех областей действия, определенных для всех его продуктов.
- Когда приложение запрашивает токен доступа, оно может указать, какие области действия ему нужны. Сервер авторизации Apigee Edge определяет, какие области действия будут назначены токену доступа, на основе (а) запрошенных областей действия и (б) областей действия, распознаваемых приложением разработчика.
- Если Apigee Edge не настроен на проверку области действия (элемент
<Scope>отсутствует в правиле VerifyAccessToken или является пустым), вызов API будет выполнен, если область действия, встроенная в токен доступа, соответствует одной из областей действия, распознаваемых зарегистрированным приложением разработчика (одной из областей действия в "основном" списке областей действия приложения). - Если с токеном доступа не связаны области действия, он будет действителен только в тех случаях, когда Edge не учитывает области действия (элемент
<Scope>отсутствует в правиле VerifyAccessToken или является пустым).