Вы просматриваете документацию Apigee Edge .
Перейдите в документацию Apigee X.info
В этой теме обсуждается, как использовать области действия OAuth 2.0 в Apigee Edge.
Что такое область действия OAuth2?
В OAuth 2.0 области действия (scopes) позволяют ограничить объем доступа, предоставляемого токену доступа. Например, токен доступа, выданный клиентскому приложению, может иметь доступ на чтение и запись к защищенным ресурсам, или только доступ на чтение. Вы можете реализовать свои API для обеспечения любой области действия или комбинации областей действия по вашему желанию. Таким образом, если клиент получает токен с областью действия «Чтение» и пытается вызвать конечную точку API, требующую доступа на запись, вызов завершится неудачей.
В этой теме мы обсудим, как назначаются области действия (scopes) для токенов доступа и как Apigee Edge обеспечивает соблюдение областей действия OAuth 2.0. После прочтения этой темы вы сможете уверенно использовать области действия.
Как назначаются области действия для токенов доступа?
Когда Edge генерирует токен доступа, он может назначить этому токену область действия (scope). Чтобы понять, как это происходит, необходимо сначала ознакомиться со следующими компонентами 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, оно может дополнительно указать, какие области действия (scopes) оно хотело бы связать с этим токеном. Например, следующий запрос запрашивает область действия "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=XYZ", то токену будет присвоена только область действия "X".
Что произойдет, если клиент не укажет параметр scope? В этом случае Edge сгенерирует токен, включающий все области действия, распознаваемые приложением разработчика. Важно понимать, что по умолчанию возвращается токен доступа, содержащий объединение всех областей действия для всех продуктов, включенных в приложение разработчика.
Если ни один из продуктов, связанных с приложением разработчика, не указывает область действия (scopes), а токен имеет такую область действия, то вызовы, выполненные с использованием этого токена, завершатся неудачей.
Предположим, приложение для разработчиков распознает следующие области видимости: ABC и D. Это основной список областей видимости приложения. Может быть, что один продукт в приложении имеет области видимости A и B, а второй — области видимости C и D, или любую их комбинацию. Если клиент не указывает параметр scope (или указывает параметр области видимости без значения), токену будут присвоены все четыре области видимости: A, B, C и D. Таким образом, токен получает набор областей видимости, представляющий собой объединение всех областей видимости, распознаваемых приложением для разработчиков.
Существует еще один случай, когда поведение по умолчанию заключается в возврате токена доступа со всеми распознанными областями действия, и это происходит, когда политика GenerateAccessToken (политика Apigee Edge, генерирующая токены доступа) не указывает элемент <Scope> . Например, вот политика GenerateAccessToken, в которой указан элемент <Scope> . Если этот элемент <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, учитывающими область действия.
Допустим, для конечной точки /resourceA в вашем API определен поток обработки данных:
<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 несут ответственность за внедрение механизмов обеспечения соответствия определенным областям действия в свои 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" (то есть, для его работы требуется область действия "A" в параметре VerifyAccessToken). Вот политика 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 и 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 или он пуст).