Esta página foi traduzida pela API Cloud Translation.

Proteja uma API com o OAuth 2.0

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Este tutorial mostra como proteger um proxy de API com um token de acesso do OAuth 2.0.

Antes de começar

Para concluir este tutorial, tem de ter acesso a uma organização do Apigee onde tem autorização para:

Crie e implemente proxies de API
Crie produtos de API
Crie apps de programador

Também tem de ter um nome de anfitrião do grupo de ambientes configurado corretamente com o qual pode fazer chamadas de proxy da API Apigee. Se não tiver a certeza sobre o nome do anfitrião do grupo de ambientes a usar, consulte o seu administrador do Apigee.

Implemente o proxy OAuth 2.0

Disponibilizamos um proxy de API no GitHub que está configurado para gerar tokens de acesso OAuth 2.0. Siga estes passos para transferir e implementar este proxy de API no seu ambiente:

Transfira o oauthproxy da API de exemplo para um diretório no seu sistema de ficheiros.

Apigee na Cloud Console

Na Google Cloud consola, aceda à página Desenvolvimento de proxy > Proxies de API.

Aceda aos proxies de API

Nota: antes de continuar, procure ou pesquise na sua lista de proxies de API. Se já tiver um chamado oauth, clique nele e avance para a secção seguinte para se certificar de que está configurado da mesma forma que o descrito. Se for diferente, elimine-o e continue com estes passos ou modifique-o para corresponder à configuração descrita.
No painel Proxies de API, clique em + Criar.
No painel Criar um proxy, em Modelo de proxy, selecione Carregar pacote de proxy.
Escolha o ficheiro oauth.zip que transferiu e clique em Seguinte.
Clicar em Seguinte.
Implementar (opcional):
- Ambientes de implementação: opcional. Use as caixas de verificação para selecionar um ou mais ambientes nos quais implementar o seu proxy. Se preferir não implementar o proxy neste ponto, deixe o campo Ambientes de implementação vazio. Pode sempre implementar o proxy mais tarde.
- Conta de serviço: opcional. Anexe uma conta de serviço à sua implementação para permitir que o proxy aceda aos serviços, conforme especificado na função e nas autorizações da conta de serviço. Google Cloud
Clique em Criar.

Apigee clássico

Aceda à IU do Apigee, inicie sessão e selecione a sua organização do Apigee.
Selecione Desenvolver > Proxies de API na barra de navegação do lado esquerdo.
Nota: antes de continuar, procure ou pesquise na sua lista de proxies de API. Se já tiver um chamado oauth, clique nele e avance para a secção seguinte para se certificar de que está configurado da mesma forma que o descrito. Se for diferente, elimine-o e continue com estes passos ou modifique-o para corresponder à configuração descrita.
Clique em Criar novo.
No assistente Criar proxy, selecione Carregar pacote de proxy.
Escolha o ficheiro oauth.zip que transferiu e clique em Seguinte.
Clique em Criar.
Após a compilação estar concluída, clique em Editar proxy para ver o novo proxy no editor de proxy de API.
Clique em Implementar.
Selecione a revisão e o ambiente para implementar. Pode deixar o campo Conta de serviço em branco.
Clique em Implementar.

Transferiu e implementou com êxito um proxy de API de geração de tokens de acesso na sua organização do Apigee.

Veja o fluxo e a política do OAuth 2.0

Dedique alguns momentos a examinar a configuração da política de OAuth 2.0.

Consola do Apigee Cloud

Em seguida, vai analisar mais detalhadamente o que o proxy de API contém.

No editor de proxy de API, clique no separador Desenvolver.

No painel do lado esquerdo, são apresentadas duas políticas. Também vê dois fluxos POST na secção Proxy Endpoints.
Clique em AccessTokenClientCredential em Pontos finais do proxy. O editor de texto apresenta 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 é um passo de processamento num proxy de API. Neste caso, o fluxo é acionado quando uma determinada condição é cumprida (denomina-se "fluxo condicional"). A condição, definida no elemento <Condition>, indica que, se a chamada do proxy de API for feita ao recurso /accesstoken e o verbo do pedido for POST, execute a política GenerateAccessTokenClient, que gera o símbolo de acesso.
Vejamos agora a política que o fluxo condicional vai acionar. Clique na política GenerateAccessTokenClient no painel Pedido:

Apigee clássico

Em seguida, vai analisar mais detalhadamente o que o proxy de API contém.

No editor de proxy de API, clique no separador Desenvolver. No painel do navegador do lado esquerdo, vai ver duas políticas. Também vê dois fluxos POST na secção Proxy Endpoints.
Clique em AccessTokenClientCredential em Pontos finais do proxy.

Na vista de código XML, verá um Flow denominado 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 é um passo de processamento num proxy de API. Neste caso, o fluxo é acionado quando uma determinada condição é cumprida. A condição, definida no elemento <Condition>, é que, se a chamada do proxy da API for feita ao recurso /accesstoken e o verbo do pedido for POST, execute a política GenerateAccessTokenClient, que gera o token de acesso.
Vejamos agora a política que o fluxo condicional vai acionar. Clique no ícone da política GenerateAccessTokenClient no diagrama de fluxo.

É apresentada a seguinte configuração XML:

<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 de vários valores predefinidos, define o que a política vai fazer. Neste caso, vai gerar um token de acesso.
O token expira 1 hora (3 600 000 milissegundos) após ser gerado.
Em <SupportedGrantTypes>, o OAuth 2.0 <GrantType> esperado para utilização é client_credentials (trocar uma chave e um segredo do consumidor por um token OAuth 2.0).
O segundo elemento <GrantType> indica à política onde procurar no parâmetro do tipo de autorização na chamada da API, conforme exigido pela especificação do OAuth 2.0. (Vai ver isto na chamada da API mais tarde). O tipo de autorizaçã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).

De momento, não tem de fazer mais nada com o proxy da API. Nos passos posteriores, vai usar este proxy de API para gerar um token de acesso do OAuth 2.0. No entanto, primeiro, tem de fazer mais algumas coisas:

Crie o proxy de API que quer proteger com o OAuth 2.0.
Crie mais alguns artefactos que vão resultar na chave de consumidor e no segredo do consumidor que tem de trocar por um token de acesso.

Crie um proxy de API protegido

Agora, vai criar o proxy de API que quer proteger. Esta é a chamada API que devolve algo que quer. Neste caso, o proxy de API chama o serviço mocktarget do Apigee para devolver o seu endereço IP. NO ENTANTO, só o vê se transmitir um token de acesso OAuth 2.0 válido com a sua chamada API.

O proxy de API que criar aqui vai incluir uma política que verifica a existência de um token OAuth 2.0 no pedido.

Apigee na Cloud Console

Na Google Cloud consola, aceda à página Desenvolvimento de proxy > Proxies de API.

Aceda aos proxies de API
No painel Proxies de API, clique em + Criar.
No painel Criar um proxy, em Modelo de proxy, selecione Proxy inverso (mais comum).

Configure o proxy com o seguinte:

Neste campo	faça o seguinte
Nome do proxy	Introduza: `helloworld_oauth2`
Caminho base	Alterar para: `/hellooauth2` O caminho base do projeto faz parte do URL usado para fazer pedidos ao proxy da API.
Descrição	Introduza: `hello world protected by OAuth 2.0`
Destino (API existente)	Introduza: `https://mocktarget.apigee.net/ip` Isto define o URL de destino que o Apigee invoca num pedido ao proxy da API.

Clicar em Seguinte.
Implementar (opcional):
- Ambientes de implementação: opcional. Use as caixas de verificação para selecionar um ou mais ambientes nos quais implementar o seu proxy. Se preferir não implementar o proxy neste ponto, deixe o campo Ambientes de implementação vazio. Pode sempre implementar o proxy mais tarde.
- Conta de serviço: opcional. Anexe uma conta de serviço à sua implementação para permitir que o proxy aceda aos Google Cloud serviços, conforme especificado na função e nas autorizações da conta de serviço.
Clique em Criar.
Clique no separador Develop do proxy helloworld_oauth2.
No menu Políticas, clique em Adicionar política.
No painel Criar política, selecione OAuth 2.0.
Clique em Criar.

Apigee clássico

