Proteja uma API com o OAuth

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

O que você vai aprender

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

Neste tutorial, você aprende a proteger uma API com o OAuth 2.0.

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 mais básico 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 Edge é 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.

Pré-requisitos

  • Uma conta do Apigee Edge. Se você ainda não tiver uma, inscreva-se com as instruções em Como criar uma conta do Apigee Edge.
  • cURL instalado na máquina para fazer chamadas de API a partir da linha de comando.

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 https://apigee.com/edge e faça login.
  3. Selecione Develop > API Proxies na barra de navegação à esquerda.
  4. Clique em + Proxy.
    Botão "Criar proxy"
  5. No assistente Criar proxy, clique em Fazer upload do pacote de proxy.
  6. Escolha o arquivo oauth.zip que você transferiu por download e clique em Next.
  7. Clique em Criar.
  8. Quando a criação for concluída, clique em Editar proxy para ver o novo proxy no editor de proxy da API.
  9. Na página "Visão geral" do editor de proxy da API, clique na lista suspensa Implantação e selecione teste. Este é o ambiente de teste da sua organização.

    No prompt de confirmação, clique em Implantar.
    Ao clicar novamente na lista suspensa de implantação, um ícone verde indica que o proxy está implantado no ambiente de teste.

Muito bem! Você fez o download e implantou um proxy de API que gera o token de acesso à organização do Edge.

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 Desenvolver. No painel Navigator à esquerda, você verá duas políticas. Você também verá dois fluxos POST na seção Proxy Endpoints.
  2. Clique em AccessTokenClientCredential em Proxy 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 de 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 millseconds, 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

Sobre o "mocktarget"

O serviço mocktarget é hospedado na Apigee e retorna dados simples. Na verdade, é possível acessá-lo em um navegador da Web. Para testar, clique no seguinte:

http://mocktarget.apigee.net/ip

O destino retorna o que você verá quando chamar esse proxy de API.

Você também pode pressionar http://mocktarget.apigee.net/help para ver outros recursos da API disponíveis no simulado.

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 + Proxy.
    Botão &quot;Criar proxy&quot;
  3. No assistente Criar um proxy, selecione Proxy reverso (mais comum) e clique em Próximo.
  4. Configure o proxy da seguinte forma:
    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 o Apigee Edge 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 Selecione: OAuth 2.0
  7. Clique em Next.
  8. Na página Virtual Hosts, clique em Next.
  9. Na página Build, verifique se o ambiente de teste está selecionado e clique em Criar e implantar.
  10. Na página Resumo, você vê uma confirmação de que o novo proxy de API foi criado e de que o proxy de API foi implantado no ambiente de teste.
  11. Clique em Editar proxy para exibir a página Visão geral do proxy de API.
    Desta vez, o proxy de API é implantado automaticamente. Clique na lista suspensa de implantação para garantir que haja um ponto de implantação verde ao lado do ambiente de "teste".

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 autorização de cabeçalho: uma política AttributionMessage que remove o token de acesso após a verificação para que ele não seja transmitido ao 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 de API.
  3. Insira os Detalhes do produto para seu 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. Por exemplo, helloworld_oauth2-Product
    Nome de exibição Nome de exibição do produto de API. O nome de exibição é usado na interface e pode ser editado a qualquer momento. Se não for especificado, o valor Nome será usado. Esse campo é preenchido automaticamente com o valor "Nome". Você pode editar ou excluir o conteúdo dele. O nome de exibição pode incluir caracteres especiais. Por exemplo, helloworld_oauth2-Product.
    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. Por exemplo, test.
    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 permitidos Ignorar para este tutorial.
  4. No campo Proxies de API, selecione o proxy de API que você acabou de criar.
  5. No campo Caminho, insira "/". Ignore os outros campos.
  6. Clique em Salvar.

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 a você, o provedor da API, um controle mais granular sobre o acesso às APIs e relatórios mais detalhados sobre o tráfego da API, porque o Edge sabe qual desenvolvedor e aplicativo pertencem a qual 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 New Developer:
    Neste campo Enter
    Nome Nigel
    Sobrenome Tufnel
    Username nigel
    E-mail nigel@example.com
  4. Clique em Criar.

Registrar um aplicativo

Vamos criar um aplicativo para o Nigel.

  1. Selecione Publicar > Apps.
  2. Clique em + App.
  3. Digite o seguinte na janela New 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. Selecione helloworld_oauth2-Product.
  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 o token/secret está associado ao "helloworld_oauth2-Product" que foi criado automaticamente.

  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)

Para começar, tente chamar o proxy de API protegido que deve retornar seu endereço IP. Execute o comando cURL a seguir em uma janela de terminal, substituindo o nome da organização do Edge. A palavra test no URL é o ambiente de teste da organização. Ele foi usado para implantar os proxies. O caminho base de proxy é /hellooauth2, o mesmo que você especificou ao criar o proxy. Observe que você não está transmitindo um token de acesso OAuth na chamada.

curl https://ORG_NAME-test.apigee.net/hellooauth2

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.

Agora verificaremos as maiores vantagens. Você está prestes a usar o token e o secret que você copiou e colou em um arquivo de texto e trocá-los 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 a chave e o secret, faça a seguinte chamada de cURL (observe que o protocolo é https), substituindo o nome da organização do Edge, a chave e o secret, quando indicado:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
"https://ORG_NAME-test.apigee.net/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, client_id e client_secret vão estar 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 dizia se o URI do recurso é /accesstoken e o verbo da solicitação é POST, para executar a política OAuth GenerateAccessTokenClient 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 sua organização de Edge e o token de acesso.

curl https://ORG_NAME-test.apigee.net/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 OAuth válido fosse incluído na chamada.

Temas relacionados