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

  • Crea e implementa proxy API
  • Crea prodotti API
  • Creare app sviluppatore

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 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 ed eseguire il deployment di questo proxy API nel tuo ambiente:

Scarica il oauth proxy API di esempio in una directory del tuo file system.

Apigee nella console Cloud

  1. Nella console Google Cloud , vai alla pagina Sviluppo proxy > Proxy API.

    Vai ai proxy API

  2. Nel riquadro Proxy API, fai clic su + Crea.
  3. Nel riquadro Crea un proxy, in Modello di proxy, seleziona Carica bundle proxy.
  4. Scegli il file oauth.zip che hai scaricato e fai clic su Avanti.
  5. Fai clic su Avanti.
  6. Deployment (facoltativo):
    • Deployment environments (ambienti di deployment): facoltativo. Utilizza le caselle di controllo per selezionare uno o più ambienti in cui eseguire il deployment del proxy. Se preferisci non eseguire il deployment del proxy in questo punto, lascia vuoto il campo Ambienti di deployment. Puoi sempre eseguire il deployment del proxy in un secondo momento.
    • Service account: facoltativo. Collega un account di servizio al deployment per consentire al proxy di accedere ai servizi Google Cloud , come specificato nel ruolo e nelle autorizzazioni del account di servizio.
  7. Fai clic su Crea.

Apigee classico

  1. Vai all'interfaccia utente Apigee, accedi e seleziona la tua organizzazione Apigee.
  2. Seleziona Sviluppa > Proxy API nella barra di navigazione a sinistra.
  3. Fai clic su Crea nuovo.
    Pulsante Crea proxy
  4. Nella procedura guidata di creazione del proxy, seleziona Carica bundle proxy.
  5. Scegli il file oauth.zip che hai scaricato e fai clic su Avanti.
  6. Fai clic su Crea.
  7. Al termine della build, fai clic su Modifica proxy per visualizzare il nuovo proxy nell'editor proxy API.
  8. Fai clic su Esegui il deployment.
  9. Seleziona la revisione e l'ambiente in cui eseguire il deployment. Puoi lasciare vuoto il campo Service account.
  10. 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.

Visualizza il flusso e le norme OAuth 2.0

Dedica qualche istante a esaminare la configurazione delle norme OAuth 2.0.

Console Apigee Cloud

Successivamente, esaminerai più da vicino i contenuti del proxy API.

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

    Norme visualizzate nella scheda Sviluppa.

    Nel riquadro a sinistra vedrai due norme. Vedrai anche due flussi POST nella sezione Proxy Endpoints.

  2. Fai clic su AccessTokenClientCredential in Endpoint proxy. L'editor di testo mostra 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 è un passaggio di elaborazione in un proxy API. In questo caso, il flusso viene attivato quando viene soddisfatta una determinata condizione (si chiama "flusso condizionale"). La condizione, definita nell'elemento <Condition>, indica che se la chiamata al proxy API viene effettuata alla risorsa /accesstoken e il verbo della richiesta è POST, viene eseguita la policy GenerateAccessTokenClient, che genera il token di accesso.

  3. Ora vediamo il criterio che attiverà il flusso condizionale. Fai clic sul criterio GenerateAccessTokenClient nel riquadro Richiesta: Fai clic su GenerateAccessTokenClient sotto AccessTokenClientCredential.

Apigee classico

Successivamente, esaminerai più da vicino i contenuti del proxy API.

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

  2. Fai clic su AccessTokenClientCredential in Endpoint proxy.
    Codice XML per il flusso condizionale.

    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 è un passaggio 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 la chiamata al proxy API viene effettuata alla risorsa /accesstoken e il verbo della richiesta è POST, viene eseguita la norma GenerateAccessTokenClient, che genera il token di accesso.

  3. Ora vediamo il criterio che attiverà il flusso condizionale. Fai clic sull'icona del criterio GenerateAccessTokenClient nel diagramma di flusso.

    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 diversi valori predefiniti, definisce l'azione del criterio. In questo caso, genererà un token di accesso.
  • Il token scadrà 1 ora (3600000 millisecondi) dopo essere stato generato.
  • In <SupportedGrantTypes>, l'<GrantType> OAuth 2.0 previsto è client_credentials (scambio di una chiave e un secret del consumer con un token OAuth 2.0).
  • Il secondo elemento <GrantType> indica alla policy dove cercare nella chiamata API il parametro del tipo di concessione, come richiesto dalla specifica OAuth 2.0. Lo vedrai più avanti nella chiamata API. 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 fare altre cose:

  • Crea il proxy API che vuoi proteggere con OAuth 2.0.
  • Crea altri artefatti che genereranno la chiave utente e il secret consumer che devi scambiare con un token di accesso.

