Esta página foi traduzida pela API Cloud Translation.

Implementar o tipo de concessão do código de autorização

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

O código de autorização é um dos tipos de concessão do OAuth 2.0 mais usados. O fluxo de código de autorização é uma configuração de "OAuth de três etapas". Nessa configuração, o usuário se autentica no servidor de recursos e dá ao aplicativo o consentimento para acessar recursos protegidos sem alterar o nome de usuário/senhas no app cliente.

Sobre este tópico

Neste tópico, você encontra uma descrição geral e uma visão geral do fluxo do tipo de concessão de autorização do OAuth 2.0, além de discutir como implementar esse fluxo no Apigee Edge.

Vídeo

Assista a um vídeo curto para saber como usar o tipo de concessão de autorização OAuth 2.0 para proteger suas APIs.

Casos de uso

Esse tipo de concessão é destinado a apps escritos por desenvolvedores de terceiros que não têm uma relação comercial confiável com o provedor de API. Por exemplo, os desenvolvedores que se registram em programas de API pública geralmente não são confiáveis. Com esse tipo de concessão, as credenciais de usuário no servidor de recursos nunca são compartilhadas com o aplicativo.

Exemplo de código

É possível encontrar uma implementação de exemplo completa e funcional do tipo de concessão de código de autorização no Apigee Edge no repositório api-platform-samples no GitHub. Consulte a amostra oauth-advanced no diretório api-platform-samples/sample-proxies. Consulte o arquivo README (em inglês) para os detalhes sobre a amostra.

Diagrama de fluxo

O diagrama de fluxo a seguir ilustra o fluxo de OAuth do código de autorização com o Apigee Edge como servidor de autorização.

Dica: para ver uma versão maior desse diagrama, clique com o botão direito nele e abra-o em uma nova guia ou salve-o e abra-o em um visualizador de imagens.

Etapas no fluxo de código de autorização

Veja um resumo das etapas necessárias para implementar o tipo de concessão de código de autorização em que o Apigee Edge funciona como o servidor de autorização. Lembre-se de que a chave para esse fluxo é que o cliente nunca consiga ver as credenciais do usuário no servidor de recursos.

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 usuário inicia o fluxo

Quando o aplicativo precisa acessar os recursos protegidos do usuário de um servidor de recursos, por exemplo, lista de contatos em um site de mídia social, ele envia uma chamada de API para o Apigee Edge, que valida o ID do cliente e, caso seja válido, redireciona o navegador do usuário para uma página de login onde o usuário insere suas credenciais. A chamada de API inclui informações que o app de cliente recebeu quando foi registrado: o ID do cliente e o URI de redirecionamento.

2. O usuário insere as credenciais

O usuário agora vê uma página de login onde é solicitado a inserir as credenciais de login. Se o login for bem-sucedido, vamos para a próxima etapa.

3. O usuário consente

Nesta etapa, o usuário autoriza o aplicativo a acessar os recursos. O formulário de consentimento normalmente inclui seleções de escopo, em que o usuário pode escolher o que o app pode fazer no servidor de recursos. Por exemplo, o usuário pode conceder permissão somente leitura ou permissão para o aplicativo atualizar recursos.

4. O aplicativo de login envia uma solicitação do Apigee Edge

Se o login e o consentimento forem bem-sucedidos, o aplicativo de login faz POST dos dados para o endpoint /authorizationcode do Apigee Edge. Os dados incluem o URI de redirecionamento, o ID do cliente, o escopo, qualquer informação específica do usuário que você quer incluir e uma indicação de que o login foi bem-sucedido.

5. O Apigee Edge gera um código de autorização

Quando o Edge recebe uma solicitação GET do app de login no endpoint /authorizationcode, duas coisas acontecem. Primeiro, o Edge determina que o login foi bem-sucedido, verificando o status HTTP ou outros meios. Depois, o Edge verifica se o URI de redirecionamento enviado do aplicativo de login corresponde ao URI de redirecionamento especificado quando o aplicativo foi registrado no Apigee Edge. Se tudo estiver certo, o Edge gerará um código de autorização. Exemplo:

http://myorg-test.apigee.net/oauth/authorizationcode?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

6. O Edge envia o código de autorização de volta ao cliente

O Edge envia um redirecionamento 302 com o código de autenticação anexado como um parâmetro de consulta ao cliente.

7. O cliente recupera o código de autorização e solicita um código de acesso do Edge.

Agora, com um código de autenticação válido, o cliente pode solicitar um token de acesso do Edge. Ele faz isso chamando o ID do cliente e as chaves secretas do cliente, recebidas quando o app foi registrado no Edge, o tipo de concessão e o escopo. Ao incluir o ID do cliente e as chaves secretas, o Apigee Edge pode verificar se o app cliente foi registrado. Exemplo:

$ curl https://{org_name}-test.apigee.net/my_oauth_proxy/accesstoken?code=Xyz123&grant_type=authorization_code -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpKNhGar6K&client_secret=hAr4GngA9vAyvI4'

8. O cliente recebe um token de acesso.

Se tudo for bem-sucedido, o Edge retornará um token de acesso ao cliente. O token de acesso terá uma validade e será válido apenas para o escopo especificado pelo usuário ao conceder que o app acesse seus recursos.

9. O cliente chama a API protegida

