Proteger uma API com o OAuth 2.0

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

Confira a documentação da Apigee Edge.

Neste tutorial, mostramos como proteger um proxy de API usando um token de acesso do OAuth 2.0.

Antes de começar

Para concluir este tutorial, você precisa ter acesso a uma organização da Apigee em que tenha permissão para:

• criar e implantar proxies de API;
• criar produtos de API;
• criar apps de desenvolvedor.

Também é necessário ter um nome de host de grupo de ambiente configurado corretamente para fazer chamadas de proxy da API da Apigee. Se você não tiver certeza sobre qual nome de host do grupo de ambiente usar, consulte seu administrador da Apigee.

Implantar o proxy do OAuth 2.0

Fornecemos um proxy de API no GitHub configurado para gerar tokens de acesso do OAuth 2.0. Siga estas etapas para fazer o download e implantar o proxy de API no seu ambiente:

1. Faça o download do proxy de API de amostra oauth em um diretório no sistema de arquivos.
2. Acesse a IU da Apigee, faça login e selecione sua organização da Apigee.
3. Selecione Desenvolver > Proxies de API na barra de navegação à esquerda.
   Observação: antes de continuar, pesquise na sua lista de proxies da API. Se você já tiver um chamado oauth, clique nele e pule para a próxima seção para garantir que ele esteja configurado da mesma forma que é descrita. Mas se seu caso for diferente, exclua-o e continue essas etapas ou modifique-o para corresponder à configuração descrita.
4. Clique em Criar nova.
   
5. No assistente "Criar proxy", selecione Fazer upload de pacote de proxy.
6. Escolha o arquivo oauth.zip que você recebeu por download e clique em Próximo.
7. Clique em Criar.
8. Quando a criação for concluída, clique em Editar proxy para visualizar o novo proxy no editor de proxy de API.
9. Clique em Implantar.
10. Selecione a revisão e o ambiente em que a implantação será feita. Deixe o campo Conta de serviço em branco.
11. Clique em Implantar.

Você fez o download e implantou um proxy de API que gera o token de acesso à organização da Apigee.

Ver o fluxo e a política do OAuth 2.0

Reserve alguns instantes para examinar a configuração da política do OAuth 2.0.

Observação: a Apigee está introduzindo uma nova versão do Editor de Proxy, que facilitará o gerenciamento de proxies.

As instruções nas duas primeiras guias abaixo explicam como usar o novo Editor de proxy ou o Proxy Editor clássico.

Novo Editor de proxy

A seguir, você verá o que o proxy de API contém mais detalhadamente.

1. No editor de proxy da API, clique na guia Desenvolver.

   

   No painel à esquerda, você verá duas políticas. Você também verá dois fluxos POST na seção "Endpoints de proxy".

2. Clique em AccessTokenClientCredential em Proxy de Endpoints. O editor de texto mostra o código XML para o fluxo condicional AccessTokenClientCredential:

   <Flow name="AccessTokenClientCredential">
       <Description/>
       <Request>
           <Step>
               <Name>GenerateAccessTokenClient</Name>
           </Step>
       </Request>
       <Response/>
       <Condition>(proxy.pathsuffix MatchesPath "/accesstoken") and (request.verb = "POST")</Condition>
   </Flow>

   Um fluxo é uma etapa de processamento em um proxy de API. Nesse caso, o fluxo é acionado quando uma determinada condição é atendida (chamado de "fluxo condicional"). A condição, definida no elemento <Condition>, informa que, se a chamada de proxy de API for feita para o recurso /accesstoken e o verbo da solicitação for POST, execute a política GenerateAccessTokenClient, que gera o token de acesso.

3. Agora, vamos analisar a política que será acionada pelo fluxo condicional. Clique na política GenerateAccessTokenClient no painel Solicitação:

Editor de Proxy clássico

A seguir, você verá o que o proxy de API contém mais detalhadamente.

1. No editor de proxy da API, clique na guia Desenvolver. No painel esquerdo do Navegador, você verá duas políticas. Você também verá dois fluxos POST na seção "Endpoints de proxy".

2. Clique em AccessTokenClientCredential em "Proxy de Endpoints".
   

   Na visualização do código XML, você verá um Flow chamado AccessTokenClientCredential:

   <Flow name="AccessTokenClientCredential">
       <Description/>
       <Request>
           <Step>
               <Name>GenerateAccessTokenClient</Name>
           </Step>
       </Request>
       <Response/>
       <Condition>(proxy.pathsuffix MatchesPath "/accesstoken") and (request.verb = "POST")</Condition>
   </Flow>

   Um fluxo é uma etapa de processamento em um proxy de API. Nesse caso, o fluxo é acionado quando uma determinada condição é atendida. A condição, definida no elemento <Condition>, informa que, se a chamada de proxy de API for feita para o recurso /accesstoken e o verbo da solicitação for POST, execute a política GenerateAccessTokenClient, que gera o token de acesso.

