Utilizzo di OAuth2 per accedere all'API Edge

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. informazioni

Apigee Edge consente di effettuare chiamate API Edge autenticate con token OAuth2. Il supporto per OAuth2 è abilitato per impostazione predefinita su Edge per gli account cloud. Se utilizzi Edge per il cloud privato, non puoi utilizzare OAuth2 senza prima configurare SAML o LDAP.

Come funziona OAuth2 (con l'API Apigee Edge)

Le chiamate all'API Apigee Edge richiedono l'autenticazione, così possiamo essere sicuri che sei chi dici di essere. Per autenticarti, richiediamo l'invio di un token di accesso OAuth2 con la tua richiesta di accesso all'API.

Ad esempio, se vuoi ottenere dettagli su un'organizzazione su Edge, devi inviare una richiesta a un URL come il seguente:

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

Ma non puoi semplicemente inviare questa richiesta senza dirci chi sei. In caso contrario, chiunque potrebbe visualizzare i dettagli dell'organizzazione.

È qui che entra in gioco OAuth2: per autenticarti, devi anche inviarci un token di accesso in questa richiesta. Il token di accesso ci comunica chi sei, in modo che tu possa visualizzare i dettagli dell'organizzazione.

Fortunatamente, puoi ottenere un token inviando le tue credenziali al servizio Edge OAuth2. Il servizio risponde con i token di accesso e di aggiornamento.

Flusso OAuth2: la richiesta iniziale

L'immagine seguente mostra il flusso OAuth2 quando accedi all'API Edge per la prima volta:

Flusso OAuth: prima richiesta
Figura 1: flusso OAuth: prima richiesta

Come mostra la Figura 1, quando effettui la richiesta iniziale all'API Edge:

  1. Richiedi un token di accesso. Puoi farlo con l'API Edge, acurl o get_token. Ad esempio: 
    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. Il servizio Edge OAuth2 risponde con un token di accesso e lo stampa su stdout; ad esempio: 
    Dy42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJz
AJpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsIm
NjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjJkMWU3NDI
GzQyMC1kYzgxLTQzMDQtOTM4ZS1hOGNmNmVlODZhNzkiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwic
ENC05MzhlLWE4Y2Y2ZWU4NmE3OSIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoiZGFuZ2VyNDI0
RI6ImUyNTM2NWQyIiwiaWF0IjoxNTI4OTE2NDA5LCJleHAiOjE1Mjg5MTgyMDksImlzcyI6Imh0dHBzOi8vbG
420iLCJlbWFpbCI6ImRhbmdlcjQyNDJAeWFob28uY29tIiwiYXV0aF90aW1lIjoxNTI4OTE2NDA5LCJhbCI6M
2lLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiw

    Le utilità acurl e get_token salvano automaticamente i token di accesso e di aggiornamento in ~/.sso-cli (il token di aggiornamento non è scritto in stdout). Se utilizzi il servizio Edge OAuth2 per ricevere i token, devi salvarli per utilizzarli in un secondo momento.

  3. Invii una richiesta all'API Edge con il token di accesso. acurl collega automaticamente il token; ad esempio: 
    acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

    Se utilizzi un altro client HTTP, assicurati di aggiungere il token di accesso. Ad esempio:

    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"
  4. L'API Edge esegue la richiesta e in genere restituisce una risposta con dati.

Flusso OAuth2: richieste successive

Nelle richieste successive non è necessario scambiare le credenziali per un token. Puoi invece includere il token di accesso già in tuo possesso, a condizione che non sia ancora scaduto:

Flusso OAuth: richieste successive
Figura 2: flusso OAuth: richieste successive

Come mostra la Figura 2, quando hai già un token di accesso:

  1. Invii una richiesta all'API Edge con il token di accesso. acurl collega automaticamente il token. Se utilizzi altri strumenti, devi aggiungere il token manualmente.
  2. L'API Edge esegue la richiesta e in genere restituisce una risposta con dati.

Flusso OAuth2: quando scade il token di accesso

Quando un token di accesso scade (dopo 12 ore), puoi utilizzarlo per ottenere un nuovo token di accesso:

Flusso OAuth: aggiornamento del token di accesso
Figura 3: flusso OAuth: aggiornamento del token di accesso

Come mostra la Figura 3, una volta scaduto il token di accesso:

  1. Invii una richiesta all'API Edge, ma il token di accesso è scaduto.
  2. L'API Edge rifiuta la tua richiesta in quanto non autorizzata.
  3. Invii un token di aggiornamento al servizio Edge OAuth2. Se utilizzi acurl, l'operazione viene eseguita automaticamente.
  4. Il servizio Edge OAuth2 risponde con un nuovo token di accesso.
  5. Invierai una richiesta all'API Edge con il nuovo token di accesso.
  6. L'API Edge esegue la richiesta e in genere restituisce una risposta con dati.

Trova i token

Per ottenere un token di accesso da inviare all'API Edge, puoi utilizzare le seguenti utilità di Apigee, oltre a un'utilità come curl:

  • Utilità get_token: scambia le credenziali Apigee per i token di accesso e di aggiornamento che puoi utilizzare per chiamare l'API Edge.
  • utilità acurl: fornisce un wrapper per la comodità per un comando curl standard. Crea richieste HTTP all'API Edge, ottiene i token di accesso e di aggiornamento da get_token e passa il token di accesso all'API Edge.
  • Endpoint dei token nel servizio Edge OAuth2: scambia le tue credenziali Apigee per i token di accesso e di aggiornamento tramite una chiamata all'API Edge.

Queste utilità scambiano le credenziali dell'account Apigee (indirizzo email e password) con token con la seguente durata:

  • I token di accesso scadono dopo 12 ore.
  • I token di aggiornamento scadono dopo 30 giorni.

Di conseguenza, dopo aver effettuato correttamente una chiamata API con acurl o get_token, puoi continuare a utilizzare la coppia di token per 30 giorni. Dopo la scadenza, devi inserire di nuovo le tue credenziali e ricevere nuovi token.

Accedere all'API Edge con OAuth2

Per accedere all'API Edge, devi inviare una richiesta a un endpoint API e includere il token di accesso. Puoi eseguire questa operazione con qualsiasi client HTTP, inclusa un'utilità a riga di comando come curl, un'interfaccia utente basata su browser come Postman o un'utilità Apigee come acurl.

L'accesso all'API Edge con acurl e con curl è descritto nelle sezioni che seguono.

Utilizza acurl

Per accedere all'API Edge con acurl, la richiesta iniziale deve includere le tue credenziali. Il servizio Edge OAuth2 risponde con i token di accesso e di aggiornamento. acurl salva i token in locale.

Nelle richieste successive, acurl utilizza i token salvati in ~/.sso-cli in modo che tu non debba includere di nuovo le credenziali fino alla scadenza dei token.

L'esempio seguente mostra una richiesta acurl iniziale che recupera i dettagli dell'organizzazione "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" ]

