Proteggi 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 di cui disponi dell'autorizzazione per:

• Crea ed esegui il deployment dei proxy API
• Creare prodotti API
• Creare app per sviluppatori

Devi inoltre avere 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, consulta l'amministratore Apigee.

Eseguire il deployment del proxy OAuth 2.0

Su GitHub forniamo un proxy API che è configurato per generare token di accesso OAuth 2.0. Segui questi passaggi per scaricare questo proxy API ed eseguirne il deployment nel tuo ambiente:

1. Scarica il proxy API di esempio oauth in una directory sul tuo file system.
2. Vai all'interfaccia utente di Apigee, accedi e seleziona la tua organizzazione Apigee.
3. Seleziona Sviluppo > Proxy API nella barra di navigazione a sinistra.
   Nota: prima di continuare, esamina o cerca nell'elenco di proxy API. Se ne hai già una chiamata oauth, fai clic su questa voce e passa alla sezione successiva per assicurarti che sia configurata come quella descritta. Se la tua è diversa, eliminala e continua con questi passaggi oppure modificala in modo che corrisponda alla configurazione descritta.
4. Fai clic su Crea nuovo.
   
5. Nella procedura guidata Crea proxy, seleziona Carica bundle di proxy.
6. Scegli il file oauth.zip scaricato e fai clic su Avanti.
7. Fai clic su Crea.
8. Al termine della build, fai clic su Modifica proxy per visualizzare il nuovo proxy nell'editor 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 per la generazione di token di accesso nella tua organizzazione Apigee.

Visualizzare il flusso e il criterio OAuth 2.0

Dedica qualche istante a esaminare la configurazione dei criteri OAuth 2.0.

Nota: Apigee sta introducendo una nuova versione dell'editor proxy, che semplificherà la gestione dei proxy.

Le istruzioni nelle prime due schede di seguito spiegano come utilizzare il nuovo Proxy Editor o la versione classica.

Nuovo editor proxy

Ora analizzerai più da vicino cosa contiene il proxy API.

1. Nell'editor proxy API, fai clic sulla scheda Sviluppo.

   

   Nel riquadro a sinistra vedrai due criteri. Vedrai anche due flussi POST nella sezione Endpoint proxy.

2. Fai clic su AccessTokenClientCredential in Proxy Endpoints. L'editor di testo visualizza il codice XML per il flusso condizionale AccessTokenClientCredential:

   <Flow name="AccessTokenClientCredential">
       <Description/>
       <Request>
           <Step>
               <Name>GenerateAccessTokenClient</Name>
           </Step>
       </Request>
       <Response/>
       <Condition>(proxy.pathsuffix MatchesPath "/accesstoken") and (request.verb = "POST")</Condition>
   </Flow>
   

   Un flusso è una fase di elaborazione in un proxy API. In questo caso, il flusso viene attivato quando viene soddisfatta una determinata condizione (è chiamato "flusso condizionale"). La condizione, definita nell'elemento <Condition>, indica che se viene effettuata la chiamata proxy API alla risorsa /accesstoken e il verbo della richiesta è POST, esegui il criterio GenerateAccessTokenClient, che genera il token di accesso.

3. Ora diamo un'occhiata al criterio che verrà attivato dal flusso condizionale. Fai clic sul criterio GenerateAccessTokenClient nel riquadro Richiesta:

Editor proxy classico

Ora analizzerai più da vicino cosa contiene il proxy API.

1. Nell'editor proxy API, fai clic sulla scheda Sviluppo. Nel riquadro di navigazione a sinistra vedrai due criteri. Vedrai anche due flussi POST nella sezione Endpoint proxy.

2. Fai clic su AccessTokenClientCredential in Endpoint proxy.
   

   Nella visualizzazione del codice XML, vedrai un Flow chiamato AccessTokenClientCredential:

   <Flow name="AccessTokenClientCredential">
       <Description/>
       <Request>
           <Step>
               <Name>GenerateAccessTokenClient</Name>
           </Step>
       </Request>
       <Response/>
       <Condition>(proxy.pathsuffix MatchesPath "/accesstoken") and (request.verb = "POST")</Condition>
   </Flow>
   

   Un flusso è una fase di elaborazione in un proxy API. In questo caso, il flusso viene attivato quando viene soddisfatta una determinata condizione. La condizione, definita nell'elemento <Condition>, è che se viene effettuata la chiamata proxy API alla risorsa /accesstoken e il verbo della richiesta è POST, esegui il criterio GenerateAccessTokenClient, che genera il token di accesso.