Crea un proxy API protetto

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

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

Apigee nella console Cloud

  1. Nella console Google Cloud , vai alla pagina Sviluppo proxy > Proxy API.

    Vai ai proxy API

  2. Nel riquadro Proxy API, fai clic su + Crea.
  3. Nel riquadro Crea un proxy, in Modello di proxy, seleziona Proxy inverso (il più comune).
  4. Configura il proxy con quanto segue:
    In questo campo Fai questo
    Nome proxy Inserisci: helloworld_oauth2
    Base Path

    Cambia con: /hellooauth2

    Il percorso di base del progetto fa parte dell'URL utilizzato per effettuare richieste al proxy API.
    Descrizione Inserisci: hello world protected by OAuth 2.0
    Target (API esistente)

    Inserisci: https://mocktarget.apigee.net/ip

    Definisce l'URL di destinazione richiamato da Apigee in una richiesta al proxy API.
  5. Fai clic su Avanti.
  6. Deployment (facoltativo):
    • Deployment environments (ambienti di deployment): facoltativo. Utilizza le caselle di controllo per selezionare uno o più ambienti in cui eseguire il deployment del proxy. Se preferisci non eseguire il deployment del proxy in questo punto, lascia vuoto il campo Ambienti di deployment. Puoi sempre eseguire il deployment del proxy in un secondo momento.
    • Service account: facoltativo. Collega un account di servizio al deployment per consentire al proxy di accedere ai servizi Google Cloud , come specificato nel ruolo e nelle autorizzazioni del account di servizio.
  7. Fai clic su Crea.
  8. Fai clic sulla scheda Sviluppa del proxy helloworld_oauth2.
  9. Nel menu Norme, fai clic su Aggiungi norma.
  10. Nel riquadro Crea criterio, seleziona OAuth 2.0.
  11. Fai clic su Crea.

Apigee classico

  1. Vai all'interfaccia utente Apigee, accedi e seleziona la tua organizzazione Apigee.
  2. Seleziona Sviluppa > Proxy API nella barra di navigazione a sinistra.
  3. Fai clic su Crea nuovo.
    Pulsante Crea proxy
  4. Nella procedura guidata Crea un proxy, seleziona Reverse proxy (il più comune).
  5. Configura il proxy con quanto segue:
    In questo campo Fai questo
    Nome proxy Inserisci: helloworld_oauth2
    Project Base Path

    Cambia con: /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

    Definisce l'URL di destinazione richiamato da Apigee in una richiesta al proxy API.
    Descrizione Inserisci: hello world protected by OAuth 2.0
  6. Fai clic su Avanti.
  7. Nella pagina Policy 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.
  8. Fai clic su Avanti.
  9. Nella pagina Riepilogo, in Deployment facoltativo, seleziona un ambiente e fai clic su Crea ed esegui il deployment.
  10. Fai clic su Modifica proxy per visualizzare la pagina Panoramica del proxy API.
    Il proxy API viene implementato automaticamente. Il completamento del deployment potrebbe richiedere alcuni istanti.

Visualizzare le norme

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

Console Apigee Cloud

  1. Nell'editor proxy API, fai clic sulla scheda Sviluppa. Vedrai che sono state aggiunte due norme al flusso di richieste del proxy API:
    • Verifica del token di accesso OAuth v2.0: controlla la chiamata API per assicurarsi che sia presente un token OAuth 2.0 valido.
    • Rimuovi autorizzazione intestazione: un criterio Assegna messaggio che rimuove il token di accesso dopo che è stato controllato, in modo che non venga passato al servizio di destinazione. (Se il servizio di destinazione avesse bisogno del token di accesso OAuth 2.0, non utilizzeresti queste norme).

  2. Fai clic sull'icona Verifica token di accesso OAuth v2.0 nel riquadro a destra e guarda l'XML sottostante nell'editor di testo.

Apigee classico

  1. Nell'editor proxy API, fai clic sulla scheda Sviluppa. Vedrai che sono state aggiunte due norme al flusso di richieste del proxy API:
    • Verifica del token di accesso OAuth v2.0: controlla la chiamata API per assicurarsi che sia presente un token OAuth 2.0 valido.
    • Rimuovi autorizzazione intestazione: un criterio Assegna messaggio che rimuove il token di accesso dopo che è stato controllato, in modo che non venga passato al servizio di destinazione. (Se il servizio di destinazione avesse bisogno del token di accesso OAuth 2.0, non utilizzeresti queste norme).

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

    Verifica del codice del token di accesso OAuth 2.0

