Como usar o OAuth2 para acessar a API Edge

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

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

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 para acessar a API.

Por exemplo, se você quiser mais 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

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

É aí que entra o OAuth2: para autenticá-lo, você também precisa nos enviar um token de acesso nessa solicitação. O token de acesso informa quem você é para que possamos ter certeza de que 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 atualização.

Fluxo do OAuth2: a solicitação inicial

A imagem a seguir mostra o fluxo do OAuth2 quando você acessa 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, quando você faz sua solicitação inicial à API Edge:

  1. Você solicita um token de acesso. Você pode fazer isso com a API Edge, acurl ou get_token (links em inglês). Por 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
  2. O serviço do Edge OAuth2 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 atualização em ~/.sso-cli. O token de atualização não é gravado no stdout. Se você usa o serviço do Edge OAuth2 para receber tokens, é necessário salvá-los para uso posterior.

  3. 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"
  4. A API Edge executa sua solicitação e normalmente retorna uma resposta com dados.

Fluxo do OAuth2: solicitações subsequentes

Nas solicitações seguintes, não será 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 a Figura 2 mostra, quando você já tem um token de acesso:

  1. Você envia uma solicitação para a API Edge com o token de acesso. acurl anexa o token automaticamente. Se você usa outras ferramentas, precisa adicionar o token manualmente.
  2. A API Edge executa sua solicitação e normalmente retorna uma resposta com dados.

Fluxo do OAuth2: quando o token de acesso expirar

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

Fluxo do OAuth: como atualizar o token de acesso
Figura 3:fluxo OAuth: atualização do token de acesso

Como mostra a Figura 3, quando seu token de acesso expirou:

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

Acessar os tokens

Para receber um token de acesso que pode ser enviado para a API Edge, é possível usar 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 atualização do get_token e transmite o token de acesso para a API Edge.
  • Pontos de extremidade de token no serviço de OAuth2 do Edge: troque suas credenciais da Apigee pelos tokens de acesso e de atualização com uma chamada para a API do Edge.

Esses utilitários trocam as credenciais da sua 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ê poderá continuar usando o par de tokens por 30 dias. Após a expiração, é preciso inserir novamente suas credenciais 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 IU baseada em navegador (como o Postman) ou um utilitário da Apigee (como acurl).

O acesso à API Edge com acurl e curl é descrito 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 do Edge OAuth2 responde com os tokens de acesso e de atualização. acurl salva os tokens localmente.

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

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

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 dentro do proxy de API "PROVIDER". A segunda solicitação usa o encurtamento "o" para "organizations" no URL.

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

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

Usar curl

Use curl para acessar a API Edge. Para fazer isso, é preciso primeiro conseguir os tokens de acesso e de atualização. É possível acessá-los usando um utilitário como o get_token ou o serviço OAuth2 do Edge.

Depois de salvar o token de acesso, transmita-o no cabeçalho Authorization das suas 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 expirar, o token de atualização poderá 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 referência, em vez de inserir credenciais e fazer uma nova solicitação a cada chamada de API.

Expiração do token

Quando seu token de acesso expirar, você poderá usá-lo para receber um novo token de acesso sem precisar enviar suas credenciais novamente.

A forma como você atualiza seu token de acesso depende da ferramenta que está usando:

  • acurl: nenhuma ação é necessária. acurl atualiza automaticamente o token de acesso quando você envia uma solicitação que contém uma desatualizada.
  • 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áquina

É possível usar os utilitários acurl e get_token para criar um script do acesso automatizado às APIs do Edge com autenticação OAuth2 para usuários de máquina. 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 de 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 impedirá que um usuário da máquina receba uma solicitação de código MFA.