Proteggi un'API con OAuth 2.0

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Stai visualizzando la documentazione di Apigee e Apigee ibrido.
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 a:

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

Devi inoltre avere un nome host del gruppo di ambienti configurato correttamente per effettuare chiamate al proxy API Apigee. Se hai dubbi sul nome host del gruppo di ambienti da utilizzare, consulta il tuo amministratore Apigee.

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

  1. Scarica il proxy API di esempio oauth in una directory nel tuo file system.
  2. Vai alla UI di Apigee, accedi e seleziona l'organizzazione Apigee.
  3. Seleziona Sviluppo > Proxy API nella barra di navigazione a sinistra.
  4. Fai clic su Crea nuovo.
    Pulsante Crea proxy
  5. Nella procedura guidata Crea proxy, seleziona Carica pacchetto proxy.
  6. Scegli il file oauth.zip che hai 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 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 il deployment di un proxy API di 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.

Nuovo editor proxy

Successivamente, approfondiremo l'argomento del proxy API.

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

    Criteri visualizzati nella scheda Sviluppo.

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

  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 una determinata condizione è soddisfatta (denominata "flusso condizionale"). La condizione, definita nell'elemento <Condition>, indica che, se la chiamata proxy API viene effettuata 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 attiverà il flusso condizionale. Fai clic sul criterio GenerateAccessTokenClient nel riquadro Richiesta: Fai clic suGenerateAccessTokenClient sotto AccessTokenClientCredential.

Editor proxy classico

Successivamente, approfondiremo l'argomento del proxy API.

  1. Nell'editor del proxy API, fai clic sulla scheda Develop. 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 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 proxy API viene effettuata alla risorsa /accesstoken e il verbo di richiesta è POST, viene eseguito il criterio GenerateAccessTokenClient, che genera il token di accesso.

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

    Icona del criterio CreateAccessTokenClient 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 il criterio che verrà eseguito. In questo caso, genererà un token di accesso.
  • Il token scadrà un'ora (360.000 millisecondi) dopo essere stato generato.
  • In <SupportedGrantTypes>, il token OAuth 2.0 <GrantType> da utilizzare è client_credentials (scambio di una chiave utente e di un secret con un token OAuth 2.0).
  • Il secondo elemento <GrantType> indica il criterio in cui cercare la chiamata API per il parametro del tipo di autorizzazione, come richiesto dalla specifica OAuth 2.0. Lo vedrai nella chiamata API in un secondo momento. 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. Ma prima devi eseguire alcune altre operazioni:

  • Crea il proxy API che vuoi proteggere con OAuth 2.0.
  • Crea altri artefatti che daranno accesso alla chiave consumer e al secret del consumatore che dovrai 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 vuoi. In questo caso, il proxy API chiama il servizio fittizia di Apigee per restituire il tuo indirizzo IP. MA, potrai vederlo solo se trasmetti un token di accesso OAuth 2.0 valido con la tua chiamata API.

