O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Como usar o OAuth2 para acessar a API Edge

Você está lendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

O Apigee Edge permite fazer chamadas da API Edge autenticadas com tokens OAuth2. O suporte ao OAuth2 é ativado por padrão nas contas do Edge para o Cloud. Se você estiver usando o Edge para a nuvem privada, não será possível usar o OAuth2 sem configurar o SAML ou o LDAP primeiro.

Como o OAuth2 funciona (com a API Apigee Edge)

As chamadas para a API Apigee Edge exigem autenticação para que possamos ter certeza de que você é quem diz ser. Para autenticar você, é necessário enviar um token de acesso OAuth2 com sua solicitação de acesso à API.

Por exemplo, se você quiser receber detalhes sobre uma organização no Edge, envie uma solicitação para um URL como este:

https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

Mas não é possível enviar essa solicitação sem nos dizer quem você é. Caso contrário, qualquer pessoa poderia ver os detalhes da sua organização.

É aí que o OAuth2 entra em cena: para autenticar você, também precisamos que você nos envie um token de acesso nessa solicitação. O token de acesso nos informa quem você é para que possamos ter certeza de que você tem permissão para ver os detalhes da organização.

Felizmente, é possível receber um token enviando suas credenciais para o serviço OAuth2 do Edge. O serviço responde com tokens de acesso e de atualização.

Fluxo do OAuth2: a solicitação inicial

A imagem a seguir mostra o fluxo do OAuth2 ao acessar a API Edge pela primeira vez:

Fluxo do OAuth: primeira solicitação — **Figura 1:** fluxo do OAuth: primeira solicitação

Como mostra a Figura 1, ao fazer sua solicitação inicial para a API Edge:

Você solicita um token de acesso. É possível fazer isso com a API Edge, o acurl, ou get_token. Exemplo:

get_token
Enter username:
ahamilton@apigee.com
Enter the password for user 'ahamilton@apigee.com'
[hidden input]
Enter the six-digit code if 'ahamilton@apigee.com' is MFA enabled or press ENTER:
123456

O serviço OAuth2 do Edge responde com um token de acesso e o imprime em stdout; por exemplo:

Dy42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJz
AJpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsIm
NjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjJkMWU3NDI
GzQyMC1kYzgxLTQzMDQtOTM4ZS1hOGNmNmVlODZhNzkiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwic
ENC05MzhlLWE4Y2Y2ZWU4NmE3OSIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoiZGFuZ2VyNDI0
RI6ImUyNTM2NWQyIiwiaWF0IjoxNTI4OTE2NDA5LCJleHAiOjE1Mjg5MTgyMDksImlzcyI6Imh0dHBzOi8vbG
420iLCJlbWFpbCI6ImRhbmdlcjQyNDJAeWFob28uY29tIiwiYXV0aF90aW1lIjoxNTI4OTE2NDA5LCJhbCI6M
2lLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiw

Os utilitários acurl e get_token salvam silenciosamente os tokens de acesso e de atualização em ~/.sso-cli. O token de atualização não é gravado em stdout. Se você usar o serviço OAuth2 do Edge para receber tokens, será necessário salvá-los para uso posterior.

Você envia uma solicitação para a API Edge com o token de acesso. acurl anexa o token automaticamente; por exemplo:

acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

Se você usar outro cliente HTTP, adicione o token de acesso. Exemplo:

curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"

A API Edge executa sua solicitação e normalmente retorna uma resposta com dados.

Fluxo do OAuth2: solicitações subsequentes

Em solicitações subsequentes, não é necessário trocar suas credenciais por um token. Em vez disso, basta incluir o token de acesso que você já tem, desde que ele ainda não tenha expirado:

Fluxo do OAuth: solicitações subsequentes — **Figura 2:** fluxo do OAuth: solicitações subsequentes

Como mostra a Figura 2, quando você já tem um token de acesso:

Você envia uma solicitação para a API Edge com o token de acesso. acurl anexa o token automaticamente. Se você usar outras ferramentas, será necessário adicionar o token manualmente.
A API Edge executa sua solicitação e normalmente retorna uma resposta com dados.

Fluxo do OAuth2: quando o token de acesso expira

Quando um token de acesso expira (após 12 horas), é possível usar o token de atualização para receber um novo token de acesso:

Fluxo do OAuth: atualização do token de acesso — **Figura 3:** fluxo do OAuth: atualização do token de acesso

Como mostra a Figura 3, quando o token de acesso expira:

Você envia uma solicitação para a API Edge, mas o token de acesso expirou.
A API Edge rejeita sua solicitação como não autorizada.
Você envia um token de atualização para o serviço OAuth2 do Edge. Se você estiver usando acurl, isso será feito automaticamente para você.
O serviço OAuth2 do Edge responde com um novo token de acesso.
Você envia uma solicitação para a API Edge com o novo token de acesso.
A API Edge executa sua solicitação e normalmente retorna uma resposta com dados.

Receber os tokens

Para receber um token de acesso que pode ser enviado à API Edge, use os seguintes utilitários da Apigee, além de um utilitário como curl:

Utilitário get_token: troca suas credenciais da Apigee por tokens de acesso e de atualização que podem ser usados para chamar a API Edge.
Utilitário acurl: fornece um wrapper de conveniência em torno de um comando curl padrão. Cria solicitações HTTP para a API Edge , recebe tokens de acesso e de atualização de get_token e transmite o token de acesso para a API Edge.
Endpoints de token no serviço OAuth2 do Edge: troque suas credenciais da Apigee pelos tokens de acesso e de atualização por meio de uma chamada para a API Edge.

