Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
OAuth si è rivelato il protocollo di autorizzazione più utilizzato per le API. La versione di OAuth descritta in dettaglio in questo argomento è definita nella specifica OAuth 2.0.
OAuth è un protocollo che consente agli utenti finali delle app di autorizzare le app ad agire per loro conto. Le app possono farlo ottenendo token di accesso dai provider API. Il provider di API autentica le credenziali dell'utente finale dell'app, garantisce che l'utente abbia autorizzato l'app e poi invia un token di accesso all'app. Quando l'app utilizza un'API protetta, Apigee Edge controlla il token di accesso per verificare che sia valido e che non sia scaduto. In qualità di provider di API, devi esporre endpoint che consentono alle app di ottenere token di accesso.
Per iniziare a utilizzare facilmente OAuth, Apigee Edge ti consente di configurare e applicare OAuth utilizzando i criteri, senza che tu debba scrivere alcun codice. In questo argomento imparerai a proteggere le API, a ottenere i token di accesso e a utilizzarli per accedere alle API protette.
La configurazione OAuth predefinita per la tua organizzazione
Per praticità, tutte le organizzazioni su Apigee Edge vengono fornite preconfigurate con un set di endpoint OAuth 2.0 che implementano il tipo di concessione delle credenziali client. Il tipo di concessione delle credenziali client definisce una procedura per l'emissione di token di accesso in cambio di credenziali dell'app. Queste credenziali dell'app sono semplicemente la coppia chiave e secret dell'utente che Apigee Edge genera per ogni app registrata in un'organizzazione. "Credenziali client" si riferisce alla coppia chiave e secret dell'utente.
Per scoprire di più sull'emissione di credenziali alle app utilizzando i Servizi per sviluppatori periferici, consulta Registrare le app e gestire le chiavi.
Per questo motivo, è relativamente semplice "intensificare" lo schema di sicurezza dell'API dalla convalida della chiave API alle credenziali client OAuth. Entrambi gli schemi utilizzano la stessa chiave utente e lo stesso secret per convalidare l'app client. La differenza è che le credenziali client forniscono un ulteriore livello di controllo, poiché puoi revocare facilmente un token di accesso quando necessario, senza che tu debba revocare la chiave utente dell'app. Per utilizzare gli endpoint OAuth predefiniti, puoi utilizzare qualsiasi chiave e secret consumer generati per l'app nella tua organizzazione per recuperare i token di accesso dall'endpoint del token. Puoi anche abilitare le credenziali client per le app che hanno già secret e chiavi utente.
La specifica completa per la concessione delle credenziali client è disponibile nella specifica OAuth 2.0.
Proteggere l'API con un criterio
Prima di poter utilizzare i token di accesso, devi configurare le API per convalidare i token di accesso OAuth in fase di runtime. A questo scopo, devi configurare un proxy API per validate i token di accesso. Ciò significa che ogni volta che un'app effettua una richiesta per consumare una delle API, l'app deve presentare un token di accesso valido insieme alla richiesta API. Apigee Edge gestisce la complessità alla base della generazione, dell'archiviazione e della convalida dei token di accesso presentati.
Puoi aggiungere facilmente la verifica OAuth a un'API quando crei un nuovo proxy API. Quando crei un nuovo proxy API, puoi aggiungere funzionalità. Come mostrato di seguito, puoi aggiungere la verifica dei token di accesso OAuth 2.0 selezionando il pulsante di opzione accanto a Proteggi con i token di accesso OAuth v2.0. Quando selezioni questa opzione, al proxy API appena creato verranno associati due criteri, uno per verificare i token di accesso e un altro per rimuovere il token di accesso dopo la verifica.
Inoltre, quando selezioni l'opzione Proteggi con token di accesso OAuth v2.0, la casella di controllo Pubblica prodotto API diventa selezionabile e viene selezionata automaticamente. Seleziona questa opzione se vuoi generare automaticamente un prodotto quando crei il nuovo proxy API. Il prodotto generato automaticamente verrà creato con un'associazione al nuovo proxy API. Se disponi di un prodotto a cui vuoi associare questa nuova API, assicurati di deselezionare questa casella di controllo in modo da non creare un prodotto non necessario. Per informazioni sui prodotti, consulta Che cos'è un prodotto API?
Se devi abilitare la verifica del token di accesso per il proxy API già esistente, è sufficiente collegare un criterio di tipo OAuthV2 all'API che vuoi proteggere. I criteri OAuthV2 funzionano specificando un'operazione. Se vuoi convalidare i token di accesso, devi specificare l'operazione denominata VerifyAccessToken. (Altri tipi di operazioni supportati dal tipo di criterio OAuthV2 sono GeneraAccessToken e generaterefreshToken. Scoprirai di più su queste operazioni quando configuri gli endpoint OAuth.
Criterio VerificationOAuthTokens di tipo OAuthV2
Di seguito è riportato un esempio di criterio per convalidare i token di accesso. Le impostazioni sono spiegate nella tabella seguente.
<OAuthV2 name="VerifyOAuthTokens"> <Operation>VerifyAccessToken</Operation> </OAuthV2>
Impostazioni criteri
| Nome | Descrizione | Predefinito | Campo obbligatorio? |
|---|---|---|---|
OAuthV2 |
Il tipo di criterio | ||
name |
Il nome del criterio a cui viene fatto riferimento nella configurazione dell'endpoint del proxy API. | N/A | Sì |
Operation |
L'operazione da eseguire dal criterio OAuthV2. Specificando VerificationAccessToken, si configura il criterio per controllare le richieste di token di accesso e per verificare che il token di accesso sia valido, che non sia scaduto e che sia approvato per utilizzare la risorsa API (URI) richiesta. Per eseguire questo controllo, il criterio legge il prodotto API che l'app può utilizzare. | N/A | Sì |
Per creare questo criterio nell'interfaccia utente di gestione, vai ad API > Proxy API.
Dall'elenco dei proxy API, seleziona weatherapi.
Nella Panoramica di weatherapi, seleziona la visualizzazione Sviluppo.
Dal menu a discesa, seleziona Nuovo criterio > OAuth v2.0
Dopo aver selezionato il criterio OAuth 2.0, viene visualizzato il menu di configurazione New Policy (Nuovo criterio).
Assegna al criterio un nome descrittivo e assicurati di selezionare Allega criterio, Preflusso del flusso e Richiedi come impostazioni per gli allegati del criterio.
Seleziona Aggiungi. Il criterio verrà creato e associato al PreFlow della richiesta di weatherapi.
Dopo aver aggiunto il criterio, la configurazione pre-flusso della richiesta riportata di seguito verrà visualizzata nel riquadro Designer.
Se lavori in locale in un editor di testo o IDE, devi allegare il criterio al pre-flusso della richiesta del proxy API che vuoi proteggere:
<PreFlow>
<Request>
<Step><Name>VerifyOAuthTokens</Name></Step>
</Request>
</PreFlow>
Se colleghi il criterio al preFlow della richiesta, ti assicuri che il criterio venga sempre applicato in modo forzato a tutti i messaggi di richiesta.
Ora hai protetto un'API con credenziali client OAuth 2.0. Il passaggio successivo consiste nell'imparare come ottenere un token di accesso e utilizzarlo per accedere all'API sicura.
Utilizzo di un token di accesso per accedere a una risorsa protetta
Ora che la weatherapi è protetta con OAuth 2.0, le app devono presentare token di accesso per utilizzare l'API. Per accedere a una risorsa protetta, l'app presenta un token di accesso nella richiesta sotto forma di intestazione HTTP "Authorization", come segue:
$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282
Poiché all'API è associato un criterio OAuthV2, Apigee Edge verificherà che il token di accesso presentato sia valido, quindi concederà l'accesso all'API, restituendo il bollettino meteo all'app che ha effettuato la richiesta.
Ma come fanno le app a ottenere i token di accesso? Ne parleremo nella prossima sezione.
Come scambiare le credenziali client per un token di accesso
Le app ricevono i token di accesso presentando le loro coppie chiave/segreto utente all'endpoint token. L'endpoint del token è configurato nel proxy API chiamato oauth. Le app devono quindi chiamare l'API esposta dal proxy API oauth per ottenere un token di accesso. Dopo che l'app dispone di un token di accesso, può chiamare più volte la weatherapi, finché il token di accesso non scade o il token di accesso viene revocato.
Ora devi cambiare modalità per pensare a te stesso come a uno sviluppatore di app. Vuoi chiamare la weatherapi, quindi devi ottenere un token di accesso per la tua app. La prima cosa da fare è una coppia chiave e secret utente (nota anche come chiave API o chiave app).
Puoi ottenere una chiave e un secret consumer registrando un'app nella tua organizzazione su Apigee Edge.
Puoi visualizzare tutte le app della tua organizzazione nell'interfaccia utente di gestione di Apigee Edge.
Verrà visualizzato l'elenco delle app registrate nella tua organizzazione.
Se non viene visualizzata alcuna app, puoi scoprire come registrarla nell'argomento Registrare app e gestire le chiavi API.
Seleziona un'app dall'elenco per visualizzarne il profilo dettagliato.
Nella visualizzazione dettagliata dell'app selezionata, osserva i campi Chiave utente e Segreto utente. Questi due valori corrispondono alle credenziali client che utilizzerai per ottenere un token di accesso OAuth.
$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps \
-u myname:mypass
Questa chiamata restituisce un elenco di app in base all'ID.
[ "da496fae-2a04-4a5c-b2d0-709278a6f9db", "50e3e831-175b-4a05-8fb6-05a54701af6e" ]
Puoi recuperare il profilo di un'app effettuando una semplice chiamata GET sull'ID dell'app:
$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/{app_id} \
-u myname:mypass
Ad esempio:
$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/da496fae-2a04-4a5c-b2d0-709278a6f9db \
-u myname:mypass
La chiamata API restituisce il profilo dell'app specificata. Ad esempio, un profilo dell'app per weatherapp ha la seguente rappresentazione JSON:
{
"accessType" : "read",
"apiProducts" : [ ],
"appFamily" : "default",
"appId" : "da496fae-2a04-4a5c-b2d0-709278a6f9db",
"attributes" : [ ],
"callbackUrl" : "http://weatherapp.com",
"createdAt" : 1380290158713,
"createdBy" : "noreply_admin@apigee.com",
"credentials" : [ {
"apiProducts" : [ {
"apiproduct" : "PremiumWeatherAPI",
"status" : "approved"
} ],
"attributes" : [ ],
"consumerKey" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
"consumerSecret" : "hAr4Gn0gA9vAyvI4",
"expiresAt" : -1,
"issuedAt" : 1380290161417,
"scopes" : [ ],
"status" : "approved"
} ],
"developerId" : "5w95xGkpnjzJDBT4",
"lastModifiedAt" : 1380290158713,
"lastModifiedBy" : "noreply_admin@apigee.com",
"name" : "weatherapp",
"scopes" : [ ],
"status" : "approved"
}
Prendi nota dei valori di consumerKey e consumerSecret. Puoi utilizzare queste credenziali per ottenere un token di accesso presentandole come credenziali di autenticazione di base in una richiesta HTTP, come mostrato di seguito. Il tipo di autorizzazione viene presentato come parametro di ricerca della richiesta.
Assicurati di modificare il valore della variabile {org_name} per riflettere il nome della tua organizzazione su Apigee Edge.
Crea una richiesta per ottenere un token di accesso
Nella richiesta seguente, sostituisci il valore di consumerKey con client_id. Sostituisci il valore dell'elemento consumerSecret associato con
client_secret.
$ curl https://{org_name}-test.apigee.net/oauth/client_credential/accesstoken?grant_type=client_credentials -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'
I servizi API verifica la chiave e il secret dell'utente, quindi genera una risposta contenente il token di accesso per questa app:
{
"issued_at" : "1380892555397",
"application_name" : "957aa73f-25c2-4ead-8021-adc01f0d2c6b",
"scope" : "",
"status" : "approved",
"api_product_list" : "[oauth-test]",
"expires_in" : "3599",
"developer.email" : "tesla@weathersample.com",
"organization_id" : "0",
"client_id" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
"access_token" : "ylSkZIjbdWybfs4fUQe9BqP0LH5Z",
"organization_name" : "rqa",
"refresh_token_expires_in" : "0",
"refresh_count" : "0"
}
Prendi nota del valore access_token nella risposta in alto. Si tratta del token di accesso che l'app utilizzerà per ottenere l'accesso di runtime alle risorse protette. Il token di accesso per questa app è
ylSkZIjbdWybfs4fUQe9BqP0LH5Z.
Ora disponi di un token di accesso valido, ylSkZIjbdWybfs4fUQe9BqP0LH5Z, che può essere utilizzato per accedere alle API protette.
Utilizzare la configurazione OAuth predefinita
Il provisioning di ogni organizzazione (anche di un'organizzazione di prova senza costi) su Apigee Edge viene eseguito con un endpoint del token OAuth. L'endpoint è preconfigurato con i criteri nel proxy API chiamato oauth. Puoi iniziare a utilizzare l'endpoint del token non appena crei un account su Apigee Edge.
L'endpoint OAuth predefinito espone il seguente URI dell'endpoint:
/oauth/client_credential/accesstoken
Pubblica questo URI per gli sviluppatori che devono ottenere token di accesso. Gli sviluppatori di app configurano le proprie app in modo che chiamino questo endpoint, presentando le loro coppie chiave utente e secret per ottenere i token di accesso.
L'endpoint del token delle credenziali client predefinito è esposto sulla rete al seguente URL:
https://{org_name}-{env_name}.apigee.net/oauth/client_credential/accesstoken
Ad esempio, se il nome della tua organizzazione è "apimakers", l'URL sarà:
https://apimakers-test.apigee.net/oauth/client_credential/accesstoken
Si tratta dell'URL chiamato dagli sviluppatori per ottenere i token di accesso.
Configurazioni OAuth a tre vie
Le configurazioni OAuth a tre vie (tipi di autorizzazione, implicito e della password) richiedono che il provider dell'API autentichi gli utenti finali dell'app. Poiché ogni organizzazione autentica gli utenti in modi diversi, per integrare OAuth con l'archivio utenti è necessario un codice o una personalizzazione dei criteri. Ad esempio, tutti gli utenti potrebbero essere archiviati in Active Directory, in un LDAP o in un altro archivio utenti. Per attivare OAuth a tre vie, devi integrare un controllo relativo a questo archivio utente nel flusso OAuth generale.
OAuth 1.0a
Per maggiori dettagli sul criterio OAuth 1.0a, vedi Criterio OAuth 1.0a.
Ricevere assistenza
Se hai bisogno di aiuto, consulta il sito dell'assistenza clienti di Apigee.