Como implementar o tipo de concessão de credenciais do cliente

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

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 na Apigee configurado para gerar um token de acesso. Se as credenciais forem válidas, a Apigee 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 na Apigee.

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 a Apigee 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: neste fluxo, a Apigee é 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ê protege os proxies de API hospedados na Apigee, ela também é o servidor de recursos.

Exemplo de código

Você pode encontrar uma implementação de amostra completa e funcional 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 de fluxo a seguir ilustra o fluxo de credenciais do cliente com a Apigee atuando como servidor de autorização. Em geral, a Apigee também é o servidor de recursos nesse fluxo, ou seja, os proxies da API são os recursos protegidos.

O fluxo de credenciais do cliente.

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 a Apigee atua como servidor de autorização. Com esse fluxo, o aplicativo cliente simplesmente apresenta o ID e a chave secreta do cliente. Se eles forem válidos, a Apigee retornará um token de acesso.

Pré-requisito: o app de cliente precisa ser registrado na Apigee 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 faz uma POST da chamada de API para a Apigee com os valores do ID e da chave secreta do cliente recebidos de um app de desenvolvedor registrado (neste exemplo, os valores são codificados em Base64 e transmitidos no cabeçalho Authorization. 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 -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" \
  -X POST "https://apitest.acme.com/oauth/token" \
  -d "grant_type=client_credentials"

Consulte também Como solicitar o tipo de concessão de credenciais de cliente.

2. A Apigee valida as credenciais

A chamada de API é enviada para o endpoint /oauth/token. Esse endpoint tem uma política anexada que valida as credenciais do aplicativo. Ou seja, a política compara as chaves enviadas com as que a Apigee criou quando o app foi registrado. Para mais informações sobre os endpoints OAuth na Apigee, consulte Como configurar endpoints e políticas do OAuth.

3. A Apigee retorna uma resposta

Se as credenciais estiverem corretas, a Apigee retornará um token de acesso ao 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 a Apigee (o proxy), e a Apigee é 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 servidor de autorização, a Apigee processa solicitações para 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 /oauth/token, 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/token. Publish this URL to app developers
         to use when obtaining an access token using an auth code
         -->
    <Condition>proxy.pathsuffix == "/oauth/token"</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 /oauth/token. 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 POST e inclui um cabeçalho de autorização com a codificação base64 client_id + client_secret e o parâmetro de consulta grant_type=client_credentials. Também pode incluir parâmetros opcionais para escopo e estado. 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, a Apigee processará a solicitação. Se não for válido, a Apigee 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.