3. Agora, vamos analisar a política que será acionada pelo fluxo condicional. Clique no ícone da política GenerateAccessTokenClient no diagrama de fluxo.

   

A seguinte configuração XML será exibida:

<OAuthV2 name="GenerateAccessTokenClient">
    <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
    <Operation>GenerateAccessToken</Operation>
    <!-- This is in milliseconds, so expire in an hour -->
    <ExpiresIn>3600000</ExpiresIn>
    <SupportedGrantTypes>
        <!-- This part is very important: most real OAuth 2.0 apps will want to use other
         grant types. In this case it is important to NOT include the "client_credentials"
         type because it allows a client to get access to a token with no user authentication -->
        <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <GrantType>request.queryparam.grant_type</GrantType>
    <GenerateResponse/>
</OAuthV2>

A configuração inclui o seguinte:

• O <Operation>, que pode ser um dos vários valores predefinidos, define o que a política fará. Nesse caso, ele gerará um token de acesso.
• O token expirará 1 hora (3.600.000 milissegundos) após ser gerado.
• Em <SupportedGrantTypes>, o <GrantType> do OAuth 2.0 que precisa ser usado é client_credentials (alterando um token e um segredo de cliente para um token do OAuth 2.0).
• O segundo elemento <GrantType> informa à política onde procurar na chamada da API o parâmetro de tipo de concessão, conforme exigido pela especificação do OAuth 2.0. Você verá isso na chamada de API mais tarde. O tipo de concessão também pode ser enviado no cabeçalho HTTP (request.header.grant_type) ou como um parâmetro de formulário (request.formparam.grant_type).

Você não precisa fazer mais nada com o proxy da API no momento. Nas etapas posteriores, você usará esse proxy da API para gerar um token de acesso OAuth 2.0. Mas, primeiro, você precisa fazer mais algumas coisas:

• Crie o proxy de API que você quer proteger com o OAuth 2.0.
• Crie mais alguns artefatos que resultarão no token e no segredo do consumidor necessários para trocar por um token de acesso.

Observação: o fluxo e a política RefreshAccessToken no proxy de API não são usados neste tutorial e não são compatíveis com o tipo de concessão de credenciais do cliente do OAuth 2.0.

Criar um proxy de API protegido

Agora você criará o proxy de API que quer proteger. É a chamada de API que retorna algo que você quer. Nesse caso, o proxy da API chamará o serviço simulado da Apigee para retornar seu endereço IP. Porém, você a verá somente se transmitir um token de acesso do OAuth 2.0 válido com a chamada de API.

O proxy de API criado aqui incluirá uma política que verifica se há um token do OAuth 2.0 na solicitação.

1. Selecione Desenvolver > Proxies de API na barra de navegação à esquerda.
2. Clique em Criar nova.
   
3. No assistente de criação de proxy, selecione Proxy reverso (mais comum).
4. Configure o proxy com o seguinte:
   

   Neste campo	faça isso
   Nome do proxy	Insira: helloworld_oauth2
   Caminho base do projeto	Altere para: /hellooauth2 O caminho base do projeto faz parte do URL usado para fazer solicitações ao proxy da API.
   API atual	Insira: https://mocktarget.apigee.net/ip Isso define o URL de destino que a Apigee invoca em uma solicitação ao proxy de API.
   Descrição	Insira: hello world protected by OAuth 2.0

5. Clique em Próxima.
6. Na página Políticas comuns:

   Neste campo	faça isso
   Segurança: autorização	Selecionar: OAuth 2.0 Essas opções são muito úteis. Elas adicionam automaticamente duas políticas ao proxy da API e criam um produto de API.

7. Clique em Próxima.
8. Na página Resumo, em Implantação opcional, selecione um ambiente e clique em Criar e implantar.
9. Clique em Editar proxy para exibir a página Visão geral do proxy de API.
   O proxy de API é implantado automaticamente para você. Pode levar alguns instantes para a implantação ser concluída.

Ver as políticas

Vamos examinar com mais detalhes o que você criou.

Novo Editor de proxy

1. No editor de proxy da API, clique na guia Desenvolver. Você verá que duas políticas foram adicionadas ao fluxo de solicitações do proxy da API:
   • Verificar o token de acesso do OAuth v2.0: verifica a chamada da API para garantir a presença de um token válido do OAuth 2.0.
   • Remover cabeçalho de autorização: uma política de atribuição de mensagem que remove o token de acesso após a verificação para que ele não seja transmitido para o serviço de destino. Se o serviço de destino precisar do token de acesso do OAuth 2.0, você não usará essa política.

