Вы просматриваете документацию Apigee Edge .
Перейдите к документации Apigee X. информация
В этом разделе обсуждается, как использовать области OAuth 2.0 в Apigee Edge.
Какова область действия OAuth2?
Области OAuth 2.0 позволяют ограничить объем доступа, предоставляемого токену доступа. Например, маркеру доступа, выданному клиентскому приложению, может быть предоставлен доступ ЧТЕНИЕ и ЗАПИСЬ к защищенным ресурсам или только доступ ЧТЕНИЕ. Вы можете реализовать свои 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». Другой способ взглянуть на это заключается в том, что параметр запроса области является своего рода фильтром. Если приложение разработчика распознает области «A, B, X», а параметр запроса указывает «scope=XYZ», то токену будет назначена только область «X».
Что, если клиент не прикрепляет параметр области? В этом случае Edge генерирует токен, включающий все области, распознаваемые приложением разработчика. Важно понимать, что по умолчанию возвращается токен доступа, содержащий объединение всех областей для всех продуктов, включенных в приложение разработчика.
Если ни один из продуктов, связанных с приложением разработчика, не указывает области, а у токена есть область, то вызовы, выполненные с помощью этого токена, завершатся ошибкой.
Допустим, приложение разработчика распознает эти области: 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 с учетом области действия.
Допустим, в вашем 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 несут ответственность за обеспечение соблюдения границ своих 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, и 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 или он пуст).