Aceda à IU do Apigee, inicie sessão e selecione a sua organização do Apigee.
Selecione Desenvolver > Proxies de API na barra de navegação do lado esquerdo.
Clique em Criar novo.
No assistente Criar um proxy, selecione Proxy inverso (mais comum).

Configure o proxy com o seguinte:

Neste campo	faça o seguinte
Nome do proxy	Introduza: `helloworld_oauth2`
Caminho base do projeto	Alterar para: `/hellooauth2` O caminho base do projeto faz parte do URL usado para fazer pedidos ao proxy da API.
API existente	Introduza: `https://mocktarget.apigee.net/ip` Isto define o URL de destino que o Apigee invoca num pedido ao proxy da API.
Descrição	Introduza: `hello world protected by OAuth 2.0`

Clicar em Seguinte.

Na página Políticas comuns:

Neste campo	faça o seguinte
Segurança: autorização	Selecione: OAuth 2.0 Estas opções são muito úteis. Adicionam automaticamente duas políticas ao seu proxy de API e criam um produto de API.

Neste campo

faça o seguinte

Segurança: autorização

Selecione:

OAuth 2.0

Estas opções são muito úteis. Adicionam automaticamente duas políticas ao seu proxy de API e criam um produto de API.

Clicar em Seguinte.
Na página Resumo, em Implementação opcional, selecione um ambiente e clique em Criar e implementar.
Clique em Editar proxy para apresentar a página Descrição geral do proxy de API.
O proxy de API é implementado automaticamente para si. (A implementação pode demorar alguns momentos a ser concluída.)

Veja as políticas

Vejamos mais detalhadamente o que criou.

Consola do Apigee Cloud

No editor de proxy de API, clique no separador Desenvolver. Vai ver que foram adicionadas duas políticas ao fluxo de pedidos do proxy de API:
- Validar chave de acesso OAuth v2.0: verifica a chamada API para garantir que está presente um token OAuth 2.0 válido.
- Remover autorização do cabeçalho: uma política Assign Message que remove o token de acesso depois de ser verificado, para que não seja transmitido ao serviço de destino. (Se o serviço de destino precisasse da chave de acesso OAuth 2.0, não usaria esta política).
Clique no ícone Validar token de acesso OAuth v2.0 no painel do lado direito e consulte o XML abaixo no editor de texto.

Apigee clássico

No editor de proxy de API, clique no separador Desenvolver. Vai ver que foram adicionadas duas políticas ao fluxo de pedidos do proxy de API:
- Validar chave de acesso OAuth v2.0: verifica a chamada API para garantir que está presente um token OAuth 2.0 válido.
- Remover autorização do cabeçalho: uma política Assign Message que remove o token de acesso depois de ser verificado, para que não seja transmitido ao serviço de destino. (Se o serviço de destino precisasse da chave de acesso OAuth 2.0, não usaria esta política).
Clique no ícone Validar token de acesso OAuth v2.0 na vista de fluxo e consulte 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>

Repare que o <Operation> é VerifyAccessToken. A operação define o que a política deve fazer. Neste caso, vai verificar se existe um token OAuth 2.0 válido no pedido.

Adicione um produto API

Para obter um token de acesso do OAuth 2.0, tem de criar três entidades do Apigee: um produto de API, um programador e uma app de programador.

Crie o produto de API:

Apigee na Cloud Console

Na Google Cloud consola, aceda à página Distribuição > Produtos API.

Aceda aos produtos de API

Apigee clássico

Na IU do Apigee, aceda a Publicar > Produtos de API.

Clique em + Criar.

Introduza os detalhes do produto do seu produto de API.

Campo	Descrição
Nome	Nome interno do produto API. Não especifique carateres especiais no nome. Nota: não pode editar o nome depois de criar o produto API.
Nome a apresentar	Nome a apresentar do produto API. O nome a apresentar é usado na IU e pode editá-lo em qualquer altura. Se não for especificado, é usado o valor do nome. Este campo é preenchido automaticamente com o valor Nome. Pode editar ou eliminar o respetivo conteúdo. O nome a apresentar pode incluir carateres especiais.
Descrição	Descrição do produto API.
Ambiente	Ambientes aos quais o produto API vai permitir o acesso. Selecione o ambiente no qual implementou o proxy de API.
Acesso	Selecione Público.
Aprovar automaticamente pedidos de acesso	Ativar a aprovação automática de pedidos de chaves para este produto de API a partir de qualquer app.
Quota	Ignore para este tutorial.
Âmbitos do OAuth 2.0 permitidos	Ignore para este tutorial.

