Esta é a documentação do Apigee Edge.
Acesse
Documentação da Apigee X. informações
Com o tipo de concessão de credenciais do cliente, um aplicativo envia as próprias credenciais (o ID e a chave secreta do cliente) a um endpoint no Apigee Edge configurado para gerar um token de acesso. Se as credenciais forem válidas, o Edge retornará um token de acesso ao app cliente.
Sobre este tópico
Este tópico oferece uma descrição geral do tipo de concessão de credenciais de cliente OAuth 2.0 e discute como implementar esse fluxo no Apigee Edge.
Casos de uso
Normalmente, esse tipo de concessão é usado quando o aplicativo também é o proprietário do recurso. Por exemplo, um app pode precisar acessar um serviço de armazenamento baseado em nuvem de back-end para armazenar e recuperar dados usados na execução do trabalho, em vez de dados específicos do usuário final. Esse fluxo de tipo de concessão ocorre estritamente entre um aplicativo cliente e o servidor de autorização. Um usuário final não participa desse fluxo de tipo de concessão.
Papéis
Os papéis especificam os "atores" que participam do fluxo do OAuth. Confira uma rápida visão geral dos papéis de credenciais do cliente para ajudar a perceber onde o Apigee Edge se encaixa. Para uma discussão completa sobre os papéis do OAuth 2.0, consulte a especificação IETF OAuth 2.0.
- Aplicativo cliente: o app que precisa acessar os recursos protegidos pelo usuário. Normalmente, com esse fluxo, o app é executado no servidor em vez de localmente no laptop ou dispositivo do usuário.
- Apigee Edge: neste fluxo, o Apigee Edge é o servidor de autorização OAuth. A função dele é gerar tokens de acesso, validar tokens de acesso e transmitir ao servidor solicitações autorizadas de recursos protegidos.
- Servidor de recursos: o serviço de back-end que armazena os dados protegidos que exigem permissão para serem acessados pelo app cliente. Se você estiver protegendo proxies de API hospedados no Apigee Edge, ele também será o servidor de recursos.
Exemplo de código
Você pode encontrar uma completa implementação de amostra do tipo de concessão de credenciais de cliente no GitHub. Consulte Recursos adicionais (abaixo) para ver links com mais exemplos.
Diagrama de fluxo
O diagrama a seguir ilustra o fluxo de credenciais do cliente com o Apigee Edge atuando como servidor de autorização. Em geral, o Edge também é o servidor de recursos nesse fluxo, ou seja, os proxies de API são os recursos protegidos.
Etapas no fluxo de credenciais do cliente
Veja um resumo das etapas necessárias para implementar o tipo de concessão de código de credenciais do cliente em que o Apigee Edge funciona como servidor de autorização. Lembre-se de que, com esse fluxo, o aplicativo cliente simplesmente apresenta o ID e a chave secreta do cliente. Se forem válidos, o Apigee Edge retorna um token de acesso.
Pré-requisito: o app de cliente precisa ser registrado no Apigee Edge para receber o ID e as chaves secretas do cliente. Consulte Como registrar aplicativos de cliente para detalhes.
1. O cliente solicita um token de acesso.
Para receber um token de acesso, o cliente usa POST e faz uma chamada de API no Edge com os valores do ID e da chave secreta do cliente recebidos de um aplicativo de desenvolvedor registrado. Além disso, o parâmetro grant_type=client_credentials precisa ser transmitido como um parâmetro de consulta. No entanto, você pode configurar a política do OAuthV2 para aceitar esse parâmetro no cabeçalho ou no corpo da solicitação. Consulte Política do OAuthV2 para mais detalhes.
Exemplo:
$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials&client_id=ns4fQc14Zg4hKFCNaSzArVuwszX95X&client_secret=ZIjFyTsNgQNyxI'
Observação: embora seja possível transmitir os valores de client_id e client_secret como parâmetros de consulta acima, é recomendável transmiti-los como uma string codificada em URL base64 cabeçalho de autorização. Para fazer isso, você precisa usar uma ferramenta ou utilitário de codificação base64 para codificar os dois valores juntos separados por dois pontos. Exemplo: aBase64EncodeFunction(clientidvalue:clientsecret). Assim, o exemplo acima seria codificado dessa forma:
resultado = aBase64EncodeFunction(ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI) // Note os dois pontos que separam os dois valores.
O resultado da codificação base64 da string acima é: bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==
Em seguida, faça a solicitação do token da seguinte maneira:
$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg=='
2. O Edge valida as credenciais
Observe que a chamada de API é enviada para o endpoint /accesstoken. Esse endpoint tem uma política anexada que valida as credenciais do aplicativo. Ou seja, a política compara as chaves enviadas com as criadas pelo Apigee Edge quando o app foi registrado. Para saber mais sobre os endpoints OAuth no Edge, consulte Como configurar os endpoints e políticas do OAuth.
3. O Edge retorna uma resposta
Se as credenciais estiverem corretas, o Edge retornará um token de acesso para o cliente. Caso contrário, será retornado um erro.
4. O cliente chama a API protegida
Agora, com um token de acesso válido, o cliente pode fazer chamadas para a API protegida. Nesse cenário, as solicitações são feitas para o Apigee Edge (o proxy), e o Edge é responsável por validar o token de acesso antes de passar a chamada de API para o servidor de recursos de destino. Para ver um exemplo, consulte Como chamar a API protegida abaixo.
Como configurar fluxos e políticas
Como o servidor de autorização, o Edge processa solicitações de tokens de acesso. Como desenvolvedor da API, você precisa criar um proxy com um fluxo personalizado para processar solicitações de token e adicionar e configurar uma política OAuthV2. Nesta seção, explicamos como configurar esse endpoint.
Configuração de fluxo personalizada
A maneira mais fácil de mostrar como o fluxo de proxy da API está configurado é exibir a definição do fluxo XML. Veja um exemplo de fluxo de proxy de API projetado para processar uma solicitação de token de acesso. Por exemplo, quando uma solicitação é recebida e o sufixo do caminho corresponde a /accesstoken, a política GetAccessToken é acionada. Consulte Como configurar endpoints e políticas do OAuth para uma rápida visão geral das etapas necessárias para criar um fluxo personalizado como esse.
<Flows>
<Flow name="GetAccessToken">
<!-- This policy flow is triggered when the URI path suffix
matches /oauth/accesstoken. Publish this URL to app developers
to use when obtaining an access token using an auth code
-->
<Condition>proxy.pathsuffix == "/oauth/accesstoken"</Condition>
<Request>
<Step><Name>GetAccessToken</Name></Step>
</Request>
</Flow>
</Flows>
Configurar o fluxo com uma política
Você precisa anexar uma política ao endpoint da seguinte maneira. Consulte Como configurar endpoints e políticas do OAuth para uma rápida visão geral das etapas necessárias para adicionar uma política OAuthV2 a um endpoint do proxy.
Receber token de acesso
Essa política está anexada ao caminho /accesstoken. Ele usa a política
OAuthV2 com a operação GenerateAccessToken especificada.
<OAuthV2 name="GetAccessToken">
<Operation>GenerateAccessToken</Operation>
<ExpiresIn>3600000</ExpiresIn>
<SupportedGrantTypes>
<GrantType>client_credentials</GrantType>
</SupportedGrantTypes>
<GenerateResponse/>
</OAuthV2>
A chamada de API para receber o token de acesso é um (comando) POST e inclui um cabeçalho de autorização com o client_id + client+secret codificado em base64 e o parâmetro de consulta grant_type=client_credentials. Também pode incluir parâmetros opcionais para escopo e estado. Por exemplo:
$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVgT1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ'
Como anexar a política de verificação de tokens de acesso
Para proteger a API com a segurança do OAuth 2.0, adicione uma política OAuthV2 à operação VerifyAccessToken. Esta política verifica se as solicitações recebidas têm um token de acesso válido. Se o token for válido, o Edge processará a solicitação. Se não for válido, o Edge retornará um erro. Para ver as etapas básicas, consulte Como verificar tokens de acesso.
<OAuthV2 async="false" continueOnError="false" enabled="true" name="VerifyAccessToken">
<DisplayName>VerifyAccessToken</DisplayName>
<ExternalAuthorization>false</ExternalAuthorization>
<Operation>VerifyAccessToken</Operation>
<SupportedGrantTypes/>
<GenerateResponse enabled="true"/>
<Tokens/>
</OAuthV2>
Como chamar a API protegida
Para chamar uma API protegida com a segurança do OAuth 2.0, é preciso apresentar um token de acesso válido. O padrão correto é incluir o token em um cabeçalho de autorização, como indicado a seguir: o token de acesso também é chamado de "token do portador".
$ curl -H "Authorization: Bearer UAj2yiGAcMZGxfN2DhcUbl9v8WsR" \ http://myorg-test.apigee.net/v0/weather/forecastrss?w=12797282
Consulte também Como enviar um token de acesso.
Outros recursos
- A Apigee oferece treinamento on-line para desenvolvedores de API, incluindo um curso sobre segurança de API, que inclui OAuth.
- Política do OAuthV2: tem muitos exemplos que mostram como fazer solicitações ao servidor de autorização e como configurar a política do OAuthV2.