OAuth

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

OAuth è diventato il protocollo di autorizzazione principale per le API. La versione di OAuth trattata 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 lo fanno ottenendo token di accesso dai provider di API. Il provider di API autentica le credenziali dell'utente finale dell'app , si assicura che l'utente abbia autorizzato l'app e poi rilascia un token di accesso all'app. Quando l'app utilizza un'API protetta, Apigee Edge controlla il token di accesso per assicurarsi che sia valido e che non sia scaduto. In qualità di provider di API, devi esporre gli endpoint che consentono alle app di ottenere token di accesso.

Per semplificare l'utilizzo di OAuth, Apigee Edge ti consente di configurare e applicare OAuth utilizzando criteri, senza dover scrivere codice. In questo argomento imparerai a proteggere le tue API, a ottenere token di accesso e a utilizzarli per accedere alle API protette.

La configurazione OAuth predefinita per la tua organizzazione

Per comodità, tutte le organizzazioni su Apigee Edge sono preconfigurate con un insieme 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 di chiave utente e secret che Apigee Edge rilascia per ogni app registrata in un'organizzazione. "Credenziali client" si riferisce alla coppia chiave-secret stessa.

Per saperne di più sull'emissione di credenziali per le app utilizzando i servizi per sviluppatori Edge, consulta Registrare le app e gestire le chiavi.

Per questo motivo, è relativamente semplice "migliorare" lo schema di sicurezza delle 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 dover revocare la chiave utente dell'app. Per utilizzare gli endpoint OAuth predefiniti, puoi utilizzare qualsiasi chiave utente e secret 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à chiavi utente e secret.)

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 tue API per convalidare i token di accesso OAuth in fase di runtime. Per farlo, configura un proxy API per convalidare i token di accesso. Ciò significa che ogni volta che un'app effettua una richiesta per utilizzare una delle tue API, deve presentare un token di accesso valido insieme alla richiesta API. Apigee Edge gestisce la complessità 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 token di accesso OAuth v2.0. Quando selezioni questa opzione, al proxy API appena creato vengono collegati 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 selezionata. Seleziona questa opzione se vuoi generare automaticamente un prodotto quando crei il nuovo proxy API proxy. Il prodotto generato automaticamente verrà creato con un'associazione al nuovo proxy API. Se hai un prodotto esistente 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 un proxy API già esistente, devi solo 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, specifica l'operazione denominata VerifyAccessToken. (Altri tipi di operazioni supportati dal tipo di policy OAuthV2 sono GenerateAccessToken e GenerateRefreshToken. Scoprirai di più su queste operazioni quando configurerai gli endpoint OAuth.)

Criterio VerifyOAuthTokens policy di tipo OAuthV2

Un esempio di criterio per convalidare i token di accesso è il seguente. (Le impostazioni sono spiegate nella tabella di seguito.)

<OAuthV2 name="VerifyOAuthTokens">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

Impostazioni criteri

Per creare questo criterio nell'interfaccia utente di gestione, vai a API > Proxy API.

Nell'elenco dei proxy API, seleziona weatherapi.

Nella panoramica di weatherapi, seleziona la visualizzazione Sviluppa.

Dal menu a discesa, seleziona Nuovo criterio > OAuth v2.0.

Dopo aver selezionato il criterio OAuth v2.0, viene visualizzato il menu di configurazione Nuovo criterio.

Assegna al criterio un nome descrittivo e assicurati di selezionare Collega criterio, PreFlow e Richiesta come impostazioni di collegamento del criterio.

Seleziona Aggiungi e il criterio viene creato e collegato al PreFlow della richiesta di weatherapi.

Dopo aver aggiunto il criterio, nella finestra Progettazione viene visualizzata la configurazione del PreFlow della richiesta riportata di seguito.

Se lavori localmente in un editor di testo o in un IDE, collega il criterio al PreFlow 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 a tutti i messaggi di richiesta.

Ora hai protetto un'API con le credenziali client OAuth 2.0. Il passaggio successivo consiste nell'imparare a ottenere un token di accesso e a utilizzarlo per accedere all'API protetta.

Utilizzare un token di accesso per accedere a una risorsa protetta