Na secção Operações, clique em Adicionar uma operação.
No campo Proxy de API, selecione o proxy de API que acabou de criar.
No campo Caminho, introduza "/". Ignore os outros campos.
Clique em Guardar para guardar a operação.
Clique em Guardar para guardar o produto API.

Adicione um programador e uma app à sua organização

Em seguida, vai simular o fluxo de trabalho de um programador que se inscreve para usar as suas APIs. Idealmente, os programadores registam-se e registam as respetivas apps através do seu portal para programadores. No entanto, neste passo, vai adicionar um programador e uma app como administrador.

Um programador tem uma ou mais apps que chamam as suas APIs, e cada app recebe uma chave de consumidor e um segredo do consumidor únicos. Esta chave/segredo por app também lhe dá, ao fornecedor da API, um controlo mais detalhado sobre o acesso às suas APIs e relatórios de estatísticas mais detalhados sobre o tráfego da API, porque o Apigee sabe a que token OAuth 2.0 pertencem o programador e a app.

Crie um programador

Vamos criar um programador chamado Nigel Tufnel.

Apigee na Cloud Console

Abra o editor Developer.
Na Google Cloud consola, aceda à página Distribuição > Programadores.

Aceda ao Google Developers
Clique em + Criar.

Introduza o seguinte na janela Adicionar programador:

Neste campo	Enter
Nome próprio	`Nigel`
Apelido	`Tufnel`
Email	`nigel@example.com`
Nome de utilizador	`nigel`

Clique em Adicionar.

Apigee clássico

Abra o editor Developer.
Na IU do Apigee, aceda a Publicar > Programadores.
Clique em + Programador.

Introduza o seguinte na janela Criar programador:

Neste campo	Enter
Nome próprio	`Nigel`
Apelido	`Tufnel`
Email	`nigel@example.com`
Nome de utilizador	`nigel`

Clique em Criar.

Registe uma app

Vamos criar uma app para o André.

Apigee na Cloud Console

Na Google Cloud consola, aceda à página Distribuição > Apps.

Aceda a Apps
Clique em + Criar.

Introduza o seguinte na janela Nova app:

Neste campo	faça o seguinte
Nome e Nome a apresentar	Introduza: `nigel_app`
Programador	Clique em Programador e selecione: `Nigel Tufnel (nigel@example.com)`
URL de retorno e Notas	Deixe em branco

Clique em + Adicionar credenciais.
Clique em + Adicionar produtos.
Selecione o produto da API que acabou de criar.
Clique em Adicionar.
Clique em Criar.

Apigee clássico

Na IU do Apigee, aceda a Publicar > Programadores.
Clique em + Programador.
Clique em + App.

Introduza o seguinte na janela Nova app:

Neste campo	faça o seguinte
Nome e Nome a apresentar	Introduza: `nigel_app`
Programador	Clique em Programador e selecione: `Nigel Tufnel (nigel@example.com)`
URL de retorno e Notas	Deixe em branco

Em Produtos, clique em Adicionar produto.
Adicione o produto API que acabou de criar.
Clique em Criar.

Obtenha a chave de consumidor e o segredo do consumidor

Agora, recebe a chave de consumidor e o segredo do consumidor que vão ser trocados por um token de acesso OAuth 2.0.

Abra a página nigel_app.

Apigee na Cloud Console

Certifique-se de que a página nigel_app é apresentada. Caso contrário, aceda à página Distribuição > Apps.

Aceda a Apps
Na página nigel_app, clique em nas colunas Chave e Segredo. Tenha em atenção que a chave/segredo estão associados ao produto da API que criou anteriormente.

Apigee clássico

Certifique-se de que a página nigel_app é apresentada. Caso contrário, na página Apps (Publicar > Apps), clique em nigel_app.
Na página nigel_app, clique em Mostrar nas colunas Chave e Segredo. Tenha em atenção que a chave/segredo estão associados ao produto da API que criou anteriormente.