Esses utilitários trocam suas credenciais de conta da Apigee (endereço de e-mail e senha) por tokens com as seguintes durações:

Os tokens de acesso expiram em 12 horas.
Os tokens de atualização expiram em 30 dias.

Como resultado, depois de fazer uma chamada de API com acurl ou get_token, você pode continuar usando o par de tokens por 30 dias. Após a expiração, é necessário inserir suas credenciais novamente e receber novos tokens.

Acessar a API Edge com o OAuth2

Para acessar a API Edge, envie uma solicitação para um endpoint de API e inclua o token de acesso. É possível fazer isso com qualquer cliente HTTP, incluindo um utilitário de linha de comando, como curl, uma interface baseada em navegador, como o Postman, ou um utilitário da Apigee, como acurl.

O acesso à API Edge com acurl e curl é descrito em nas seções a seguir.

Usar acurl

Para acessar a API Edge com acurl, sua solicitação inicial precisa incluir suas credenciais. O serviço OAuth2 do Edge responde com os tokens de acesso e de atualização. acurl salva os tokens localmente.

Em solicitações subsequentes, acurl usa os tokens salvos em ~/.sso-cli para que você não precise incluir suas credenciais novamente até que os tokens expirem.

O exemplo a seguir mostra uma solicitação acurl inicial que recebe detalhes da "ahamilton-eval" organização:

acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -u ahamilton@apigee.com
Enter the password for user 'ahamilton@apigee.com'
[hidden input]
Enter the six-digit code (no spaces) if 'ahamilton@apigee.com' is MFA-enabled or press ENTER:
1a2b3c
{
  "createdAt" : 1491854501264,
  "createdBy" : "noreply_iops@apigee.com",
  "displayName" : "ahamilton",
  "environments" : [ "prod", "test" ],
  "lastModifiedAt" : 1491854501264,
  "lastModifiedBy" : "noreply_iops@apigee.com",
  "name" : "ahamilton",
  "properties" : {
    "property" : [ {
      "name" : "features.isSmbOrganization",
      "value" : "false"
    }, {
      "name" : "features.isCpsEnabled",
      "value" : "true"
    } ]
  },
  "type" : "trial"
}

acurl https://api.enterprise.apigee.com/v1/o/ahamilton-eval/apis/helloworld/revisions/1/policies

[ "SOAP-Message-Validation-1", "Spike-Arrest-1", "XML-to-JSON-1" ]

Além de receber detalhes sobre a organização, este exemplo também mostra uma segunda solicitação que recebe uma lista de políticas no proxy de API "helloworld". A segunda solicitação usa a abreviação "o" para "organizações" no URL.

Observação: o acurl transmite automaticamente o token de acesso na segunda solicitação. Não é necessário transmitir suas credenciais de usuário depois que o acurl armazena os tokens OAuth2. Ele recebe o token de ~/.sso-cli para chamadas subsequentes.

Para mais informações, consulte Como usar o acurl para acessar a API Edge.

Usar curl

É possível usar curl para acessar a API Edge. Para isso, primeiro é necessário receber os tokens de acesso e de atualização. É possível recebê-los usando um utilitário como get_token ou o serviço OAuth2 do Edge..

Depois de salvar o token de acesso, transmita-o no Authorization cabeçalho das chamadas para a API Edge, como mostra o exemplo a seguir:

curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"

O token de acesso é válido por 12 horas após a emissão. Depois que o token de acesso expira, o token de atualização pode ser usado por 30 dias para emitir outro token de acesso sem exigir credenciais. A Apigee recomenda solicitar um novo token de acesso somente após a expiração do token de atualização, em vez de inserir credenciais e fazer uma nova solicitação a cada chamada de API.

Expiração do token

Depois que o token de acesso expira, é possível usar o token de atualização para receber um novo token de acesso sem precisar enviar suas credenciais novamente.

A maneira de atualizar o token de acesso depende da ferramenta que você está usando:

acurl: nenhuma ação necessária. acurl atualiza automaticamente o token de acesso quando você envia uma solicitação que contém um token desatualizado.
get_token: chame get_token para atualizar o token de acesso.
Serviço OAuth2 do Edge: envie uma solicitação que inclua:
- Token de atualização
- Parâmetro de formulário grant_type definido como "refresh_token"

OAuth2 para usuários de máquinas

É possível usar os utilitários acurl e get_token para criar scripts de acesso automatizado às APIs Edge com autenticação OAuth2 para usuários de máquinas. O exemplo a seguir mostra como usar get_token para solicitar um token de acesso e, em seguida, adicionar o valor do token a uma chamada curl:

  USER=me@example.com
  PASS=not-that-secret
  TOKEN=$(get_token -u $USER:$PASS -m '')
  curl -H "Authorization: Bearer $TOKEN" 'https://api.enterprise.apigee.com/v1/organizations/...'

Como alternativa, é possível combinar a solicitação de token e a chamada curl usando o utilitário acurl. Exemplo:

  USER=me@example.com
  PASS=not-that-secret
  acurl -u $USER:$PASS -m '' 'https://api.enterprise.apigee.com/v1/organizations/...'

Nos dois exemplos, definir o valor de -m como uma string vazia impede que um usuário de máquina receba uma solicitação de código MFA.