Agora, com um código de acesso válido, o cliente pode fazer chamadas à 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. Os tokens de acesso são transmitidos em um cabeçalho de autorização. Exemplo:

$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

Como configurar fluxos e políticas

Como o servidor de autorização, o Edge precisa processar diversas solicitações OAuth: para tokens de acesso, códigos de autenticação, tokens de atualização, redirecionamentos da página de login, etc. Há duas etapas fundamentais para configurar esses endpoints:

Como criar fluxos personalizados
Como adicionar e configurar políticas do OAuthV2

Configuração de fluxo personalizada

Normalmente, esse fluxo de concessão é configurado para que cada etapa ou "perna" do fluxo seja definida por um fluxo no proxy Apigee Edge. Cada fluxo tem um endpoint e uma política que executa a tarefa específica do OAuth necessária, como gerar um código de autorização ou um token de acesso. Por exemplo, como mostrado no XML abaixo, o endpoint /oauth/authorizationcode tem uma política associada chamada GenerateAuthCode, que é uma política OAuthV2 com a / operação GenerateAuthorizationCode especificada.

A maneira mais fácil de mostrar a configuração do fluxo é com um exemplo de XML. Consulte os comentários in-line para informações sobre cada fluxo. Exemplo: os nomes de fluxos e caminhos podem ser configurados da maneira que quiser. Consulte também Como configurar endpoints e políticas do OAuth para uma visão geral rápida das etapas necessárias para criar um fluxo personalizado como esse.

Veja também o exemplo de implementação no GitHub.

<Flows>
  <Flow name="RedirectToLoginApp">
         <!-- 
         Publish this URI to developers to use for their 'login' link 
         -->
    <Condition>proxy.pathsuffix == "/oauth/authorize"</Condition>
    <Request>
        <Step><Name>RedirectToLoginPage</Name></Step>
    </Request>
  </Flow>
  <Flow name="GetAuthCode">
         <!-- 
         Call this URL from your Login app after you authenticate the user.
         The policy will automatically return the auth code in the response to the 
         redirect_uri registered by the calling app 
         -->
    <Condition>proxy.pathsuffix == "/oauth/authorizationcode"</Condition>
    <Request>
        <Step><Name>GenerateAuthCode</Name></Step>
    </Request>
  </Flow>
  <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>GenerateAccessToken</Name></Step>
    </Request>
  </Flow>
</Flows>

Configurar os fluxos com políticas

Cada endpoint tem uma política associada a ele. Vejamos exemplos das políticas. Consulte também Como configurar endpoints e políticas do OAuth para uma visão geral rápida das etapas necessárias para adicionar políticas do OAuthV2 aos endpoints do proxy.

Esse é o caminho /oauth/authorize. A política anexada é responsável por redirecionar o usuário para um app de login, em que o usuário final pode autenticar e autorizar com segurança o app de cliente para acessar os recursos protegidos sem divulgar o nome de usuário e a senha com o app de cliente. É possível fazer isso com uma política de chamada de serviço, JavaScript, Node.js ou outros meios.

A chamada de API para fazer a solicitação é um GET e requer os parâmetros de consulta client_id, response_type, redirect_uri, escopo e estado.

$ curl http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

Receber código de autorização

Esse é o caminho /oauth/authorizationcode. Ele usa a política OAuthV2 com a operação GenerateAuthorizationCode especificada.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="GetAuthCode">
    <DisplayName>GetAuthCode</DisplayName>
    <Operation>GenerateAuthorizationCode</Operation>
    <ExpiresIn>600000</ExpiresIn>
    <GenerateResponse/>
</OAuthV2>

A chamada de API para obter o código de autorização é um GET e requer os parâmetros de consulta client_id, response_type e, opcionalmente, o escopo e o estado, conforme mostrado neste exemplo:

$curl http://myorg-test.apigee.net/oauth/authorizationcode?client_id={consumer_key}&response_type=code&scope=scope1%20scope2&state={some_string}

Receber token de acesso

Essa política está anexada ao caminho /oauth/accesstoken. Ela usa a política OAuthV2 com a operação GenerateAccessCode especificada. Nesse caso, o parâmetro "grant_type" é esperado como um parâmetro de consulta:

<OAuthV2 name="GetAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>360000000</ExpiresIn> 
    <SupportedGrantTypes> 
        <GrantType>authorization_code</GrantType> 
    </SupportedGrantTypes> 
    <GrantType>request.queryparam.grant_type</GrantType> 
    <GenerateResponse/> 
</OAuthV2>

A chamada de API para receber o código de acesso é um POST e precisa incluir o client_id, client_secret, grant_type=authorization_code e, opcionalmente, o escopo. Exemplo:

$ curl https://{org_name}-test.apigee.net/oauth/accesstoken?grant_type=authorization_code -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'

Esse é apenas um resumo básico. Um exemplo de produção inclui muitas outras políticas para criar URLs, fazer transformações e executar outras tarefas. Consulte a amostra no GitHub para ver um projeto completo e funcionando.

Como anexar a política de verificação de tokens de acesso

Anexe uma política VerifyAccessToken, que é uma política do OAuthV2 com a operação VerifyAccessToken especificada, ao início de qualquer fluxo que acesse uma API protegida. Dessa maneira, ela será executada sempre que houver uma solicitação de recursos protegidos. O Edge verifica se cada solicitação tem um token de acesso válido. Caso contrário, um erro será retornado. 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.