Selecione e copie os valores Chave e Segredo. Cole-os num ficheiro de texto temporário. Vai usá-las num passo posterior, em que chama o proxy da API que vai trocar estas credenciais por um token de acesso OAuth 2.0.

Experimente chamar a API para obter o seu endereço IP (falha!)

Experimente chamar o proxy de API protegido que acabou de criar. Repare que não está a transmitir um token de acesso OAuth 2.0 na chamada.

onde YOUR ENV_GROUP_HOSTNAME é o nome do anfitrião do grupo de ambientes. Consulte Encontre o nome de anfitrião do grupo de ambientes.

Uma vez que o proxy de API tem a política Verify OAuth v2.0 Access Token a verificar se existe um token OAuth 2.0 válido no pedido, a chamada deve falhar com a seguinte mensagem:

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

Neste caso, a falha é boa! Isto significa que o seu proxy de API é muito mais seguro. Apenas as apps fidedignas com um símbolo de acesso OAuth 2.0 válido podem chamar esta API com êxito.

Obtenha uma chave de acesso OAuth 2.0

Em seguida, vai usar a chave e o segredo que copiou e colou num ficheiro de texto e trocá-los por um token de acesso OAuth 2.0. Agora, vai fazer uma chamada API ao proxy de exemplo da API que importou, oauth, que vai gerar um token de acesso à API.

Com essa chave e segredo, faça a seguinte chamada cURL (tenha em atenção 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"

Tenha em atenção que, se estiver a usar um cliente como o Postman para fazer a chamada, os parâmetros client_id e client_secret são colocados no corpo do pedido e têm de ser x-www-form-urlencoded.

Deve receber uma resposta como a seguinte:

{
  "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"
}

Tem a sua chave de acesso OAuth 2.0! Copie o valor access_token (sem as aspas) e cole-o no ficheiro de texto. Vai usá-lo dentro de momentos.

O que foi isto?

Lembra-se de quando analisou esse "fluxo condicional" no proxy oauth, o que dizia que, se o URI do recurso for /accesstoken e o verbo do pedido for POST, deve executar a política de OAuth 2.0 GenerateAccessTokenClient que gera um token de acesso? O seu comando cURL cumpriu essas condições, pelo que a Política de OAuth 2.0 foi executada. Validou a sua chave de consumidor e segredo do consumidor, e trocou-os por um token OAuth 2.0 que expira dentro de 1 hora.

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

Agora que tem um token de acesso, pode usá-lo para chamar o proxy da API. Faça a seguinte chamada cURL: Substitua o nome da organização da Apigee e o token de acesso.

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

Agora, deve receber uma chamada bem-sucedida para o proxy da API que devolve o seu endereço IP. For example:

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

Pode repetir essa chamada da API durante quase uma hora, após a qual a chave de acesso expira. Para fazer a chamada após uma hora, tem de gerar uma nova chave de acesso através dos passos anteriores.

Parabéns! Criou um proxy de API e protegeu-o exigindo que seja incluída uma chave de acesso OAuth 2.0 válida na chamada.

Tópicos relacionados

Página inicial do OAuth 2.0
Política OAuthV2
Transfira proxies de API (que mostra como agrupar um proxy de API num ficheiro ZIP como o que transferiu)

Proteja uma API com o OAuth 2.0 Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Implemente o proxy OAuth 2.0

Apigee na Cloud Console

Apigee clássico

Veja o fluxo e a política do OAuth 2.0

Consola do Apigee Cloud

Apigee clássico

Crie um proxy de API protegido

Apigee na Cloud Console

Apigee clássico

Veja as políticas

Consola do Apigee Cloud

Apigee clássico

Adicione um produto API

Apigee na Cloud Console

Apigee clássico

Adicione um programador e uma app à sua organização

Crie um programador

Apigee na Cloud Console

Apigee clássico

Registe uma app

Apigee na Cloud Console

Apigee clássico

Obtenha a chave de consumidor e o segredo do consumidor

Apigee na Cloud Console

Apigee clássico

Experimente chamar a API para obter o seu endereço IP (falha!)

Obtenha uma chave de acesso OAuth 2.0

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

Tópicos relacionados

Proteja uma API com o OAuth 2.0