<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, verificherà la presenza di un token OAuth 2.0 valido nella richiesta.

Aggiungere un prodotto API

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

  1. Crea il prodotto API:

    2. Apigee nella console Cloud

    Nella console Google Cloud , vai alla pagina Distribuzione > Prodotti API.

    Vai a Prodotti API

    Apigee classico

    Nell'interfaccia utente Apigee, vai a 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 una volta 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 Nome. Questo campo viene compilato automaticamente utilizzando il valore Nome. Puoi modificare o eliminare i contenuti. Il nome visualizzato può includere caratteri speciali.
    Descrizione Descrizione del prodotto API.
    Ambiente Gli 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

Successivamente, 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, invece, 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 consumer e un secret consumer unici. Questa chiave/secret per app offre anche a te, il fornitore di API, un controllo più granulare sull'accesso alle tue API e report di analisi più granulari sul traffico API, perché Apigee sa a quale token OAuth 2.0 appartengono lo sviluppatore e l'app.

Creare uno sviluppatore

Creiamo uno sviluppatore di nome Nigel Tufnel.

Apigee nella console Cloud

  1. Apri l'editor Sviluppatore.

  2. Nella console Google Cloud , vai alla pagina Distribuzione > Sviluppatori.

    Vai a Sviluppatori

  3. Fai clic su + Crea.
  4. Inserisci quanto segue nella finestra Aggiungi sviluppatore:
    In questo campo Invio
    Nome Nigel
    Cognome Tufnel
    Email nigel@example.com
    Nome utente nigel
  5. Fai clic su Aggiungi.

Apigee classico

  1. Apri l'editor Sviluppatore.

  2. Nell'interfaccia utente Apigee, vai a Pubblica > Sviluppatori.

  3. Fai clic su + Sviluppatore.
  4. Nella finestra Crea uno sviluppatore, inserisci quanto segue:
    In questo campo Invio
    Nome Nigel
    Cognome Tufnel
    Email nigel@example.com
    Nome utente nigel
  5. Fai clic su Crea.

Registrare un'app

Creiamo un'app per Norberto.

Apigee nella console Cloud

  1. Nella console Google Cloud , vai alla pagina Distribuzione > App.

    Vai ad App

  2. Fai clic su + Crea.
  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 (nigel@example.com)
    URL di callback e Note Lascia vuoto
  4. Fai clic su + Aggiungi credenziali.
  5. Fai clic su + Aggiungi prodotti.
  6. Seleziona il prodotto API appena creato.
  7. Fai clic su Aggiungi.
  8. Fai clic su Crea.

Apigee classico

  1. Nell'interfaccia utente Apigee, vai a Pubblica > Sviluppatori.

  2. Fai clic su + Sviluppatore.
  3. Fai clic su + App.
  4. 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 (nigel@example.com)
    URL di callback e Note Lascia vuoto
  5. In Prodotti, fai clic su Aggiungi prodotto.
  6. Aggiungi il prodotto API che hai appena creato.
  7. Fai clic su Crea.

Ottieni la chiave utente e il secret consumer

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

  1. Apri la pagina nigel_app.

    2. Apigee nella console Cloud

    1. Assicurati che venga visualizzata la pagina nigel_app. In caso contrario, vai alla pagina Distribuzione > App.

      Vai ad App

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

    Apigee classico

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

  2. Seleziona e copia i valori di Chiave e Secret. Incollali in un file di testo temporaneo. Li utilizzerai in un passaggio successivo, in cui 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 (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. Consulta Trovare il nome host del gruppo di ambienti.

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

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

In questo caso, il fallimento è un bene. Ciò significa che il 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 API di esempio che hai importato, oauth, che genererà un token di accesso API.

Utilizzando la chiave e il secret, 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, i parametri client_id e client_secret vanno inseriti nel corpo della richiesta e devono essere x-www-form-urlencoded.

Dovresti ricevere una risposta simile a questa:

{
  "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 userai tra poco.

Che 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, deve essere eseguita la norma OAuth 2.0 GenerateAccessTokenClient che genera un token di accesso? Il comando cURL soddisfaceva queste condizioni, pertanto è stata eseguita la norma OAuth 2.0. Ha verificato la chiave utente e il segreto utente e li ha scambiati con un token OAuth 2.0 che scade dopo 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 scadrà. Per effettuare la chiamata dopo un'ora, dovrai generare un nuovo token di accesso seguendo 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