Utilizzo di OAuth2 per accedere all'API Edge

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Apigee Edge ti consente di effettuare chiamate API Edge autenticate con token OAuth2. Il supporto di 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 per consentirci di verificare che tu sia chi dici di essere. Per autenticarti, richiediamo che venga inviato un token di accesso OAuth2 con la richiesta di accesso all'API.

Ad esempio, se volessi ottenere i dettagli di un'organizzazione su Edge, invieresti una richiesta a un URL simile al seguente:

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

Tuttavia, non puoi semplicemente inviare la richiesta senza comunicarci la tua identità. In caso contrario, chiunque potrebbe visualizzare i dettagli della tua organizzazione.

È qui che entra in gioco OAuth2: per autenticarti, dobbiamo chiederti di inviarci anche un token di accesso nella richiesta. Il token di accesso ci indica la tua identità, in modo che possiamo assicurarci che tu sia autorizzato a visualizzare i dettagli dell'organizzazione.

Fortunatamente, puoi ottenere un token inviando le tue credenziali al servizio Edge OAuth2. Il servizio risponde con 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 mostrato nella 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 viene scritto in stdout. Se utilizzi il servizio Edge OAuth2 per ottenere i token, devi salvarli per un utilizzo successivo.

  3. Invia una richiesta all'API Edge con il token di accesso. acurl allega 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 i dati.

Flusso OAuth2: richieste successive

Nelle richieste successive, non devi scambiare le tue credenziali con un token. Puoi invece includere il token di accesso che hai già, a condizione che non sia ancora scaduto:

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

Come mostrato nella Figura 2, se hai già un token di accesso:

  1. Invia una richiesta all'API Edge con il token di accesso. acurl allega 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 i dati.

Flusso OAuth2: quando il token di accesso scade

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

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

Come mostrato nella Figura 3, quando il token di accesso è scaduto:

  1. Invia una richiesta all'API Edge, ma il token di accesso è scaduto.
  2. L'API Edge rifiuta la richiesta perché non autorizzata.
  3. Invia un token di aggiornamento al servizio Edge OAuth2. Se utilizzi acurl, questa operazione viene eseguita automaticamente.
  4. Il servizio Edge OAuth2 risponde con un nuovo token di accesso.
  5. Invia 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 i dati.

Ottenere i token

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

  • Utilità get_token: scambia le tue credenziali Apigee con token di accesso e di aggiornamento che puoi utilizzare per chiamare l'API Edge.
  • Utilità acurl: fornisce un wrapper di convenienza attorno a un comando standard curl. Crea richieste HTTP all'API Edge , ottiene 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 con i token di accesso e di aggiornamento tramite una chiamata all'API Edge.

Queste utilità scambiano le credenziali del tuo account Apigee (indirizzo email e password) con token con le seguenti durate:

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

Di conseguenza, una volta effettuata 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 ottenere nuovi token.

Accedere all'API Edge con OAuth2

Per accedere all'API Edge, invia una richiesta a un endpoint API e includi il token di accesso. Puoi farlo con qualsiasi client HTTP, inclusa un'utilità della 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 curl è descritto in nelle sezioni seguenti.

Utilizzare 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 localmente.

Nelle richieste successive, acurl utilizza i token salvati in ~/.sso-cli in modo che non devi includere di nuovo le tue 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 recuperare i dettagli dell'organizzazione, questo esempio mostra anche una seconda richiesta che recupera un elenco di policy all'interno del proxy API "helloworld". La seconda richiesta utilizza l' abbreviazione "o" per "organizations" nell'URL.

Tieni presente che acurl passa automaticamente il token di accesso alla seconda richiesta. Non devi passare le tue credenziali utente una volta che acurl memorizza 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.

Utilizzare curl

Puoi utilizzare curl per accedere all'API Edge. Per farlo, devi prima ottenere i token di accesso e di aggiornamento. Puoi ottenerli utilizzando un'utilità come get_token o il servizio Edge OAuth2..

Dopo aver salvato correttamente il token di accesso, passalo nell' 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 dopo l'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 aggiornamento, anziché inserire le credenziali ed effettuare una nuova richiesta a ogni chiamata API.

Scadenza del token

Una volta scaduto il token di accesso, puoi utilizzare il token di aggiornamento per ottenere un nuovo token di accesso senza dover inviare di nuovo le tue credenziali.

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

  • acurl: non è necessaria alcuna azione. 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 Edge OAuth2: invia una richiesta che includa:
    • Token di aggiornamento
    • Parametro del modulo grant_type impostato su "refresh_token"

OAuth2 per utenti macchina

Puoi utilizzare le utilità acurl e get_token per creare script di accesso automatico alle API Edge con l'autenticazione OAuth2 per gli utenti macchina. L'esempio seguente mostra come utilizzare get_token per richiedere un token di accesso e poi 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 impedisce a un utente macchina di ricevere una richiesta di codice MFA.