3. Ora diamo un'occhiata al criterio che verrà attivato dal flusso condizionale. Fai clic sull'icona del criterio GenerateAccessTokenClient nel diagramma di flusso.

   

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 dei vari valori predefiniti, definisce lo scopo del criterio. In questo caso, genererà un token di accesso.
• Il token scadrà 1 ora (3600000 millisecondi) dopo essere stato generato.
• In <SupportedGrantTypes>, l'utilizzo di OAuth 2.0 <GrantType> previsto è client_credentials (scambiando una chiave e un secret dell'utente con un token OAuth 2.0).
• Il secondo elemento <GrantType> indica al criterio dove cercare il parametro del tipo di autorizzazione nella chiamata API, come richiesto dalla specifica OAuth 2.0. (lo vedrai nella chiamata API in seguito). Il tipo di autorizzazione 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 eseguire alcune altre operazioni:

• Crea il proxy API che vuoi effettivamente proteggere con OAuth 2.0.
• Crea qualche altro artefatto che genererà la chiave e il consumer secret che dovrai scambiare con un token di accesso.

Nota: il flusso e il criterio UpdateAccessToken nel proxy API non vengono utilizzati in questo tutorial e non sono supportati con il tipo di concessione delle credenziali client OAuth 2.0.

Crea un proxy API protetto

Ora creerai il proxy API che vuoi proteggere. Questa è la chiamata API che restituisce qualcosa che vuoi. In questo caso, il proxy API chiamerà il servizio fittizio di Apigee per restituire il tuo indirizzo IP. Potrai vederlo solo se passi un token di accesso OAuth 2.0 valido con la tua chiamata API.

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

1. Seleziona Sviluppo > Proxy API nella barra di navigazione a sinistra.
2. Fai clic su Crea nuovo.
   
3. Nella procedura guidata Crea un proxy, seleziona Inverti proxy (più comune).
4. Configura il proxy con i seguenti metodi:
   

   In questo campo	fai questo
   Nome proxy	Inserisci: helloworld_oauth2
   Percorso base del progetto	Cambia in: /hellooauth2 Il percorso di base del progetto fa parte dell'URL utilizzato per effettuare richieste al proxy API.
   API esistente	Inserisci: https://mocktarget.apigee.net/ip Questo definisce l'URL di destinazione che Apigee richiama su una richiesta al proxy API.
   Description	Inserisci: hello world protected by OAuth 2.0

5. Tocca Avanti.
6. Nella pagina Norme comuni:

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

7. Tocca Avanti.
8. Nella pagina Riepilogo, in 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 deployment del proxy API viene eseguito automaticamente. Il completamento del deployment potrebbe richiedere alcuni minuti.

Visualizza le norme

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

Nuovo editor proxy

1. Nell'editor proxy API, fai clic sulla scheda Sviluppo. Vedrai che sono stati aggiunti due criteri al flusso di richiesta del proxy API:
   • Verifica token di accesso OAuth v2.0: controlla la chiamata API per verificare che sia presente un token OAuth 2.0 valido.
   • Rimuovi autorizzazione intestazione: un criterio di assegnazione dei messaggi che rimuove il token di accesso dopo la verifica, in modo che non venga passato al servizio di destinazione. Se il servizio di destinazione necessita del token di accesso OAuth 2.0, non devi utilizzare questo criterio.

2. Fai clic sull'icona Verifica token di accesso OAuth v2.0 nel riquadro di destra e osserva il codice XML sottostante nell'editor di testo.

Editor proxy classico

1. Nell'editor proxy API, fai clic sulla scheda Sviluppo. Vedrai che sono stati aggiunti due criteri al flusso di richiesta del proxy API:
   • Verifica token di accesso OAuth v2.0: controlla la chiamata API per verificare che sia presente un token OAuth 2.0 valido.
   • Rimuovi autorizzazione intestazione: un criterio di assegnazione dei messaggi che rimuove il token di accesso dopo la verifica, in modo che non venga passato al servizio di destinazione. Se il servizio di destinazione necessita del token di accesso OAuth 2.0, non devi utilizzare questo criterio.

2. Fai clic sull'icona Verifica token di accesso OAuth v2.0 nella visualizzazione del flusso e osserva il codice XML sottostante nel riquadro del codice.

   