2. Clique no ícone Verificar token de acesso OAuth v2.0 no painel à direita e veja o XML abaixo dele no editor de texto.

Editor de Proxy clássico

1. No editor de proxy da API, clique na guia Desenvolver. Você verá que duas políticas foram adicionadas ao fluxo de solicitações do proxy da API:
   • Verificar o token de acesso do OAuth v2.0: verifica a chamada da API para garantir a presença de um token válido do OAuth 2.0.
   • Remover cabeçalho de autorização: uma política de atribuição de mensagem que remove o token de acesso após a verificação para que ele não seja transmitido para o serviço de destino. Se o serviço de destino precisar do token de acesso do OAuth 2.0, você não usará essa política.

2. Clique no ícone Verificar o token de acesso do OAuth v 2.0 na visualização de fluxo e observe o XML abaixo no painel de código.

   

<OAuthV2 async="false" continueOnError="false" enabled="true" name="verify-oauth-v2-access-token">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <Operation>VerifyAccessToken</Operation>
</OAuthV2>

Observe que <Operation> é VerifyAccessToken. A operação define o que a política deve fazer. Nesse caso, ela verificará se há um token do OAuth 2.0 válido na solicitação.

Adicionar um produto de API.

Para receber um token de acesso do OAuth 2.0, você precisa criar três entidades da Apigee: um produto de API, um desenvolvedor e um app para desenvolvedores. Primeiro, crie o produto de API:

1. Selecione Publicar > Produtos da API.
2. Clique em Criar.
3. Insira os detalhes do produto do produto de API.
   

   Campo	Descrição
   Nome	Nome interno do produto de API. Não especifique caracteres especiais no nome. Observação: não é possível editar o nome depois que o produto da API é criado.
   Nome de exibição	Nome de exibição do produto de API. O nome de exibição é usado na IU e é possível editá-lo a qualquer momento. Se não for especificado, o valor Nome será usado. Esse campo é preenchido automaticamente com o valor do nome. você pode editar ou excluir o conteúdo. O nome de exibição pode incluir caracteres especiais.
   Descrição	Descrição do produto de API.
   Ambiente	Ambientes em que o produto de API permitirá acesso. Selecione o ambiente em que você implantou o proxy de API.
   Acesso	Selecione Público.
   Aprovar automaticamente solicitações de acesso	Ativar a aprovação automática das solicitações de chave deste produto de API em qualquer app.
   Cota	Ignorar para este tutorial.
   Escopos do OAuth 2.0 permitidos	Ignorar para este tutorial.

4. Na seção Operações, clique em Adicionar uma operação.
5. No campo "API Proxy", selecione o proxy de API que você acabou de criar.
6. No campo "Caminho", digite "/". Ignore os outros campos.
7. Clique em Salvar para salvar a operação.
8. Clique em Salvar para salvar o produto da API.

Adicionar um desenvolvedor e um app à sua organização

Em seguida, simule o fluxo de trabalho de um desenvolvedor se inscrevendo para usar suas APIs. O ideal é que os desenvolvedores registrem a si mesmos e seus aplicativos por meio do portal do desenvolvedor. Nesta etapa, no entanto, adicione um desenvolvedor e um app como administrador.

Um desenvolvedor terá um ou mais apps que chamam suas APIs e cada app recebe um token ou secret de cliente exclusivo. Esse token/secret por aplicativo também oferece ao provedor da API um controle mais granular sobre o acesso às APIs e relatórios mais detalhados sobre o tráfego da API, porque a Apigee sabe qual desenvolvedor e aplicativo pertencem a que token do OAuth 2.0.

Crie um desenvolvedor

Vamos criar um desenvolvedor chamado Nigel Tufnel.

1. Selecione Publicar > Desenvolvedores no menu.
2. Clique em + Desenvolvedor.
3. Digite o seguinte na janela "Novo desenvolvedor":
   

   Neste campo	Tecla Enter
   Nome	Nigel
   Sobrenome	Tufnel
   Nome de usuário	nigel
   E-mail	[e-mail]

4. Clique em Salvar.

Registrar um aplicativo

Vamos criar um aplicativo para o Nigel.

1. Selecione Publicar > Apps.
2. Clique em + App.
3. Digite o seguinte na janela "Novo app":
   

   Neste campo	faça isso
   Nome e nome de exibição	Insira: nigel_app
   Desenvolvedor	Clique em Desenvolvedor e selecione: Nigel Tufnel ([e-mail])
   Callback URL e Observações	Deixar em branco

4. Em Produtos, clique em Adicionar produto.
5. Adicione o produto de API que você acabou de criar.
6. Clique em Criar.