Ora che weatherapi è protetta con OAuth 2.0, le app devono presentare i token di accesso per utilizzare l'API. Per accedere a una risorsa protetta, l'app presenta un token di accesso nella richiesta come "Authorization" intestazione HTTP nel seguente modo:

$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

Poiché all'API è collegato un criterio OAuthV2, Apigee Edge verifica che il token di accesso presentato sia valido e poi concede l'accesso all'API, restituendo il bollettino meteorologico all'app che ha effettuato la richiesta.

Ma come fanno le app a ottenere i token di accesso? Lo vedremo nella sezione successiva.

Come scambiare le credenziali client con un token di accesso

Le app ottengono i token di accesso presentando le coppie di chiave utente/secret all'endpoint del token. L'endpoint del token è configurato nel proxy API denominato oauth. Pertanto, le app devono chiamare l'API esposta dal oauth API proxy per ottenere un token di accesso. Dopo che l'app ha un token di accesso, può chiamare weatherapi ripetutamente, finché il token di accesso non scade o non viene revocato.

Ora devi cambiare prospettiva e pensare a te stesso come a uno sviluppatore di app. Vuoi chiamare the weatherapi, quindi devi ottenere un token di accesso per la tua app. La prima cosa da fare è ottenere una coppia di chiave utente e secret (nota anche come chiave API o chiave app).

Puoi ottenere una chiave utente e un secret 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 management UI.

Viene visualizzato l'elenco delle app registrate nella tua organizzazione.

(Se non vengono visualizzate app, puoi scoprire come registrarne una nell'argomento chiamato Registrare le app e gestire le chiavi API chiavi.)

Seleziona un'app dall'elenco per visualizzarne il profilo dettagliato.

Nella visualizzazione dei dettagli dell'app selezionata, prendi nota dei campi Chiave utente e Secret utente. Questi due valori sono le 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 per ID app.

[ "da496fae-2a04-4a5c-b2d0-709278a6f9db", "50e3e831-175b-4a05-8fb6-05a54701af6e" ]

Puoi recuperare il profilo di un'app effettuando una semplice chiamata GET sull'ID 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 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. Utilizza 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 concessione viene presentato come parametro di query alla richiesta. Assicurati di modificare il valore della variabile {org_name} in modo che rifletta il nome della tua organizzazione su Apigee Edge.

Creare una richiesta per ottenere un token di accesso

Nella richiesta seguente, sostituisci il valore di consumerKey con client_id. Sostituisci il valore di 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 verificano la chiave utente e il secret, quindi generano 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 sopra. Questo è il token di accesso che l'app utilizzerà per ottenere l'accesso in fase di runtime alle risorse protette. Il token di accesso per questa app è ylSkZIjbdWybfs4fUQe9BqP0LH5Z.

Ora hai un token di accesso valido, ylSkZIjbdWybfs4fUQe9BqP0LH5Z, che può essere utilizzato per accedere alle API protette.

Utilizzare la configurazione OAuth predefinita

Ogni organizzazione (anche un'organizzazione di prova senza costi) su Apigee Edge viene sottoposta a provisioning con un endpoint del token OAuth. L'endpoint è preconfigurato con i criteri nel proxy API denominato 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 i token di accesso. Gli sviluppatori di app configurano le loro app per chiamare questo endpoint, presentando le coppie di chiave utente e secret per ottenere i token di accesso.

L'endpoint del token delle credenziali client predefinito viene 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

Questo è l'URL che gli sviluppatori chiamano per ottenere i token di accesso.

Configurazioni OAuth a tre vie

Le configurazioni OAuth a tre vie (tipi di concessione del codice di autorizzazione, implicito e password) richiedono che tu, il provider di API, autentichi gli utenti finali dell'app. Poiché ogni organizzazione autentica gli utenti in modi diversi, è necessaria una personalizzazione dei criteri o del codice per integrare OAuth con l'archivio utenti. Ad esempio, tutti i tuoi utenti potrebbero essere archiviati in Active Directory, in un LDAP o in un altro archivio utenti. Per configurare e utilizzare OAuth a tre vie, devi integrare un controllo su questo archivio utenti nel flusso OAuth complessivo.

OAuth 1.0a

Per informazioni dettagliate sul criterio OAuth 1.0a, consulta Criterio OAuth v1.0a.

Richiedi assistenza

Per assistenza, consulta l'assistenza clienti di Apigee.