Esta página foi traduzida pela API Cloud Translation.

Como usar o OAuth2 para acessar a API Edge

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

O Apigee Edge permite fazer chamadas da API Edge que são autenticadas com tokens OAuth2. O suporte ao OAuth2 está ativado por padrão no Edge para as contas do Cloud. Se você estiver usando o Edge para a nuvem privada, não é possível usar o OAuth2 sem Primeiro, configure 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 quando disser que é. Para autenticar você, é necessário enviar um token de acesso OAuth2 com sua solicitação para acessar a API.

Por exemplo, se você quisesse ver detalhes sobre uma organização no Edge, enviaria uma solicitação para um URL como o seguinte:

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

No entanto, não é possível simplesmente enviar esse pedido sem nos dizer quem você é. Caso contrário, qualquer pessoa pode ver os detalhes da sua organização.

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

Você pode receber um token enviando suas credenciais para o serviço Edge OAuth2. A 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 para a primeira horário:

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:

Você solicita um token de acesso. Você pode fazer isso com o API Edge, acurl ou get_token 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

O serviço 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 o acesso e tokens de atualização para ~/.sso-cli (o token de atualização não é gravado stdout. Se você usar o serviço Edge OAuth2 para receber tokens, será necessário salvá-los para mais tarde você mesmo.

Você envia uma solicitação à API Edge com o token de acesso. acurl anexos 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

Nas solicitações subsequentes, não é necessário trocar suas credenciais por um token. Em vez disso, Você pode simplesmente incluir o token de acesso que 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 à API Edge com o token de acesso. acurl anexos o token automaticamente. Se você usa outras ferramentas, precisa adicionar o token manualmente.
A API Edge executa sua solicitação e normalmente retorna uma resposta com dados.

Fluxo do OAuth2: quando seu 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 token de acesso:

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

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

Você envia uma solicitação para a API Edge, mas seu 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 Edge OAuth2. Se você estiver usando acurl, isso estará concluído automaticamente para você.
O serviço Edge OAuth2 responde com um novo token de acesso.
Envie uma solicitação à 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, você pode usar o seguinte: Utilitários da Apigee, além de outro, como curl:

Utilitário get_token: troca suas credenciais da Apigee por acesso e tokens 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. cria solicitações HTTP para a borda; API, recebe tokens de acesso e atualização de get_token e transmite o token de acesso para a API Edge.
Tokens de endpoints no serviço Edge OAuth2: troque seus Credenciais da Apigee para os tokens de acesso e atualização por meio de uma chamada para a API Edge.

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

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

Por isso, depois de fazer uma chamada de API com acurl ou get_token, é possível continuar usando o par por 30 dias. Após a expiração, você deve inserir novamente seu credenciais e obter novos tokens.

Acessar a API Edge com o OAuth2

Para acessar a API Edge, envie uma solicitação a um endpoint da 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 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, a solicitação inicial precisa incluir o credenciais. O serviço Edge OAuth2 responde com os tokens de acesso e atualização. acurl salva os tokens localmente.

Nas solicitações subsequentes, acurl usa os tokens salvos em ~/.sso-cli para que 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 obtém detalhes para o "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 obter detalhes sobre a organização, este exemplo também mostra uma segunda solicitação que recebe uma lista de políticas dentro de "helloworld" proxy de API. A segunda solicitação usa "o" encurtado para "organizações" no URL.

Observe que acurl transmite automaticamente o token de acesso na segunda solicitação. Você não precisarão transmitir suas credenciais de usuário depois que acurl armazenar os tokens OAuth2. Ela recebe o token de ~/.sso-cli para chamadas subsequentes.

Saiba mais em Como usar acurl para acessar a API Edge.

Usar curl

Use curl para acessar a API Edge. Para fazer isso, você deve primeiro obter o tokens de acesso e atualização. Você pode obtê-los usando um utilitário como o get_token ou o Serviço OAuth2 do Edge.

Após salvar seu token de acesso, transmita-o na Cabeçalho Authorization das chamadas para a API Edge, como no exemplo a seguir. mostra:

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. Após a expiração do token de acesso, 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 depois que o token de referência expirar, 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á usar o token de atualização para receber um novo token sem ter que enviar suas credenciais novamente.

A forma de atualização do token de acesso depende da ferramenta usada:

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 Edge OAuth2: 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 scripts de acesso automatizado às APIs Edge com autenticação OAuth2 para usuários de máquina. O exemplo abaixo mostra como use 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 vai impedir que um usuário da máquina de um código de MFA.