Proteja uma API com o OAuth

Você está vendo a documentação da Apigee X.
Ver a documentação da Apigee Edge.

Neste tutorial, explicamos como:

  • Faça o download e implante um proxy de API de amostra.
  • Crie um proxy de API protegido por OAuth.
  • Crie um produto, desenvolvedor e aplicativo.
  • Credenciais do Exchange para um token de acesso OAuth.
  • Chamar uma API com um token de acesso.

O OAuth é um protocolo de autorização que permite que os apps acessem informações em nome dos usuários sem que eles precisem divulgar o nome de usuário e a senha.

Com o OAuth, as credenciais de segurança (como nome de usuário/senha ou token/secret) são trocadas por um token de acesso. Exemplo:

joe:joes_password (nome de usuário:senha) ou
Nf2moHOASMJeUmXVdDhlMbPaXm2U7eMc:unUOXYpPe74ZfLEb (token:secret)

se torna algo como:

b0uiYwjRZLEo4lEu7ky2GGxHkanN

O token de acesso é uma string aleatória de caracteres e é temporário (ele precisa expirar após um tempo relativamente curto). Portanto, passá-lo para autenticar um usuário em um fluxo de trabalho de aplicativos é muito mais seguro do que passar as credenciais reais.

A especificação OAuth 2.0 define diferentes mecanismos, chamados de "tipos de concessão", para distribuir tokens de acesso para aplicativos. O tipo de concessão definido pelo OAuth 2.0 é chamado de "credenciais do cliente". Nesse tipo de concessão, os tokens de acesso OAuth são gerados em troca de credenciais do cliente, que são pares de tokens/secrets do cliente, como no exemplo acima.

O tipo de concessão de credenciais de cliente no Apigee é implementado usando políticas em proxies de API. Um fluxo OAuth comum envolve duas etapas:

  • Chame o proxy de API 1 para gerar um token de acesso OAuth a partir de credenciais de cliente. Uma política do OAuth v2.0 no proxy de API lida com isso.
  • Chame o proxy de API 2 para enviar o token de acesso OAuth em uma chamada de API. O proxy da API verifica o token de acesso usando uma política do OAuth v2.0.

Fazer o download e implantar um proxy de API que gera um token

Nesta etapa, você criará o proxy de API que gera um token de acesso OAuth a partir de um token ou secret do cliente enviados em uma chamada de API. A Apigee fornece um exemplo de proxy de API que faz isso. Faça o download e a implantação do proxy agora. Em seguida, use-o posteriormente no tutorial. Você mesmo pode criar esse proxy de API. Essa etapa de download e implantação é conveniente para facilitar o compartilhamento dos proxies que já foram criados.

  1. Faça o download do arquivo de amostra proxy da API do "Oauth" para qualquer diretório no seu sistema de arquivos.
  2. Acesse a IU da Apigee e faça login.
  3. Selecione Develop > API Proxies na barra de navegação à esquerda.
  4. Clique em Criar nova.
    Botão "Criar proxy"
  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 na lista suspensa Revisão e selecione o número de revisão para implantar o proxy.

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

Vamos dar uma olhada no que está o proxy da API.

  1. No editor de proxy da API, clique na guia Desenvolvedor. 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 (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 no ícone da política GenerateAccessTokenClient no diagrama de fluxo.

    A seguinte configuração de XML é carregada na visualização de código:

    <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 que precisa ser usado é client_credentials (alterando um token e um segredo de cliente para um token OAuth).
    • 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. Mas, primeiro, você precisa fazer mais algumas coisas:

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

Criar o proxy da API protegido pelo OAuth

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. Mas, você a verá somente se passar um token de acesso OAuth válido com sua chamada de API.

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

  1. Selecione Develop > API Proxies na barra de navegação à esquerda.
  2. Clique em Criar nova.
    Botão &quot;Criar proxy&quot;
  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
  5. Clique em Next.
  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 Next.
  8. Na página Resumo, em Implantação opcional, selecione um ambiente e clique em Criar.
  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.

  1. No editor de proxy da API, clique na guia Desenvolvedor. 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 OAuth válido.
    • 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 OAuth, você não usará essa política.
  2. Clique no ícone Verificar o token de acesso do OAuth v2.0 na visualização de fluxo e observe o XML abaixo dele 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 OAuth válido na solicitação.

Adicionar um produto de API.

Para adicionar um produto de API usando a IU da Apigee:

  1. Selecione Publicar > Produtos da API.
  2. Clique em +Produto da API.
  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.
    Acesse 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 permitidos Ignorar para este tutorial.
  4. Na seção "Recursos de API", adicione o proxy de API que você acabou de criar.
  5. Na seção "Caminhos", adicione o caminho "/".
  6. Clique em Save.

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 OAuth.

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 Enter
    Nome Nigel
    Sobrenome Tufnel
    Username nigel
    E-mail nigel@example.com
  4. Clique em Save.

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 (nigel@example.com)
    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.

  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 OAuth.

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 OAuth na chamada.

curl -v -k https://EXTERNAL_IP/hellooauth2

Em que EXTERNAL_IP é o endereço do endereço IP voltado à Internet, conforme definido quando a Apigee foi instalada. Consulte Configurar roteamento.

Como o proxy da API tem a verificação de política Verificar token de acesso OAuth v2.0 para um token OAuth 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 OAuth válido podem chamar essa API.

Providencie um token de acesso do OAuth2.

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 OAuth. 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://EXTERNAL_IP/oauth/client_credential/accesstoken?grant_type=client_credentials" \
-d "client_id={key}&client_secret={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" : "nigel@example.com",
  "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. Copie o valor de access_token (sem as aspas) e cole-o no seu 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 que gera um token de acesso? Como o comando cURL atendeu a essas condições, a política do OAuth foi executada. Ele verificou o token e o segredo do cliente e os trocou por um token OAuth 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 organização da Apigee e o token de acesso (remova as chaves).

curl https://EXTERNAL_IP/hellooauth2 -H "Authorization: Bearer {access-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 OAuth válido fosse incluído na chamada.

Temas relacionados