Il proxy API creato 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.
    Pulsante Crea proxy
  3. Nella procedura guidata Crea un proxy, seleziona Inverti proxy (più comune).
  4. Configura il proxy con i seguenti elementi:
    In questo campo fallo
    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 dell'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 Next (Avanti).
  6. Nella pagina Norme comuni:
    In questo campo fallo
    Sicurezza: autorizzazione Seleziona:
    • OAuth 2.0

    Queste opzioni sono molto utili. Aggiungeranno automaticamente due criteri al proxy API e creeranno un prodotto API.

  7. Tocca Next (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 istanti.

Visualizza le norme

Analizziamo nel dettaglio ciò che hai creato.

Nuovo editor proxy

  1. Nell'editor del proxy API, fai clic sulla scheda Develop. Noterai che sono stati aggiunti due criteri al flusso di richiesta del proxy API:
    • Verifica token di accesso OAuth 2.0: controlla la chiamata API per assicurarsi che sia presente un token OAuth 2.0 valido.
    • Rimuovi autorizzazione di intestazione: un criterio di assegnazione di messaggi che rimuove il token di accesso dopo che è stato selezionato, in modo che non venga trasmesso al servizio di destinazione. Se il servizio target ha bisogno del token di accesso OAuth 2.0, non devi utilizzare questo criterio.
  2. Fai clic sull'icona Verifica token di accesso OAuth 2.0 nel riquadro a destra e osserva il codice XML sottostante nell'editor di testo.

Editor proxy classico

  1. Nell'editor del proxy API, fai clic sulla scheda Develop. Noterai che sono stati aggiunti due criteri al flusso di richiesta del proxy API:
    • Verifica token di accesso OAuth 2.0: controlla la chiamata API per assicurarsi che sia presente un token OAuth 2.0 valido.
    • Rimuovi autorizzazione di intestazione: un criterio di assegnazione di messaggi che rimuove il token di accesso dopo che è stato selezionato, in modo che non venga trasmesso al servizio di destinazione. Se il servizio target ha bisogno del token di accesso OAuth 2.0, non devi utilizzare questo criterio.
  2. Fai clic sull'icona Verifica token di accesso OAuth 2.0 nella visualizzazione flusso e osserva il codice XML sottostante al suo interno.

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

Nota che <Operation> è VerifyAccessToken. L'operazione definisce ciò che il criterio deve fare. In questo caso, controllerà un token OAuth 2.0 valido nella richiesta.

Aggiungi un prodotto API

Per ottenere un token di accesso OAuth 2.0, devi creare tre entità Apigee: un prodotto API, uno sviluppatore e un'applicazione sviluppatore. Per prima cosa, 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 è possibile 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 Nome. Questo campo viene compilato automaticamente utilizzando il valore 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 Abilita l'approvazione automatica delle richieste principali 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 API Proxy, 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.

Aggiungi uno sviluppatore e un'app alla tua organizzazione

Stai per simulare il flusso di lavoro di uno sviluppatore che si registra per utilizzare le tue API. Idealmente, gli sviluppatori si registrano autonomamente e ricevono le app tramite il portale per gli sviluppatori. In questo passaggio, tuttavia, devi aggiungere uno sviluppatore e un'app come amministratore.

Uno sviluppatore avrà una o più app che chiamano le tue API e ogni app riceverà una chiave consumer e un consumer secret univoci. Questa chiave/segreto per app offre inoltre al provider di API il controllo più granulare sull'accesso alle API e report di analisi più granulari sul traffico delle API, perché Apigee sa quale sviluppatore e app appartengono a quale 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 Giulia.

  1. Seleziona Pubblica > App.
  2. Fai clic su + App.
  3. Inserisci quanto segue nella finestra Nuova app:
    In questo campo fallo
    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 Add product (Aggiungi prodotto).
  5. Aggiungi il prodotto API appena creato.
  6. Fai clic su Crea.

Ottieni la chiave e il segreto del consumatore

Ora otterrai la chiave utente e il consumer secret che verranno scambiati con 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. Nota che la chiave/il segreto sono associati al prodotto API creato in precedenza.

  3. Seleziona e copia la chiave e il secret. Incollali in un file di testo temporaneo. Li utilizzerai in un passaggio successivo, in cui utilizzerai il proxy API che scambia queste credenziali con un token di accesso OAuth 2.0.

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

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

dove YOUR ENV_GROUP_HOSTNAME è il nome host del gruppo di ambienti. Vedi Trova il nome host del gruppo di ambienti.

Poiché il proxy API ha il criterio Verifica il token di accesso OAuth 2.0 che controlla 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 va 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, dovrai utilizzare la chiave e il secret copiati e incollati in un file di testo e scambiarli 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 all'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, 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 ricevuto il token di accesso OAuth 2.0. Copia il valore access_token (senza le virgolette) e incollalo nel file di testo. Lo utilizzerai tra poco.

Che cos'è appena successo?

Ricordate in precedenza quando avete esaminato il "flusso condizionale" nel proxy oauth, quello che dice che se l'URI della risorsa è /accesstoken e il verbo della richiesta è POST, per eseguire il criterio OAuth 2.0 di GenerateAccessTokenClient che genera un token di accesso? Il tuo comando cURL ha soddisfatto queste condizioni, pertanto il criterio OAuth 2.0 è stato eseguito. Ha verificato la tua chiave e il tuo secret consumer e li ha scambiati con un token OAuth 2.0 che scade tra un'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. 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"

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