<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>

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

Aggiungi un prodotto API

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

1. Seleziona Pubblica > Prodotti API.
2. Fai clic su +Crea.
3. Inserisci i dettagli del 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 del prodotto API. Il nome visualizzato viene utilizzato nell'interfaccia utente e puoi modificarlo in qualsiasi momento. Se non specificato, verrà utilizzato il valore Nome. Questo campo viene compilato automaticamente utilizzando il valore del campo Nome; puoi modificarne o eliminarne i 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).
   Approva automaticamente le richieste di accesso	Attiva l'approvazione automatica delle richieste chiave 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 che hai 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.

Aggiungi uno sviluppatore e un'app alla tua organizzazione

Quindi, simulerai il flusso di lavoro di uno sviluppatore che si iscrive per utilizzare le tue API. Idealmente, gli sviluppatori si registrano e le loro app tramite il tuo portale per sviluppatori. Tuttavia, in questo passaggio aggiungerai uno sviluppatore e un'app come amministratore.

Uno sviluppatore avrà una o più app che chiamano le tue API e ogni app riceve una chiave e un consumer secret univoci. Questa chiave/secret per app offre inoltre al provider di API un controllo più granulare sull'accesso alle API e report di analisi più granulari sul traffico API, poiché Apigee sa quale sviluppatore e app appartengono a quale token OAuth 2.0.

Creare uno sviluppatore

Creiamo uno sviluppatore chiamato Nigel Tufnel.

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

   In questo campo	Invio
   Nome	Nigel
   Cognome	Tufnel
   Nome utente	nigel
   Email	[e-mail]

4. Fai clic su Salva.

Registra un'app

Creiamo un'app per Nigel.

1. Seleziona Pubblica > App.
2. Fai clic su + App.
3. Nella finestra Nuova app, inserisci quanto segue:
   

   In questo campo	fai questo
   Nome e Nome visualizzato	Inserisci: nigel_app
   Developer	Fai clic su Sviluppatore e seleziona: Nigel Tufnel ([e-mail])
   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.

Recupero chiave e segreto utente

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

1. Assicurati che sia 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/il secret sono associati al prodotto API che hai creato in precedenza.

3. Seleziona e copia la chiave e il secret. Incollali in un file di testo temporaneo. Le utilizzerai in un passaggio successivo, dove chiami il proxy API che scambierà queste credenziali per un token di accesso OAuth 2.0.

Prova a chiamare l'API per ottenere il tuo indirizzo IP (operazione non riuscita)

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. Vedi Trovare il nome host del gruppo di ambienti.

Poiché il proxy API dispone del criterio Verifica token di accesso OAuth v2.0 che verifica la presenza di un token OAuth 2.0 valido nella richiesta, la chiamata non dovrebbe riuscire con il seguente messaggio:

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

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

Richiedere un token di accesso OAuth 2.0

Successivamente, utilizzerai la chiave e il secret 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 API di esempio che hai importato, oauth, che genererà un token di accesso all'API.

Utilizza la chiave e il secret per effettuare 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" : "[e-mail]",
  "token_type" : "BearerToken",
  "client_id" : "xNnREu1DNGfiwzQZ5HUN8IAUwZSW1GZW",
  "access_token" : "GTPY9VUHCqKVMRB0cHxnmAp0RXc0",
  "organization_name" : "myOrg",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

Hai ricevuto il tuo token di accesso per OAuth 2.0. Copia il valore access_token (senza virgolette) e incollalo nel file di testo. Lo utilizzerai tra poco.

Che cos'è appena successo?

Ricordi che in precedenza, quando guardavi il "flusso condizionale" nel proxy oauth, quello che indicava che, se l'URI della risorsa è /accesstoken e il verbo della richiesta è POST, per eseguire il criterio OAuth 2.0 GenerateAccessTokenClient che genera un token di accesso? Il comando cURL soddisfava queste condizioni, pertanto è stato eseguito il criterio OAuth 2.0. Ha verificato la tua chiave e il tuo secret consumatore e li ha scambiati con un token OAuth 2.0 che scade dopo un'ora.

Chiamata all'API con un token di accesso (operazione riuscita)

Ora che disponi di un token di accesso, puoi utilizzarlo per chiamare il proxy API. Effettua 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 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 scadrà. 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 l'inclusione di un token di accesso OAuth 2.0 valido nella chiamata.

Argomenti correlati

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