Proteggere un'API con OAuth 2.0

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questo tutorial mostra come proteggere un proxy API utilizzando un token di accesso OAuth 2.0.

Prima di iniziare

Per completare questo tutorial, devi avere accesso a un'organizzazione Apigee in cui hai l'autorizzazione per:

• Crea e implementa i proxy API
• Creare prodotti API
• Creare app per sviluppatori

Devi anche disporre di un nome host del gruppo di ambienti configurato correttamente con cui puoi effettuare chiamate proxy API Apigee. Se hai dubbi su quale nome host del gruppo di ambienti utilizzare, rivolgiti all'amministratore di Apigee.

Esegui il deployment del proxy OAuth 2.0

Forniamo un proxy API su GitHub configurato per generare token di accesso OAuth 2.0. Segui questi passaggi per scaricare e implementare questo proxy API nel tuo ambiente:

1. Scaricare il proxy API di esempio oauth in una directory del file system.
2. Vai all'interfaccia utente di Apigee, accedi e seleziona la tua organizzazione Apigee.
3. Seleziona Sviluppa > Proxy API nella barra di navigazione a sinistra.
4. Fai clic su Crea nuova.
   
5. Nella procedura guidata Crea proxy, seleziona Carica bundle di proxy.
6. Scegli il file oauth.zip che hai scaricato e fai clic su Avanti.
7. Fai clic su Crea.
8. Al termine della compilazione, fai clic su Modifica proxy per visualizzare il nuovo proxy nell'editor del proxy API.
9. Fai clic su Esegui il deployment.
10. Seleziona la revisione e l'ambiente in cui eseguire il deployment. Puoi lasciare vuoto il campo Account di servizio.
11. Fai clic su Esegui il deployment.

Hai scaricato ed eseguito correttamente il deployment di un proxy API che genera token di accesso nella tua organizzazione Apigee.

Visualizza il flusso e i criteri di OAuth 2.0

Esamina la configurazione dei criteri OAuth 2.0.

Viene visualizzata la seguente configurazione XML:

<OAuthV2 name="GenerateAccessTokenClient">
    <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
    <Operation>GenerateAccessToken</Operation>
    <!-- This is in milliseconds, so expire in an hour -->
    <ExpiresIn>3600000</ExpiresIn>
    <SupportedGrantTypes>
        <!-- This part is very important: most real OAuth 2.0 apps will want to use other
         grant types. In this case it is important to NOT include the "client_credentials"
         type because it allows a client to get access to a token with no user authentication -->
        <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <GrantType>request.queryparam.grant_type</GrantType>
    <GenerateResponse/>
</OAuthV2>

La configurazione include quanto segue:

• <Operation>, che può essere uno di diversi valori predefiniti, definisce cosa farà il criterio. In questo caso, genererà un token di accesso.
• Il token scade 1 ora (3600000 millisecondi) dopo la generazione.
• In <SupportedGrantTypes>, il valore OAuth 2.0 <GrantType> che dovrebbe essere utilizzato è client_credentials (scambio di una chiave consumer e di un segreto per un token OAuth 2.0).
• Il secondo elemento <GrantType> indica al criterio dove cercare il parametro del tipo di concessione nella chiamata API, come richiesto dalla specifica OAuth 2.0. (lo vedrai nella chiamata all'API più avanti). Il tipo di concessione può essere inviato anche nell'intestazione HTTP (request.header.grant_type) o come parametro del modulo (request.formparam.grant_type).

Al momento non devi fare altro con il proxy API. Nei passaggi successivi, utilizzerai questo proxy API per generare un token di accesso OAuth 2.0. Prima, però, devi svolgere qualche altro passaggio:

• Crea il proxy API che vuoi proteggere con OAuth 2.0.
• Crea altri elementi che daranno la chiave consumer e il segreto consumer da scambiare per un token di accesso.

Creare un proxy API protetto

Ora dovrai creare il proxy API che vuoi proteggere. Questa è la chiamata API che restituisce ciò che vuoi. In questo caso, il proxy API chiamerà il servizio mocktarget di Apigee per restituire il tuo indirizzo IP. MA potrai visualizzarlo solo se passi un token di accesso OAuth 2.0 valido con la chiamata API.

Il proxy API creato qui includerà un criterio che controlla la presenza di un token OAuth 2.0 nella richiesta.

1. Seleziona Sviluppa > Proxy API nella barra di navigazione a sinistra.
2. Fai clic su Crea nuova.
   
3. Nella procedura guidata Crea un proxy, seleziona Proxy inverso (il più comune).
4. Configura il proxy con quanto segue:
   

   In questo campo	Fai così
   Nome del proxy	Inserisci: helloworld_oauth2
   Project Base Path	Modifica in: /hellooauth2 Il percorso di base del progetto fa parte dell'URL utilizzato per inviare richieste al proxy dell'API.
   API esistenti	Inserisci: https://mocktarget.apigee.net/ip Questo definisce l'URL di destinazione che Apigee richiama su una richiesta al proxy API.
   Descrizione	Inserisci: hello world protected by OAuth 2.0

5. Fai clic su Avanti.
6. Nella pagina Criteri comuni:

   In questo campo	Fai così
   Sicurezza: autorizzazione	Seleziona: OAuth 2.0 Queste opzioni sono molto utili. Aggiungeranno automaticamente due criteri al proxy API e creeranno un prodotto API.

7. Fai clic su Avanti.
8. Nella pagina Riepilogo, fai clic su Deployment facoltativo, seleziona un ambiente e fai clic su Crea ed esegui il deployment.
9. Fai clic su Modifica proxy per visualizzare la pagina Panoramica del proxy API.
   Il proxy API viene eseguito automaticamente. Il completamento del deployment potrebbe richiedere qualche istante.

Visualizza le norme

Diamo un'occhiata più da vicino a ciò che hai creato.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="verify-oauth-v2-access-token">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <Operation>VerifyAccessToken</Operation>
</OAuthV2>

Tieni presente che <Operation> è VerifyAccessToken. L'operazione definisce cosa deve fare il criterio. In questo caso, viene controllato se nella richiesta è presente un token OAuth 2.0 valido.

Aggiungere un prodotto API

Per ottenere un token di accesso OAuth 2.0, devi creare tre entità Apigee: un prodotto API, un sviluppatore e un'app per sviluppatori. Per prima cosa, crea il prodotto API:

1. Seleziona Pubblica > Prodotti API.
2. Fai clic su +Crea.
3. Inserisci i dettagli del prodotto per il tuo prodotto API.
   

   Campo	Descrizione
   Nome	Nome interno del prodotto API. Non specificare caratteri speciali nel nome. Nota: non puoi modificare il nome dopo aver creato il prodotto API.
   Nome visualizzato	Nome visualizzato per il prodotto API. Il nome visualizzato viene utilizzato nell'interfaccia utente e puoi modificarlo in qualsiasi momento. Se non specificato, verrà utilizzato il valore Name. Questo campo viene compilato automaticamente utilizzando il valore Nome. Puoi modificare o eliminare i relativi contenuti. Il nome visualizzato può includere caratteri speciali.
   Descrizione	Descrizione del prodotto API.
   Ambiente	Ambienti a cui il prodotto API consentirà l'accesso. Seleziona l'ambiente in cui hai eseguito il deployment del proxy API.
   Accesso	Seleziona Public (Pubbliche).
   Approvare automaticamente le richieste di accesso	Attiva l'approvazione automatica delle richieste di chiavi per questo prodotto API da qualsiasi app.
   Quota	Ignora per questo tutorial.
   Ambiti OAuth 2.0 consentiti	Ignora per questo tutorial.

4. Nella sezione Operazioni, fai clic su Aggiungi un'operazione.
5. Nel campo Proxy API, seleziona il proxy API appena creato.
6. Nel campo Percorso, inserisci "/". Ignora gli altri campi.
7. Fai clic su Salva per salvare l'operazione.
8. Fai clic su Salva per salvare il prodotto API.

Aggiungere uno sviluppatore e un'app alla tua organizzazione

A questo punto, simulerai il flusso di lavoro di uno sviluppatore che si registra per utilizzare le tue API. Idealmente, gli sviluppatori registrano se stessi e le loro app tramite il tuo portale per sviluppatori. In questo passaggio, però, aggiungerai uno sviluppatore e un'app come amministratore.

Uno sviluppatore avrà una o più app che richiamano le tue API e ogni app riceve una chiave consumer e un segreto consumer univoci. Questa chiave/questo segreto per app offre anche al fornitore di API un controllo più granulare sull'accesso alle API e report di analisi più granulari sul traffico delle API, perché Apigee sa a quale sviluppatore e a quale app appartiene ciascun token OAuth 2.0.

Creare uno sviluppatore

Creiamo uno sviluppatore di nome Nigel Tufnel.

1. Seleziona Pubblica > Sviluppatori nel menu.
2. Fai clic su + Sviluppatore.
3. Inserisci quanto segue nella finestra Nuovo sviluppatore:
   

   In questo campo	Invio
   Nome	Nigel
   Cognome	Tufnel
   Nome utente	nigel
   Email	nigel@example.com

4. Fai clic su Salva.

Registra un'app

Creiamo un'app per Nigel.

1. Seleziona Pubblica > App.
2. Fai clic su + App.
3. Inserisci quanto segue nella finestra Nuova app:
   

   In questo campo	Fai così
   Nome e Nome visualizzato	Inserisci: nigel_app
   Developer	Fai clic su Sviluppatore e seleziona: Nigel Tufnel (nigel@example.com)
   URL di callback e Note	Lascia vuoto

4. In Prodotti, fai clic su Aggiungi prodotto.
5. Aggiungi il prodotto API che hai appena creato.
6. Fai clic su Crea.

Recupera la chiave utente e il secret consumer

Ora riceverai la chiave utente e il segreto utente che verranno scambiati per un token di accesso OAuth 2.0.

1. Assicurati che venga visualizzata la pagina nigel_app. In caso contrario, nella pagina App (Pubblica > App), fai clic su nigel_app.

2. Nella pagina nigel_app, fai clic su Mostra nelle colonne Chiave e Secret. Tieni presente che la chiave/la secret sono associate al prodotto API che hai creato in precedenza.

3. Seleziona e copia la chiave e il secret. Incollali in un file di testo provvisorio. Le utilizzerai in un passaggio successivo, quando chiamerai il proxy API che scambierà queste credenziali con un token di accesso OAuth 2.0.

Prova a chiamare l'API per ottenere il tuo indirizzo IP (errore!)

Prova a chiamare il proxy API protetto che hai appena creato. Tieni presente che non stai passando un token di accesso OAuth 2.0 nella chiamata.

dove YOUR ENV_GROUP_HOSTNAME è il nome host del gruppo di ambienti. Consulta Trovare il nome host del gruppo di ambienti.

Poiché il proxy API ha il criterio Verifica token di accesso OAuth 2.0 che controlla la presenza di un token OAuth 2.0 valido nella richiesta, la chiamata dovrebbe non riuscire con il seguente messaggio:

{"fault":{"faultstring":"Invalid access token","detail":{"errorcode":"oauth.v2.InvalidAccessToken"}}}

In questo caso, l'errore è positivo. Ciò significa che il tuo proxy API è molto più sicuro. Solo le app attendibili con un token di accesso OAuth 2.0 valido possono chiamare correttamente questa API.

Ottenere un token di accesso OAuth 2.0

Successivamente, utilizzerai la chiave e il segreto che hai copiato e incollato in un file di testo e li scambierai con un token di accesso OAuth 2.0. Ora effettuerai una chiamata API al proxy di esempio dell'API che hai importato, oauth, che genererà un token di accesso API.

Utilizzando la chiave e il token segreto, effettua la seguente chiamata cURL (tieni presente che il protocollo è https):

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
"https://YOUR ENV_GROUP_HOSTNAME/oauth/client_credential/accesstoken?grant_type=client_credentials" \
-d "client_id=CLIENT_KEY&client_secret=CLIENT_SECRET"

Tieni presente che se utilizzi un client come Postman per effettuare la chiamata, client_id e client_secret vanno nel corpo della richiesta e devono essere x-www-form-urlencoded.

Dovresti ricevere una risposta simile alla seguente:

{
  "issued_at" : "1466025769306",
  "application_name" : "716bbe61-f14a-4d85-9b56-a62ff8e0d347",
  "scope" : "",
  "status" : "approved",
  "api_product_list" : "[helloworld_oauth2-Product]",
  "expires_in" : "3599", //--in seconds
  "developer.email" : "nigel@example.com",
  "token_type" : "BearerToken",
  "client_id" : "xNnREu1DNGfiwzQZ5HUN8IAUwZSW1GZW",
  "access_token" : "GTPY9VUHCqKVMRB0cHxnmAp0RXc0",
  "organization_name" : "myOrg",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

Hai ottenuto il token di accesso OAuth 2.0. Copia il valore access_token (senza virgolette) e incollalo nel file di testo. Lo utilizzerai a breve.

Cosa è successo?

Ricordi quando hai esaminato il "flusso condizionale" nel proxy oauth, quello che diceva che se l'URI della risorsa è /accesstoken e il verbo della richiesta è POST, devi eseguire il criterio OAuth 2.0 GenerateAccessTokenClient che genera un token di accesso? Il comando cURL ha soddisfatto queste condizioni, pertanto il criterio OAuth 2.0 è stato eseguito. Ha verificato la tua chiave utente e il tuo segreto utente e li ha scambiati con un token OAuth 2.0 che scade tra 1 ora.

Chiama l'API con un token di accesso (operazione riuscita)

Ora che hai un token di accesso, puoi utilizzarlo per chiamare il proxy API. Esegui la seguente chiamata cURL. Sostituisci il nome dell'organizzazione Apigee e il token di accesso.

curl https://YOUR ENV_GROUP_HOSTNAME/hellooauth2 -H "Authorization: Bearer TOKEN"

A questo punto dovresti ricevere una chiamata riuscita al proxy API che restituisce il tuo indirizzo IP. Ad esempio:

{"ip":"::ffff:192.168.14.136"}

Puoi ripetere la chiamata API per quasi un'ora, dopodiché il token di accesso scade. Per effettuare la chiamata dopo un'ora, dovrai generare un nuovo token di accesso utilizzando i passaggi precedenti.

Complimenti! Hai creato un proxy API e lo hai protetto richiedendo che nella chiamata sia incluso un token di accesso OAuth 2.0 valido.

Argomenti correlati

• Home page di OAuth 2.0
• Norme di OAuthV2
• Scarica i proxy API (che mostra come raggruppare un proxy API in un file ZIP come quello che hai scaricato)