Receber o token e o secret do consumidor

Agora você receberá o token e o secret do cliente que serão trocados por um token de acesso do OAuth 2.0.

1. Verifique se a página nigel_app é exibida. Se não, na página "Apps" (Publicar > Apps), clique em nigel_app.

2. Na página nigel_app, clique em Mostrar nas colunas Token e Secret. Observe que a chave/secret está associada ao produto de API que você criou anteriormente.

3. Selecione e copie o token e o segredo. Cole-os em um arquivo de texto temporário. Você os usará em uma etapa posterior, onde chamará o proxy de API que trocará essas credenciais por um token de acesso do OAuth 2.0.

Tente chamar a API para saber seu endereço IP (falha)

Tente chamar o proxy da API protegida que você acabou de criar. Observe que você não está transmitindo um token de acesso do OAuth 2.0 na chamada.

em que YOUR ENV_GROUP_HOSTNAME é o nome do host do grupo de ambiente. Consulte Encontrar o nome do host do grupo de ambientes.

Como o proxy da API tem a verificação de política Verificar token de acesso do OAuth v2.0 para um token do OAuth 2.0 válido na solicitação, a chamada falhará com a seguinte mensagem:

{"fault":{"faultstring":"Invalid access token","detail":{"errorcode":"oauth.v2.InvalidAccessToken"}}}

Nesse caso, a falha é bem-vinda. Isso significa que o proxy da API é muito mais seguro. Somente os apps confiáveis com um token de acesso do OAuth 2.0 válido podem chamar essa API.

Receber um token de acesso do OAuth 2.0

Em seguida, use a chave e o secret que você copiou e colou em um arquivo de texto e troque-os por um token de acesso do OAuth 2.0. Agora, você fará uma chamada de API para o proxy de amostra da API que você importou e o oauth, que gerará um token de acesso à API.

Usando essa chave e o secret, faça a seguinte chamada cURL (observe que o protocolo é https):

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
"https://YOUR ENV_GROUP_HOSTNAME/oauth/client_credential/accesstoken?grant_type=client_credentials" \
-d "client_id=CLIENT_KEY&client_secret=CLIENT_SECRET"

Se você estiver usando um cliente como o Postman para fazer a chamada, o client_id e o client_secret vão no corpo da solicitação e precisam ser x-www-form-urlencoded.

Você deve receber uma resposta como esta:

{
  "issued_at" : "1466025769306",
  "application_name" : "716bbe61-f14a-4d85-9b56-a62ff8e0d347",
  "scope" : "",
  "status" : "approved",
  "api_product_list" : "[helloworld_oauth2-Product]",
  "expires_in" : "3599", //--in seconds
  "developer.email" : "[e-mail]",
  "token_type" : "BearerToken",
  "client_id" : "xNnREu1DNGfiwzQZ5HUN8IAUwZSW1GZW",
  "access_token" : "GTPY9VUHCqKVMRB0cHxnmAp0RXc0",
  "organization_name" : "myOrg",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

Você recebeu seu token de acesso do OAuth 2.0. Copie o valor access_token (sem as aspas) e cole-o no arquivo de texto. Ele será usado em alguns instantes.

O que aconteceu?

Você se lembra de quando analisou esse "fluxo condicional" no proxy oauth, aquele que informou se o URI do recurso é /accesstoken e o verbo de solicitação é POST, para executar a política GenerateAccessTokenClient do OAuth 2.0 que gera um token de acesso? Como o comando cURL atendeu a essas condições, a política do OAuth 2.0 foi executada. Ele verificou o token e o segredo do cliente e os trocou por um token do OAuth 2.0 que expira em uma hora.

Chame a API com um token de acesso (com êxito).

Agora que você tem um token de acesso, use-o para chamar o proxy da API. Faça a chamada cURL a seguir. Substitua o nome da sua organização da Apigee e o token de acesso.

curl https://YOUR ENV_GROUP_HOSTNAME/hellooauth2 -H "Authorization: Bearer TOKEN"

Agora você deve receber uma chamada bem-sucedida para o proxy da API que retorna seu endereço IP. Exemplo:

{"ip":"::ffff:192.168.14.136"}

Repita essa chamada de API para perto de uma hora. Depois desse tempo, o token de acesso expirará. Para fazer a chamada após uma hora, gere um novo token de acesso usando as etapas anteriores.

Parabéns! Você criou um proxy de API e o protegeu exigindo que um token de acesso do OAuth 2.0 válido fosse incluído na chamada.

Temas relacionados

• Página inicial do OAuth 2.0
• Política do OAuthV2
• Fazer o download de proxies de API (mostra como agrupar um proxy de API em um arquivo ZIP, como o arquivo salvo)