Utilizzo di OAuth2 per accedere all'API Edge

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione Documentazione di Apigee X. Informazioni

Apigee Edge ti 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 Private Cloud, non è possibile utilizzare OAuth2 prima di 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 dici di esserlo. Per autenticarti, richiediamo l'invio di un token di accesso OAuth2 con la tua richiesta per accedere all'API.

Ad esempio, per ottenere i dettagli di un'organizzazione su Edge, puoi inviare una richiesta a un URL come il seguente:

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

Tuttavia, non puoi semplicemente inviare questa richiesta senza dirci chi sei. Altrimenti, chiunque potrebbero vedere i dettagli della tua organizzazione.

È qui che entra in gioco OAuth2: per autenticarti, abbiamo bisogno che tu ci invii un token di accesso anche in questa richiesta. Il token di accesso ci comunica chi sei per consentirci di verificare che tu abbia il permesso di per vedere i dettagli dell'organizzazione.

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

Flusso OAuth2: richiesta iniziale

L'immagine seguente mostra il flusso OAuth2 quando accedi per la prima volta all'API Edge 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 utilizzando 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 l'accesso e i token di aggiornamento in ~/.sso-cli (il token di aggiornamento non viene scritto stdout.) Se utilizzi il servizio OAuth2 Edge per ricevere token, devi salvarli per in un secondo momento.

  3. Invia una richiesta all'API Edge con il token di accesso. acurl allegati 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 con un token. Invece, puoi includere il token di accesso già in tuo possesso, purché non sia ancora scaduto:

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

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

  1. Invia una richiesta all'API Edge con il token di accesso. acurl allegati automaticamente il token. Se utilizzi altri strumenti, dovrai 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 utilizzare il token di aggiornamento per riceverne uno 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, quando il token di accesso è scaduto:

  1. Invii una richiesta all'API Edge, ma il token di accesso è scaduto.
  2. L'API Edge rifiuta la richiesta in quanto non autorizzata.
  3. Invii un token di aggiornamento al servizio OAuth2 Edge. Se utilizzi acurl, è necessario automaticamente.
  4. Il servizio OAuth2 Edge risponde con un nuovo token di accesso.
  5. Invii 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.

recupera i token

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

  • Utilità get_token: scambia le tue credenziali Apigee per l'accesso e di aggiornamento che puoi usare per chiamare l'API Edge.
  • utilità acurl: fornisce un pratico wrapper attorno a un modello Comando curl. Crea richieste HTTP a livello perimetrale l'API, ottiene i token di accesso e di aggiornamento da get_token e passa il token di accesso l'API Edge.
  • Endpoint di token nel servizio OAuth2 Edge: scambia il tuo Credenziali Apigee per i token di accesso e di aggiornamento tramite una chiamata all'API Edge.

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

  • 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 nuovamente le credenziali e ottenere nuovi token.

Accedi all'API Edge con OAuth2

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

L'accesso all'API Edge con acurl e curl è descritto in le sezioni successive.

Usare acurl

Per accedere all'API Edge con acurl, la richiesta iniziale deve includere il tuo e credenziali. Il servizio Edge OAuth2 risponde con i token di accesso e di aggiornamento. acurl e salvare i token localmente.

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

L'esempio seguente mostra una richiesta acurl iniziale che ottiene i dettagli per "ahamilton-eval" organizzazione:

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 i dettagli sull'organizzazione, in questo esempio viene mostrata anche una seconda richiesta che ottiene un elenco di criteri all'interno di "helloworld" proxy API. La seconda richiesta utilizza abbreviazione della "o" per "organizzazioni" nell'URL.

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

Per ulteriori informazioni, vedi Utilizzo di acurl per accedere all'API Edge.

Usa curl

Puoi utilizzare curl per accedere all'API Edge. Per farlo, devi prima ottenere di accesso e di aggiornamento. Puoi ottenerle con un'utilità come get_token o Servizio OAuth2 Edge.

Dopo aver salvato correttamente il token di accesso, passalo nella sezione Intestazione Authorization delle tue chiamate all'API Edge, come nell'esempio seguente mostra:

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 essere emesso un altro token di accesso senza richiedere le credenziali. Apigee consiglia di richiedere un nuovo token di accesso solo dopo la scadenza del token referesh, anziché inserendo le credenziali ed effettuando una nuova richiesta a ogni chiamata API.

Scadenza del token

Una volta scaduto il token di accesso, puoi utilizzarlo per richiederne uno nuovo senza dover inviare di nuovo 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 contiene una richiesta obsoleta.
  • get_token: chiama get_token per aggiornare il token di accesso.
  • Servizio OAuth2 Edge: invia una richiesta che include:
      .
    • Aggiorna token
    • Parametro del modulo grant_type impostato su "refresh_token"

OAuth2 per gli utenti di macchine

Puoi utilizzare le utilità acurl e get_token per creare uno script dell'accesso automatico alle API Edge con l'autenticazione OAuth2 per gli utenti delle macchine. L'esempio seguente mostra come usa get_token per richiedi un token di accesso e quindi aggiungi 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 di 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 all'utente di una macchina non venga richiesto un codice MFA.