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:
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 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
- 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
eget_token
salvam silenciosamente os tokens de acesso e atualização em~/.sso-cli
. O token de atualização não é gravado nostdout
. Se você usa o serviço do Edge OAuth2 para receber tokens, é 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
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:
Como a Figura 2 mostra, 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ê 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 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:
Como mostra a Figura 3, quando seu token de acesso expirou:
- Você enviou uma solicitação para a API Edge, mas seu token de acesso expirou.
- A API Edge rejeita a solicitação como não autorizada.
- Envie um token de atualização para o serviço do Edge OAuth2. Se você estiver usando
acurl
, isso será feito automaticamente para você. - O serviço do Edge OAuth2 responde com um novo token de acesso.
- Você vai enviar 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.
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 doget_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
: chameget_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.