Oltre a ottenere dettagli sull'organizzazione, questo esempio mostra anche una seconda richiesta che riceve un elenco di criteri all'interno del proxy API "helloworld". La seconda richiesta utilizza l'abbreviazione "o" per "organizzazioni" nell'URL.

Tieni presente che acurl passa automaticamente il token di accesso alla seconda richiesta. Non è necessario passare le credenziali utente dopo che acurl ha archiviato i token OAuth2. Recupera il token da ~/.sso-cli per le chiamate successive.

Per saperne di più, vedi Utilizzare acurl per accedere all'API Edge.

Usa curl

Puoi usare curl per accedere all'API Edge. A tale scopo, devi prima ottenere i token di accesso e di aggiornamento. Puoi ottenerle utilizzando un'utilità come get_token o il servizio OAuth2 di Edge.

Dopo aver salvato correttamente il token di accesso, lo passi nell'intestazione Authorization delle chiamate all'API Edge, come mostrato nell'esempio seguente:

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

Il token di accesso è valido per 12 ore dall'emissione. Dopo la scadenza del token di accesso, il token di aggiornamento può essere utilizzato per 30 giorni per emettere un altro token di accesso senza richiedere le credenziali. Apigee consiglia di richiedere un nuovo token di accesso solo dopo la scadenza del token di riferimento, anziché inserire le credenziali e creare una nuova richiesta a ogni chiamata API.

Scadenza del token

Una volta scaduto il token di accesso, puoi utilizzarlo per ottenere un nuovo token di accesso senza dover inviare nuovamente le credenziali.

La modalità di aggiornamento del token di accesso dipende dallo strumento che utilizzi:

  • acurl: nessuna azione necessaria. acurl aggiorna automaticamente il token di accesso quando invii una richiesta che ne contiene uno obsoleto.
  • get_token: chiama get_token per aggiornare il token di accesso.
  • Servizio OAuth2 Edge: invia una richiesta che includa:
    • Aggiorna token
    • Parametro del modulo grant_type impostato su "refresh_token"

OAuth2 per utenti della macchina

Puoi utilizzare le utilità acurl e get_token per creare script dell'accesso automatico alle API Edge con l'autenticazione OAuth2 per gli utenti delle macchine. L'esempio seguente mostra come utilizzare get_token per richiedere un token di accesso e quindi aggiungere il valore del token a una chiamata 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/...'

In alternativa, puoi combinare la richiesta del token e la chiamata curl utilizzando l'utilità acurl. Ad esempio:

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

In entrambi gli esempi, l'impostazione del valore di -m su una stringa vuota impedirà a un utente della macchina di richiedere un codice MFA.