Utilizzo degli ambiti OAuth2

Questa pagina si applica a Apigee e Apigee ibridi.

Visualizza documentazione di Apigee Edge.

Questo argomento illustra come utilizzare e applicare gli ambiti OAuth 2.0 con Apigee.

Che cos'è l'ambito OAuth2?

Gli ambiti OAuth 2.0 consentono di limitare la quantità di accessi che viene concesso a un tipo di accesso di accesso. Ad esempio, un token di accesso emesso per un'app client può ottenere l'accesso in lettura e in scrittura alle risorse protette o semplicemente l'accesso in READ. Puoi implementare le API per applicare qualsiasi ambito la combinazione di ambiti desiderata. Quindi, se un client riceve un token con ambito READ e tenta di chiamare un endpoint API che richiede l'accesso in scrittura, la chiamata non andrà a buon fine.

In questo argomento parleremo di come vengono assegnati gli ambiti ai token di accesso e di come Apigee applica gli ambiti OAuth 2.0. Dopo aver letto questo argomento, potrai utilizzare gli ambiti con sicurezza.

Come vengono assegnati gli ambiti ai token di accesso?

Quando Apigee genera un token di accesso, può assegnare un ambito a quel token. Per comprendere il in questo caso, devi prima conoscere le seguenti entità Apigee: prodotti API, sviluppatori e app per sviluppatori. Per un'introduzione, consulta Introduzione alla pubblicazione. I nostri suggerimenti di rivedere questo materiale, se necessario, prima di continuare.

Un token di accesso è una lunga stringa di caratteri casuali che permette ad Apigee di verificare le richieste API in entrata (pensate a questa soluzione come un sostituto credenziali nome utente/password). Tecnicamente, il token è una chiave che si riferisce a una raccolta di con metadati che assomigliano a questo:

{
  "issued_at" : "1416962591727",
  "application_name" : "0d3e1d41-a59f-4d74-957e-d4e3275d4781",
  "scope" : "A",
  "status" : "approved",
  "api_product_list" : "[scopecheck1-bs0cSuqS9y]",
  "expires_in" : "1799", //--in seconds
  "developer.email" : "[e-mail]",
  "organization_id" : "0",
  "token_type" : "BearerToken",
  "client_id" : "eTtB7w5lvk3DnOZNGReBlvGvIAeAywun",
  "access_token" : "ODm47ris5AlEty8TDc1itwYPe5MW",
  "organization_name" : "wwitman",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

I metadati del token includono la stringa del token di accesso effettiva, le informazioni sulla scadenza, identificazione dell'app dello sviluppatore, dello sviluppatore e dei prodotti associati al token. Dovrai noterai anche che i metadati includono anche "scope".

In che modo il token ottiene l'ambito?

La prima chiave per comprendere l'ambito è ricordare che ogni prodotto di un'app per sviluppatori può non hanno più ambiti assegnati. Questi ambiti possono essere assegnati quando il prodotto oppure possono essere aggiunti in un secondo momento. Esistono come elenco di nomi e sono inclusi nel "metadata" associati a ciascun prodotto.

Best practice:

Puoi assegnare ai tuoi ambiti il nome che preferisci. Nei casi semplici, è corretto usare semplici come READ, WRITE o DELETE. In scenari più complessi in cui sono presenti più API, ognuno con più risorse che supportano molteplici azioni distinte, SCRITTURA in una risorsa non equivale a scrivere in un'altra risorsa. In questi casi, la best practice prevede di assegnare a ogni ambito un nome univoco, sotto forma di URN. Esempi di URN includono: https://www.examplecompany.com/private_catalog.readonly e urn:examplecompany:product_price:update.

Scopri di più sugli URN in RFC3986.

Quando crei un'app per sviluppatori e vi aggiungi prodotti, Apigee esamina tutti i prodotti in l'app per sviluppatori e crea un elenco di tutti gli ambiti per quei prodotti (la rete principale l'elenco di ambiti globali: una combinazione di tutti gli ambiti riconosciuti).

Nota: esiste un caso in cui l'elenco principale viene sostituito. È è possibile creare un'app sviluppatore utilizzando l'API Apigee. Utilizzando l'API, puoi specificare OAuth ambiti per l'app. Gli ambiti specifici dell'app sostituiscono l'elenco principale degli ambiti presi dalla i prodotti inclusi nell'app. Per informazioni sull'API, consulta la sezione Creare Developer App. Tieni presente che la UI di Apigee non ti consente di specificare ambiti specifici delle app. È possibile solo se utilizzi l'API per creare un'app.

Quando un'app client richiede un token di accesso ad Apigee, può facoltativamente specificare quale gli ambiti che desidera associare al token. Ad esempio, la seguente richiesta chiede per l'ambito "A". In altre parole, il client chiede che il server di autorizzazione (Apigee) generi un token di accesso con ambito "A" (autorizzando l'app a chiamare le API con ambito "A"). L'app invia una richiesta POST come questa:

curl -i -X POST -H Authorization: Basic Mg12YTk2UkEIyIBCrtro1QpIG \
  -H content-type:application/x-www-form-urlencoded \
  https://apitest.acme.com/oauth/token?grant_type=client_credentials&scope=A

Che cosa succede?

Quando Apigee riceve questa richiesta sa quale app lo sta facendo e sa quale l'app sviluppatore registrata dal client (l'ID client e le chiavi client secret sono codificati nel intestazione autenticazione di base). Poiché è incluso il parametro di query scope, Apigee deve decide se uno dei prodotti API associati all'app dello sviluppatore ha l'ambito "A". Se sì, viene generato un token di accesso con l'ambito "A". Un altro modo per interpretare questa situazione è che l'ambito parametro di query è un tipo di filtro. Se l'app sviluppatore riconosce gli ambiti "A, B, X" e il parametro di query specifica "scope=X Y Z", quindi solo l'ambito "X" verranno assegnati di accesso.

Nota:

• Se il valore del parametro di ambito corrisponde a nessuno dei valori riconosciuti ambiti, viene comunque generato un token; ma al token non verranno assegnati ambiti (i metadati dell'ambito saranno vuoti).
• Sono consentiti solo gli ambiti specificati nei prodotti. Se non vengono specificati ambiti in nessuna dei prodotti associati a un'app sviluppatore, non puoi generare un token contiene un ambito semplicemente richiedendolo nella chiamata per generare il token. Puoi solo generare un token con uno o più ambiti se l'app sviluppatore pertinente include prodotti che specificano l'ambito o gli ambiti richiesti.

Che cosa succede se il client non collega un parametro di ambito? In questo caso, Apigee genera un token che includa tutti gli ambiti riconosciuti dall'app sviluppatore. È è importante capire che il comportamento predefinito prevede la restituzione di un token di accesso che contenga unione di tutti gli ambiti per tutti i prodotti inclusi nell'app per sviluppatori.

Se nessuno dei prodotti associati a un'app dello sviluppatore specifica ambiti e un token ha un ambito, le chiamate effettuate con quel token non andranno a buon fine.

Supponiamo che un'app sviluppatore riconosca questi ambiti: A B C D. Questo è l'elenco principale dell'app ambiti. È possibile che un prodotto nell'app abbia gli ambiti A e B e un secondo con l'ambito C e D o una qualsiasi combinazione. Se il client non specifica un parametro scope (o se specifica il parametro di ambito senza alcun valore), al token verranno concessi tutti e quattro gli ambiti: e D. Anche in questo caso, il token riceve un insieme di ambiti che rappresentano l'unione di tutti gli ambiti riconosciuti dall'app sviluppatore.

C'è un altro caso in cui il comportamento predefinito è restituire un token di accesso con tutte le riconosciuti, ovvero quando viene usato il criterio GeneraAccessToken (il criterio Apigee che genera token di accesso) non specifica un elemento <Scope>. Ad esempio, ecco un criterio CreateAccessToken in cui <Scope> è specificato. Se l'elemento <Scope> non è presente (o se è presente ma vuoto), viene eseguito il comportamento predefinito.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-GenerateAccessToken">
    <DisplayName>OAuthV2 - Generate Access Token</DisplayName>
    <Attributes>
      <Attribute name='hello' ref='system.time' display='false'>value1</Attribute>
    </Attributes>
    <Scope>request.queryparam.scope</Scope> 
    <GrantType>request.formparam.grant_type</GrantType>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>GenerateAccessToken</Operation>
    <SupportedGrantTypes>
      <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
</OAuthV2>

Come vengono applicati gli ambiti?

Innanzitutto, ricorda che su Apigee, i token di accesso vengono convalidati con il criterio OAuthV2 (in genere all'inizio di un flusso proxy). Il criterio deve avere il parametro Operazione VerifyAccessToken specificata. Esaminiamo queste norme:

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope> <!-- Optional: space-separated list of scope names. -->
    <GenerateResponse enabled="true"/>
</OAuthV2>

Osserva l'elemento <Scope>. È utilizzato per specificare gli ambiti in cui il criterio accetterà.

Nota: se viene specificato più di un ambito (ad esempio, <Scope>A B C</Scope>), il criterio avrà esito positivo se il token di accesso include uno di questi (come una valutazione logica "OR"). Se vuoi applicare una richiesta "AND" di operazione, in cui sono applicati più ambiti su un token, è possibile farlo creando più VeryifyAccessToken norme, ciascuna con un singolo ambito distinto.

In questo esempio, il criterio avrà esito positivo solo se il token di accesso include l'ambito "A". Se questo &lt;Scope&gt; viene omesso o se non ha un valore, il criterio ignora l'ambito token di accesso.

Ora, con la possibilità di convalidare i token di accesso in base all'ambito, puoi progettare le tue API applicare ambiti specifici. Per farlo, progetta flussi personalizzati con VerifyAccessToken con rilevamento dell'ambito i criteri associati.

Supponiamo che la tua API abbia un flusso definito per l'endpoint /resourceA:

<Flow name="resourceA">
            <Condition>(proxy.pathsuffix MatchesPath "/resourceA") and (request.verb = "GET")</Condition>
            <Description>Get a resource A</Description>
            <Request>
                <Step>
                    <Name>OAuthV2-VerifyAccessTokenA</Name>
                </Step>
            </Request>
            <Response>
                <Step>
                    <Name>AssignMessage-CreateResponse</Name>
                </Step>
            </Response>
        </Flow>

Quando viene attivato questo flusso (riceve una richiesta con /resourceA nel percorso ), il criterio OAuthV2-VerifyAccessTokenA viene chiamato immediatamente. Questo criterio verifica che il token di accesso sia valido e controlla gli ambiti supportati. Se il criterio è configurato come nell'esempio riportato di seguito, con <Scope>A</Scope>, il criterio avrà esito positivo solo se il token di accesso ha l'ambito "A". In caso contrario, verrà restituito un errore.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Per riepilogare, gli sviluppatori di API sono responsabili della progettazione dell'applicazione forzata dell'ambito nelle loro API. Per farlo, crea flussi personalizzati per gestire ambiti specifici e collega VerifyAccessToken per applicare questi ambiti.

Esempi di codice

Infine, diamo un'occhiata ad alcune chiamate API di esempio per illustrare come i token ricevono gli ambiti e le modalità di applicazione degli ambiti.

Maiuscole predefinite

Supponiamo che tu abbia un'app per sviluppatori con prodotti e che la loro unione ambiti sono: A, B e C. Questa chiamata API richiede un token di accesso, ma non specifica una query sull'ambito .

curl -X POST -H content-type:application/x-www-form-urlencoded \
  https://apitest.acme.com/scopecheck1/token?grant_type=client_credentials

In questo caso, al token generato verranno assegnati gli ambiti A, B e C (comportamento predefinito). La i metadati del token potrebbero avere il seguente aspetto:

{
  "issued_at" : "1417016208588",
  "application_name" : "eb1a0333-5775-4116-9eb2-c36075ddc360",
  "scope" : "A B C",
  "status" : "approved",
  "api_product_list" : "[scopecheck1-yEgQbQqjRR]",
  "expires_in" : "1799", //--in seconds
  "developer.email" : "[e-mail]",
  "organization_id" : "0",
  "token_type" : "BearerToken",
  "client_id" : "atGFvl3jgA0pJd05rXKHeNAC69naDmpW",
  "access_token" : "MveXpj4UYXol38thNoJYIa8fBGlI",
  "organization_name" : "wwitman",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

Ora, supponiamo che tu abbia un endpoint API con ambito "A" (VerificaAccessToken) richiede l'ambito "A"). Ecco le norme VerifyAccessToken:

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Ecco un esempio di chiamata a e endpoint che applica l'ambito A:

curl -X GET -H Authorization: Bearer MveXpj4UYXol38thNoJYIa8fBGlI \
  https://apitest.acme.com/scopecheck1/resourceA

Questa chiamata GET ha esito positivo:

 {
   "hello" : "Tue, 25 Nov 2014 01:35:53 UTC"
 }

L'operazione riesce perché il criterio VerifyAccessToken viene attivato quando l'endpoint viene chiamato richiede l'ambito A e al token di accesso sono stati concessi gli ambiti A, B e C. L'impostazione predefinita comportamento degli utenti.

Custodia con filtro

Supponiamo che tu abbia un'app sviluppatore con prodotti con ambiti A, B, C e X. Hai richiesto un token di accesso e includi il parametro di query scope, in questo modo:

curl -i -X POST -H content-type:application/x-www-form-urlencoded \
  'https://apitest.acme.com/oauth/token?grant_type=client_credentials&scope=A X'

In questo caso, al token generato verranno assegnati gli ambiti A e X, perché sia A che X sono un validi. Ricorda che l'app sviluppatore riconosce gli ambiti A, B, C e X. In questo caso, si sta filtrando l'elenco dei prodotti API in base a questi ambiti. Se un prodotto ha l'ambito A o X, puoi configurare gli endpoint API che applicheranno questi ambiti. Se un prodotto non rientra nell'ambito A o X (supponiamo che abbia B, C e Z), quindi le API che applicano gli ambiti A o X non possono essere chiamate con il token.

Quando chiami l'API con il nuovo token:

curl -X GET -H Authorization: Bearer Rkmqo2UkEIyIBCrtro1QpIG \
  https://apitest.acme.com/scopecheck1/resourceX

Il token di accesso viene convalidato dal proxy API. Ad esempio:

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenX">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A X</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

L'attivatore di chiamata GET riesce e restituisce una risposta. Ad esempio:

 {
   "hello" : "Tue, 25 Nov 2014 01:35:53 UTC"
 }
 

Ha esito positivo perché il criterio VerifyAccessToken richiede l'ambito A o X e il token di accesso include gli ambiti A e X. Naturalmente, se l'elemento <Scope> fosse impostato su "B", la chiamata non andrebbe a buon fine.

Riepilogo

È importante capire in che modo Apigee gestisce gli ambiti OAuth 2.0. Ecco il concetto chiave punti:

• Un'app sviluppatore "riconosce" dall'unione di tutti gli ambiti definiti per tutti i suoi prodotti.
• Quando un'app richiede un token di accesso, ha la possibilità di specificare gli ambiti che che vorrebbero avere. Spetta ad Apigee (il server di autorizzazione) individuare gli ambiti assegnerà effettivamente il token di accesso in base a (a) l'ambito o gli ambiti richiesti e (b) quelli riconosciuti dall'app sviluppatore.
• Se Apigee non è configurato per verificare l'ambito (l'elemento <Scope> non è presente nel criterio VerifyAccessToken o è vuoto), la chiamata API avrà esito positivo purché l'ambito incorporato nel token di accesso corrisponda a uno degli ambiti riconosciuti dal app sviluppatore registrata (uno degli ambiti nell'elenco di ambiti "principale" dell'app).
• Se a un token di accesso non sono associati ambiti, l'operazione riuscirà nei casi in cui Apigee non considera l'ambito (l'elemento <Scope> non è presente dal criterio VerifyAccessToken o è vuoto).