Criterio OAuthV2

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

OAuthV2 è una policy sfaccettata per l'esecuzione di operazioni di tipo di concessione OAuth 2.0. Questo è il criterio principale utilizzato per configurare gli endpoint OAuth 2.0 su Apigee.

Queste norme sono estendibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di policy e sulle implicazioni di utilizzo, consulta Tipi di policy.

Per scoprire di più su OAuth su Apigee, consulta la home page di OAuth. Fornisce link a risorse, esempi, video e altro ancora.

Campioni

VerifyAccessToken

VerifyAccessToken

Questa configurazione della policy OAuthV2 (con l'operazione VerifyAccessToken) verifica che un token di accesso inviato ad Apigee sia valido. Quando viene attivata questa operazione del criterio, Apigee cerca un token di accesso valido nella richiesta. Se il token di accesso è valido, la richiesta può procedere. Se non è valido, tutta l'elaborazione si interrompe e nella risposta viene restituito un errore. 

<OAuthV2 name="OAuthV2-Verify-Access-Token">
    <Operation>VerifyAccessToken</Operation>
</OAuthV2>

Un'applicazione client deve inviare una richiesta con un token. Ad esempio, utilizzando curl potrebbe essere:

$ curl https://API_ENDPOINT/weather/forecastrss?w=12797282 \
  -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z"

Dove API_ENDPOINT è il dominio utilizzato per accedere alle tue API, come configurato nel tuo sistema Apigee.

Per impostazione predefinita, il criterio OAuthV2 estrae il token di accesso dall'intestazione Authorization, rimuovendo il prefisso Bearer. Puoi modificare questo comportamento predefinito con l'elemento di configurazione AccessToken.

GenerateAccessToken

Generazione di token di accesso

Per esempi che mostrano come richiedere token di accesso per ciascuno dei tipi di concessione supportati, vedi Ottenere token OAuth 2.0. L'argomento include esempi di queste operazioni:

GenerateAuthorizationCode

Generare il codice di autorizzazione

Per esempi che mostrano come richiedere i codici di autorizzazione, consulta Richiesta di un codice di autorizzazione.

RefreshAccessToken

Aggiornare un token di accesso

Per esempi che mostrano come richiedere token di accesso utilizzando un token di aggiornamento, vedi Aggiornamento di un token di accesso.

Token di accesso JWT

Token di accesso JWT

Per esempi che mostrano come generare, verificare e aggiornare i token di accesso JWT, vedi Utilizzo dei token di accesso JWT.

Token del flusso di risposta

Generare un token di accesso nel flusso di risposta

A volte potrebbe essere necessario generare un token di accesso nel flusso di risposta. Ad esempio, puoi eseguire questa operazione in risposta a una convalida personalizzata eseguita in un servizio di backend. In questo esempio, il caso d'uso richiede sia un token di accesso sia un token di aggiornamento, escludendo il tipo di concessione implicita. In questo caso, utilizzeremo il tipo di autorizzazione password per generare il token. Come vedrai, il trucco per far funzionare il tutto è passare un'intestazione della richiesta di autorizzazione con un criterio JavaScript.

Innanzitutto, esaminiamo il criterio di esempio:

<OAuthV2 enabled="true" continueOnError="false" async="false" name="generateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <AppEndUser>Doe</AppEndUser>
    <UserName>jdoe</UserName>
    <PassWord>jdoe</PassWord>
    <GrantType>grant_type</GrantType>
    <ClientId>a_valid_client_id</ClientId>
    <SupportedGrantTypes>
        <GrantType>password</GrantType>
    </SupportedGrantTypes>
</OAuthV2>

Se inserisci questa norma nel flusso di risposta, si verificherà un errore 401 UnAuthorized anche se i parametri di accesso corretti sono specificati nella norma. Per risolvere questo problema, devi impostare un'intestazione della richiesta di autorizzazione.

L'intestazione Authorization deve contenere uno schema di accesso Basic con client_id:client_secret codificato in Base64.

Puoi aggiungere questa intestazione con una norma JavaScript posizionata appena prima della norma OAuthV2, in questo modo. Le variabili di contesto "local_clientid" e "local_secret" devono essere impostate in precedenza e disponibili nel flusso:

var clientId = context.getVariable("local_clientid");
var clientSecret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+ CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(clientId + ':' + clientSecret)));

Vedi anche Codifica delle credenziali di autenticazione di base.

Riferimento elemento

Il riferimento ai criteri descrive gli elementi e gli attributi dei criteri OAuthV2.

La policy di esempio mostrata di seguito è una delle tante configurazioni possibili. Questo esempio mostra un criterio OAuthV2 configurato per l'operazione GenerateAccessToken. Include elementi obbligatori e facoltativi. Per i dettagli, consulta le descrizioni degli elementi in questa sezione.

<OAuthV2 name="GenerateAccessToken">
  <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
  <Operation>GenerateAccessToken</Operation>
  <!-- This is in millseconds, so expire in an hour -->
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <GenerateResponse/>
</OAuthV2>

Attributi <OAuthV2>

<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">

La tabella seguente descrive gli attributi comuni a tutti gli elementi principali dei criteri:

Attributo Descrizione Predefinito Presence
name

Il nome interno del criterio. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri.

Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

 N/D Obbligatorio
continueOnError

Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri.

Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche:

 falso Facoltativo
enabled

Imposta su true per applicare il criterio.

Imposta su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso.

 true Facoltativo
async

Questo attributo è stato ritirato.

 falso Deprecato

Elemento <DisplayName>

Da utilizzare insieme all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>
Predefinito

N/D

Se ometti questo elemento, viene utilizzato il valore dell'attributo name del criterio.
Presence Facoltativo
Tipo Stringa

Elemento <AccessToken>

<AccessToken>request.header.access_token</AccessToken>

Per impostazione predefinita, quando Operation è VerifyAccessToken, la policy prevede che il token di accesso venga inviato nell'intestazione Authorization come token di tipo bearer, ovvero con il prefisso "Bearer" seguito da uno spazio vuoto. Puoi modificare questo valore predefinito utilizzando questo elemento, specificando il nome di una variabile che contiene il token di accesso da verificare. Quando utilizzi questo elemento, il criterio per impostazione predefinita non cerca un prefisso nei contenuti della variabile. Se vuoi specificare che il criterio deve cercare un prefisso, utilizza anche l'elemento AccessTokenPrefix.

Esempi:

  • Quando la configurazione dei criteri è:

      <OAuthV2 name="OAuthV2-Verify-Access-Token-in-Header">
      <Operation>VerifyAccessToken</Operation>
      <AccessToken>request.header.access_token</AccessToken>
  </OAuthV2>

    Per passare il token utilizzando curl, puoi utilizzare:

      curl https://API_ENDPOINT/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

  • Quando la configurazione dei criteri è:

      <OAuthV2 name="OAuthV2-Verify-Access-Token-in-QueryParam">
      <Operation>VerifyAccessToken</Operation>
      <AccessToken>request.queryparam.token</AccessToken>
  </OAuthV2>

    Per passare il token utilizzando curl, puoi utilizzare:

      curl "https://API_ENDPOINT/oauth2/validate?token=Rft3dqrs56Blirls56a"

Dove API_ENDPOINT è il dominio utilizzato per accedere alle tue API, come configurato nel tuo sistema Apigee.

Predefinito

N/D

Presenza

Facoltativo
Tipo Stringa
Valori validi

qualsiasi nome di variabile
Utilizzato con le operazioni
  • VerifyAccessToken

Elemento <AccessTokenPrefix>

<AccessTokenPrefix>Prefix</AccessTokenPrefix>

Per impostazione predefinita, quando Operation è VerifyAccessToken, la policy prevede che il token di accesso venga inviato nell'intestazione Authorization come token di tipo bearer, ovvero con il prefisso "Bearer" seguito da uno spazio vuoto. Se utilizzi l'elemento AccessToken per specificare una posizione diversa per il token di accesso in entrata, puoi utilizzare anche questo elemento, AccessTokenPrefix, per specificare un prefisso diverso e non standard.

Ad esempio, se specifichi:

<OAuthV2 name="OAuthV2-Verify-Access-Token-Alternative-Header">
    <Operation>VerifyAccessToken</Operation>
    <AccessToken>request.header.token</AccessToken>
    <AccessTokenPrefix>KEY</AccessTokenPrefix>
</OAuthV2>

Il criterio estrae il token di accesso in entrata dall'intestazione della richiesta token, in questo modo: se l'intestazione inizia con la parola "KEY" seguita da uno spazio, il criterio rimuove il prefisso e lo spazio e interpreta il valore rimanente come token di accesso. Se il prefisso specificato non è presente nell'intestazione, il criterio genererà un errore.

Se specifichi l'elemento AccessToken e non specifichi l'elemento AccessTokenPrefix, la policy interpreterà l'intero valore della variabile specificata all'interno dell'elemento AccessToken come token di accesso.

Questo elemento è efficace solo se viene utilizzato anche l'elemento AccessToken.

Predefinito

-nessuno-

Presenza

Facoltativo
Tipo Stringa
Valori validi

qualsiasi stringa
Utilizzato con le operazioni
  • VerifyAccessToken

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Specifica l'algoritmo di crittografia utilizzato per firmare un token di accesso JWT. Gli algoritmi RSA (RS*) utilizzano una coppia di chiavi pubblica/segreta, mentre gli algoritmi HMAC (HS*) utilizzano un segreto condiviso. Questo elemento è obbligatorio per le operazioni GenerateJWTAccessToken, VerifyJWTAccessToken e RefreshJWTAccessToken.

Predefinito N/D
Presenza Obbligatorio quando si utilizzano le operazioni GenerateJWTAccessToken, VerifyJWTAccessToken e RefreshJWTAccessToken.
Tipo Stringa
Valori validi HS256, HS384, HS512, RS256, RS384, RS512

Elemento <AppEndUser>

<AppEndUser>request.queryparam.app_enduser</AppEndUser>

Nei casi in cui l'ID utente finale dell'app deve essere inviato al server di autorizzazione, questo elemento consente di specificare dove Apigee deve cercare l'ID utente finale. Ad esempio, potrebbe essere inviato come parametro di query o in un'intestazione HTTP.

Ad esempio, request.queryparam.app_enduser indica che AppEndUser deve essere presente come parametro di query, ad esempio ?app_enduser=ntesla@theramin.com. Per richiedere AppEndUser in un'intestazione HTTP, ad esempio, imposta questo valore su request.header.app_enduser.

Se fornisci questa impostazione, puoi includere un ID utente finale dell'app nel token di accesso. Questa funzionalità è utile se vuoi poter recuperare o revocare i token di accesso OAuth 2.0 in base all'ID utente finale. Per saperne di più, consulta Abilitare il recupero e la revoca dei token di accesso OAuth 2.0 per ID utente finale, ID app o entrambi.

Predefinito

N/D

Presenza

Facoltativo
Tipo Stringa
Valori validi

Qualsiasi variabile di flusso accessibile al criterio in fase di runtime.
Utilizzato con i tipi di concessione
  • authorization_code
  • implicito
  • password
  • client_credentials

<Attributes/Attribute>

<Attributes>
    <Attribute name="attr_name1" ref="flow.variable" display="true|false">value1</Attribute>
    <Attribute name="attr_name2" ref="flow.variable" display="true|false">value2</Attribute>
</Attributes>

Utilizza questo elemento per aggiungere attributi personalizzati a un token di accesso o a un codice di autorizzazione. Ad esempio, potresti voler incorporare un ID utente o un identificatore di sessione in un token di accesso che può essere estratto e controllato in fase di runtime.

Questo elemento ti consente di specificare un valore in una variabile di flusso o da una stringa letterale. Se specifichi sia una variabile che una stringa, viene utilizzato il valore specificato nella variabile di flusso. Se la variabile non può essere risolta, la stringa è quella predefinita.

Per saperne di più sull'utilizzo di questo elemento, vedi Personalizzazione dei token e dei codici di autorizzazione.

Visualizzazione o nascondimento degli attributi personalizzati nella risposta

Tieni presente che se imposti l'elemento GenerateResponse di questo criterio su true, nella risposta viene restituita la rappresentazione JSON completa del token, inclusi gli attributi personalizzati che hai impostato. In alcuni casi, potresti voler nascondere alcuni o tutti gli attributi personalizzati nella risposta in modo che non siano visibili alle app client.

Per impostazione predefinita, gli attributi personalizzati vengono visualizzati nella risposta. Se vuoi nasconderli, puoi impostare il parametro display su false. Ad esempio:

<Attributes>
    <Attribute name="employee_id" ref="employee.id" display="false"/>
    <Attribute name="employee_name" ref="employee.name" display="false"/>
</Attributes>

Il valore dell'attributo display non viene memorizzato. Supponiamo di generare un token di accesso con attributi personalizzati che vuoi nascondere nella risposta generata. L'impostazione display=false consente di raggiungere questo obiettivo. Tuttavia, se in un secondo momento viene generato un nuovo token di accesso utilizzando un token di aggiornamento, gli attributi personalizzati originali del token di accesso verranno visualizzati nella risposta del token di aggiornamento. Questo perché Apigee non ricorda che l'attributo display era originariamente impostato su false nella policy Genera token di accesso. L'attributo personalizzato fa semplicemente parte dei metadati del token di accesso.

Vedrai lo stesso comportamento se aggiungi attributi personalizzati a un codice di autorizzazione: quando viene generato un token di accesso utilizzando quel codice, questi attributi personalizzati verranno visualizzati nella risposta del token di accesso. Anche in questo caso, potrebbe non essere il comportamento che intendi.

Per nascondere gli attributi personalizzati in questi casi, hai a disposizione le seguenti opzioni:

  • Reimposta esplicitamente gli attributi personalizzati nella policy dei token di aggiornamento e imposta la loro visualizzazione su false. In questo caso, potrebbe essere necessario recuperare i valori personalizzati originali dal token di accesso originale utilizzando il criterio GetOAuthV2Info.
  • Utilizza un criterio JavaScript di post-elaborazione per estrarre manualmente gli attributi personalizzati che non vuoi visualizzare nella risposta.

Vedi anche Personalizzazione di token e codici di autorizzazione.

Predefinito

N/A

Presenza

Facoltativo
Valori validi
  • name - Nome dell'attributo
  • ref: il valore dell'attributo. Può provenire da una variabile di flusso.
  • display - (Facoltativo) Consente di specificare se gli attributi personalizzati vengono visualizzati nella risposta. Se true, gli attributi personalizzati vengono visualizzati nella risposta (se è attivato anche GenerateResponse). Se false, gli attributi personalizzati non sono inclusi nella risposta. Il valore predefinito è true. Consulta Visualizzare o nascondere attributi personalizzati nella risposta.
Utilizzato con i tipi di concessione
  • authorization_code
  • implicito
  • password
  • client_credentials
  • refresh_token
  • Può essere utilizzato anche con l'operazione GenerateAuthorizationCode.

Elemento <CacheExpiryInSeconds>

<CacheExpiryInSeconds ref="propertyset.settings.token-ttl">60</CacheExpiryInSeconds>

Questo elemento può essere utilizzato solo con l'operazione VerifyAccessToken. Specifica la durata (TTL) della cache dei token di accesso per la particolare esecuzione della policy. La prima volta che Apigee verifica un token di accesso OAuth 2, deve recuperarlo da un archivio permanente. Si tratta di un'operazione relativamente costosa, pertanto Apigee memorizza nella cache il risultato della ricerca del token, inclusi lo stato del token, l'elenco dei prodotti per cui il token è valido e gli eventuali attributi personalizzati allegati al token. Le invocazioni successive di OAuthV2/VerifyAccessToken fino alla scadenza del TTL leggeranno il risultato memorizzato nella cache in memoria, il che significa che la verifica del token sarà molto più veloce.

Il TTL predefinito per la cache dei token di accesso è di 180 secondi. Questo elemento ti consente di ridurre il TTL, scambiando il rendimento con la correttezza. Uno scenario in cui ciò avrebbe senso è se a volte revochi i token e vuoi ridurre la finestra temporale durante la quale Apigee continuerà a trattare i token revocati come validi.

L'intervallo supportato è compreso tra 1 e 180 secondi. Puoi fornire una variabile di flusso e un valore predefinito. Se fornisci una variabile di flusso e se contiene un valore numerico, ha la precedenza sul valore predefinito specificato.

Predefinito

 N/D

Se ometti questo elemento, il periodo di scadenza predefinito per il token di accesso memorizzato nella cache è di 180 secondi.

Presenza

 Facoltativo

Tipo

 Numero intero

Valori validi

 Qualsiasi numero intero positivo diverso da zero. Specifica il tempo di scadenza in secondi.
Utilizzato con le operazioni
  • VerifyAccessToken

Attributi

La tabella seguente descrive gli attributi dell'elemento <CacheExpiryInSeconds>.

Attributo Descrizione Predefinito Presenza
ref

Un riferimento alla variabile di flusso contenente il valore per la scadenza della cache, espresso in secondi.

Se fornito, il valore della variabile di flusso ha la precedenza sul valore predefinito specificato.

 N/D Facoltativo

Elemento <ClientId>

<ClientId>request.formparam.client_id</ClientId>

In diversi casi, l'app client deve inviare l'ID client al server di autorizzazione. Questo elemento specifica che Apigee deve cercare l'ID client nella variabile di flusso request.formparam.client_id. L'impostazione di ClientId su qualsiasi altra variabile non è supportata. Vedi anche Recuperare i token OAuth 2.0.

Predefinito

request.formparam.client_id (un x-www-form-urlencoded e specificato nel corpo della richiesta)

Presenza

Facoltativo
Tipo Stringa
Valori validi La variabile di flusso: request.formparam.client_id
Utilizzato con i tipi di concessione
  • authorization_code
  • password
  • implicito
  • client_credentials

Può essere utilizzato anche con l'operazione GenerateAuthorizationCode.

Elemento <Code>

<Code>request.queryparam.code</Code>

Nel flusso del tipo di concessione di autorizzazione, il client deve inviare un codice di autorizzazione al server di autorizzazione (Apigee). Questo elemento ti consente di specificare dove Apigee deve cercare il codice di autorizzazione. Ad esempio, può essere inviato come parametro di query, intestazione HTTP o parametro del modulo (impostazione predefinita).

La variabile request.queryparam.auth_code indica che il codice di autorizzazione deve essere presente come parametro di query, ad esempio ?auth_code=AfGlvs9. Per richiedere il codice di autorizzazione in un'intestazione HTTP, ad esempio, imposta questo valore su request.header.auth_code. Vedi anche Recuperare i token OAuth 2.0.

Predefinito

request.formparam.code (un x-www-form-urlencoded specificato nel corpo della richiesta)

Presenza

facoltativo
Tipo Stringa
Valori validi Qualsiasi variabile di flusso accessibile al criterio in fase di runtime
Utilizzato con i tipi di concessione authorization_code

Elemento <ExpiresIn>

<ExpiresIn>10000</ExpiresIn>

Applica il tempo di scadenza dei token di accesso e dei codici di autorizzazione in millisecondi. (Per i token di aggiornamento, utilizza <RefreshTokenExpiresIn>.) Il valore della scadenza è un valore generato dal sistema più il valore <ExpiresIn>. Se <ExpiresIn> non è specificato, il sistema applica un valore predefinito configurato a livello di sistema.

Il tempo di scadenza può essere impostato anche in fase di runtime utilizzando un valore predefinito hardcoded o facendo riferimento a una variabile di flusso. Ad esempio, puoi memorizzare un valore di scadenza del token in una mappa chiave-valore, recuperarlo, assegnarlo a una variabile e farvi riferimento nel criterio. Ad esempio, kvm.oauth.expires_in.

Apigee mantiene le seguenti entità nella cache per un minimo di 180 secondi dopo che le entità sono state accessibili.

  • Token di accesso OAuth. Ciò significa che l'elemento ExpiresIn nel criterio OAuth v2 non potrà far scadere un token di accesso in meno di 180 secondi.
  • Entità Key Management Service (KMS) (app, sviluppatori, prodotti API).
  • Attributi personalizzati su token OAuth ed entità KMS.

La seguente strofa specifica una variabile di flusso e anche un valore predefinito. Tieni presente che il valore della variabile di flusso ha la precedenza sul valore predefinito specificato.

<ExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</ExpiresIn>

Apigee non supporta un modo per forzare la scadenza di un token dopo la sua creazione. Se devi forzare la scadenza del token (ad esempio, in base a una condizione), una possibile soluzione è descritta in questo post della community Apigee.

Per impostazione predefinita, i token di accesso scaduti vengono eliminati dal sistema Apigee Apigee automaticamente 3 giorni dopo la scadenza. Vedi anche Eliminazione dei token di accesso

Predefinito

Se non viene specificato, il sistema applica un valore predefinito configurato a livello di sistema.

Presenza

Facoltativo
Tipo Numero intero
Valori validi

Qualsiasi numero intero positivo diverso da zero. Specifica la scadenza in millisecondi. Sebbene il valore di questo elemento sia in millisecondi, il valore impostato nella proprietà expires_in del token e nella variabile di flusso expires_in è espresso in secondi.
Utilizzato con i tipi di concessione
  • authorization_code
  • implicito
  • password
  • client_credentials
  • refresh_token

Utilizzato anche con l'operazione GenerateAuthorizationCode.

Elemento <ExternalAccessToken>

<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>

Indica ad Apigee dove trovare un token di accesso esterno (un token di accesso non generato da Apigee).

La variabile request.queryparam.external_access_token indica che il token di accesso esterno deve essere presente come parametro di query, ad esempio ?external_access_token=12345678. Per richiedere il token di accesso esterno in un'intestazione HTTP, ad esempio, imposta questo valore su request.header.external_access_token. Vedi anche Utilizzo di token OAuth di terze parti.

Elemento <ExternalAuthorization>

<ExternalAuthorization>true</ExternalAuthorization>

Se questo elemento è false o non è presente, Apigee convalida client_id e client_secret normalmente rispetto all'archivio di autorizzazione Apigee. Utilizza questo elemento quando vuoi lavorare con token OAuth di terze parti. Per informazioni dettagliate sull'utilizzo di questo elemento, vedi Utilizzo di token OAuth di terze parti.

Predefinito

falso

Presenza

Facoltativo
Tipo Booleano
Valori validi vero o falso
Utilizzato con i tipi di concessione
  • authorization_code
  • password
  • client_credentials

Elemento <ExternalAuthorizationCode>

<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>

Indica ad Apigee dove trovare un codice di autorizzazione esterno (un codice di autorizzazione non generato da Apigee).

La variabile request.queryparam.external_auth_code indica che il codice di autorizzazione esterno deve essere presente come parametro di query, ad esempio ?external_auth_code=12345678. Per richiedere il codice di autenticazione esterno in un'intestazione HTTP, ad esempio, imposta questo valore su request.header.external_auth_code. Vedi anche Utilizzo di token OAuth di terze parti.

Elemento <ExternalRefreshToken>

<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>

Indica ad Apigee dove trovare un token di aggiornamento esterno (un token di aggiornamento non generato da Apigee).

La variabile request.queryparam.external_refresh_token indica che il token di aggiornamento esterno deve essere presente come parametro di query, ad esempio ?external_refresh_token=12345678. Per richiedere il token di aggiornamento esterno in un'intestazione HTTP, ad esempio, imposta questo valore su request.header.external_refresh_token. Vedi anche Utilizzo di token OAuth di terze parti.

Elemento <GenerateResponse>

<GenerateResponse enabled='true'/>

Se è impostato su true o se l'attributo enabled viene omesso, il criterio genera e restituisce una risposta. Ad esempio, per GenerateAccessToken, la risposta potrebbe essere simile a questa:

{
  "issued_at" : "1467841035013",
  "scope" : "read",
  "application_name" : "e31b8d06-d538-4f6b-9fe3-8796c11dc930",
  "refresh_token_issued_at" : "1467841035013",
  "status" : "approved",
  "refresh_token_status" : "approved",
  "api_product_list" : "[Product1, nhl_product]",
  "expires_in" : "1799",
  "developer.email" : "edward@slalom.org",
  "token_type" : "BearerToken",
  "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj",
  "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a",
  "organization_name" : "cerruti",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

Se impostato su false o se l'elemento <GenerateResponse> viene omesso, non viene inviata alcuna risposta. Viene invece compilato un insieme di variabili di flusso con valori correlati alla funzione del criterio. Ad esempio, una variabile di flusso chiamata oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code viene compilata con il nuovo codice di autorizzazione. Tieni presente che expires_in è espresso in secondi nella risposta.

Predefinito

true

Presenza

Facoltativo
Tipo string
Valori validi vero o falso
Utilizzato con i tipi di concessione
  • implicito
  • password
  • client_credentials
  • refresh_token
  • Può essere utilizzato anche con l'operazione GenerateAuthorizationCode.

Elemento <GenerateErrorResponse>

<GenerateErrorResponse enabled='true'/>

Se impostato su true, il criterio genera e restituisce una risposta se l'attributo ContinueOnError è impostato su true. Se false (il valore predefinito), non viene inviata alcuna risposta. Viene invece compilato un insieme di variabili di flusso con valori correlati alla funzione del criterio.

Predefinito

falso

Presenza

Facoltativo
Tipo string
Valori validi vero o falso
Utilizzato con i tipi di concessione
  • implicito
  • password
  • client_credentials
  • refresh_token
  • Può essere utilizzato anche con l'operazione GenerateAuthorizationCode.

<GrantType>

<GrantType>request.queryparam.grant_type</GrantType>

Indica alla policy dove trovare il parametro del tipo di concessione passato in una richiesta. In base alla specifica OAuth 2.0, il tipo di concessione deve essere fornito con le richieste di token di accesso e codici di autorizzazione. La variabile può essere un'intestazione, un parametro di query o un parametro del modulo (impostazione predefinita).

Ad esempio, request.queryparam.grant_type indica che la password deve essere presente come parametro di query, ad esempio ?grant_type=password. Per richiedere il tipo di concessione in un'intestazione HTTP, ad esempio, imposta questo valore su request.header.grant_type. Vedi anche Recuperare i token OAuth 2.0.

Predefinito

request.formparam.grant_type (un x-www-form-urlencoded specificato nel corpo della richiesta)

Presenza

Facoltativo
Tipo string
Valori validi Una variabile, come spiegato sopra.
Utilizzato con i tipi di concessione
  • authorization_code
  • password
  • implicito
  • client_credentials
  • refresh_token

Elemento <Operation>

<Operation>GenerateAuthorizationCode</Operation>

L'operazione OAuth 2.0 eseguita dalla policy.

Predefinito

Se <Operation> non è specificato, Apigee esamina l'elenco di <SupportedGrantTypes>. Solo le operazioni su questi tipi di concessione avranno esito positivo. In altre parole, puoi omettere <Operation> se specifichi un <GrantType> nell'elenco <SupportedGrantTypes>. Se non vengono specificati <Operation> né <SupportedGrantTypes>, il tipo di autorizzazione predefinito è authorization_code. ovvero le richieste di tipo di concessione authorization_code andranno a buon fine, ma tutte le altre non riusciranno.

Presenza

Facoltativo
Tipo Stringa
Valori validi
  • GenerateAccessToken: genera un token di accesso. Vedi anche Recuperare i token OAuth 2.0.
  • GenerateAccessTokenImplicitGrant - Genera un token di accesso per il tipo di concessione implicita. Vedi anche Recuperare i token OAuth 2.0.
  • GenerateAuthorizationCode: genera un codice di autorizzazione. Utilizzato con il tipo di autorizzazione codice di autorizzazione. Vedi anche Recuperare i token OAuth 2.0.
  • RefreshAccessToken: scambia un token di aggiornamento con un nuovo token di accesso. Vedi anche Recuperare i token OAuth 2.0.
  • VerifyAccessToken: verifica che un token di accesso inviato in una richiesta sia valido. Vedi l'esempio VerifyAccessToken riportato sopra e Verifica dei token di accesso.
  • InvalidateToken - Revoca un token di accesso. Una volta revocato un token, i client non possono utilizzarlo per chiamare un'API protetta. Vedi anche Approvazione e revoca dei token di accesso.
  • ValidateToken: ripristina o "approva" un token di accesso che era stato revocato in precedenza. Vedi anche Approvazione e revoca dei token di accesso.

Operazioni aggiuntive con i token di accesso JWT

Se preferisci utilizzare token di accesso JWT anziché token stringa opachi, sono disponibili anche le seguenti operazioni per generare e convalidare i token JWT. Per maggiori dettagli, vedi Utilizzo delle operazioni sui token OAuth JWT:

Elemento <PassWord>

<PassWord>request.queryparam.password</PassWord>

Questo elemento viene utilizzato solo con il tipo di autorizzazione password. Con il tipo di concessione della password, le credenziali utente (password e nome utente) devono essere rese disponibili al criterio OAuthV2. Gli elementi <PassWord> e <UserName> vengono utilizzati per specificare le variabili in cui Apigee può trovare questi valori. Se questi elementi non sono specificati, il criterio prevede di trovare i valori (per impostazione predefinita) nei parametri del modulo denominati username e password. Se i valori non vengono trovati, il criterio genera un errore. Puoi utilizzare gli elementi <PassWord> e <UserName> per fare riferimento a qualsiasi variabile di flusso contenente le credenziali.

Ad esempio, puoi trasmettere la password in una richiesta di token utilizzando un parametro di query e impostare l'elemento nel seguente modo: <PassWord>request.queryparam.password</PassWord>. Per richiedere la password in un'intestazione HTTP, imposta questo valore su request.header.password.

Il criterio OAuthV2 non esegue altre operazioni con questi valori delle credenziali; Apigee si limita a verificare che siano presenti. Spetta allo sviluppatore dell'API recuperare la richiesta di valori e inviarli a un provider di identità prima dell'esecuzione della policy di generazione dei token.

Vedi anche Recuperare i token OAuth 2.0.

Predefinito

request.formparam.password (un x-www-form-urlencoded e specificato nel corpo della richiesta)

Presenza

Facoltativo
Tipo Stringa
Valori validi Qualsiasi variabile di flusso disponibile per il criterio in fase di runtime.
Utilizzato con i tipi di concessione password

<PrivateKey>/<Value>

<PrivateKey>
  <Value ref="variable-name-here"/>
</PrivateKey>

Fornisce la chiave privata utilizzata per verificare o firmare token di accesso in formato JWT con un algoritmo RSA. Utilizza l'attributo ref per passare la chiave in una variabile di flusso. Utilizza solo quando il valore dell'elemento Algorithm è RS256, RS384 o RS512. Per maggiori informazioni, consulta Utilizzo delle operazioni sui token OAuth JWT.

Predefinito N/D
Presenza Obbligatorio quando il valore dell'elemento Algorithm è uno tra HS256, HS384 o HS512.
Tipo Stringa
Valori validi Una variabile di flusso contenente una stringa che rappresenta un valore della chiave privata RSA con codifica PEM.

<PublicKey>/<Value>

<PublicKey>
   <Value ref="variable-name-here"/>
</PublicKey>

Specifica la chiave pubblica o il certificato pubblico utilizzato per verificare la firma di un token di accesso in formato JWT firmato con un algoritmo RSA. Utilizza l'attributo ref per trasferire la chiave/il certificato in una variabile di flusso. Utilizza solo quando il valore dell'elemento Algorithm è RS256, RS384 o RS512.

Predefinito N/D
Presenza Per verificare un JWT firmato con un algoritmo RSA, devi utilizzare gli elementi Certificate, JWKS o Value.
Tipo Stringa
Valori validi Una variabile di flusso o una stringa.

Elemento <RedirectUri>

<RedirectUri>request.queryparam.redirect_uri</RedirectUri>

Specifica dove Apigee deve cercare il parametro redirect_uri nella richiesta.

Informazioni sugli URI di reindirizzamento

Gli URI di reindirizzamento vengono utilizzati con i tipi di autorizzazione codice e implicita. L'URI di reindirizzamento indica al server di autorizzazione (Apigee) dove inviare un codice di autorizzazione (per il tipo di concessione del codice di autorizzazione) o un token di accesso (per il tipo di concessione implicita). È importante capire quando questo parametro è obbligatorio, quando è facoltativo e come viene utilizzato:

  • (obbligatorio) Se un URL di callback è registrato con l'app per sviluppatori associata alle chiavi client della richiesta e se redirect_uri è presente nella richiesta, i due devono corrispondere esattamente. Se non corrispondono, viene restituito un errore. Per informazioni sulla registrazione delle app per sviluppatori su Apigee e sulla specifica di un URL di callback, consulta Registrare app e gestire le chiavi API.

  • (facoltativo) Se è registrato un URL di callback e redirect_uri non è presente nella richiesta, Apigee reindirizza all'URL di callback registrato.
  • (obbligatorio) Se non è registrato un URL di callback, è obbligatorio redirect_uri. Tieni presente che in questo caso Apigee accetterà QUALSIASI URL. Questo caso può presentare un problema di sicurezza e pertanto deve essere utilizzato solo con app client attendibili. Se le app client non sono attendibili, la best practice è richiedere sempre la registrazione di un URL di callback.

Puoi inviare questo parametro in un parametro di query o in un'intestazione. La variabile request.queryparam.redirect_uri indica che RedirectUri deve essere presente come parametro di query, ad esempio ?redirect_uri=login.myapp.com. Per richiedere RedirectUri in un'intestazione HTTP, ad esempio, imposta questo valore su request.header.redirect_uri. Consulta anche Recuperare i token OAuth 2.0.

Predefinito

request.formparam.redirect_uri (un x-www-form-urlencoded e specificato nel corpo della richiesta)

Presenza

Facoltativo
Tipo Stringa
Valori validi Qualsiasi variabile di flusso accessibile nel criterio in fase di runtime
Utilizzato con i tipi di concessione
  • authorization_code
  • implicito

Utilizzato anche con l'operazione GenerateAuthorizationCode.

Elemento <RefreshToken>

<RefreshToken>request.queryparam.refreshtoken</RefreshToken>

Quando richiedi un token di accesso utilizzando un token di aggiornamento, devi fornire il token di aggiornamento nella richiesta. Questo elemento consente di specificare dove Apigee deve cercare il token di aggiornamento. Ad esempio, può essere inviato come parametro di query, intestazione HTTP o parametro del modulo (impostazione predefinita).

La variabile request.queryparam.refreshtoken indica che il token di aggiornamento deve essere presente come parametro di query, ad esempio ?refresh_token=login.myapp.com. Per richiedere il RefreshToken in un'intestazione HTTP, ad esempio, imposta questo valore su request.header.refresh_token. Consulta anche Recuperare i token OAuth 2.0.

Predefinito

request.formparam.refresh_token (un x-www-form-urlencoded specificato nel corpo della richiesta)

Presenza

Facoltativo
Tipo Stringa
Valori validi Qualsiasi variabile di flusso accessibile nel criterio in fase di runtime
Utilizzato con i tipi di concessione
  • refresh_token

Elemento <RefreshTokenExpiresIn>

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

Applica il tempo di scadenza dei token di aggiornamento in millisecondi. Il valore dell'ora di scadenza è un valore generato dal sistema più il valore <RefreshTokenExpiresIn>. Se <RefreshTokenExpiresIn> non è specificato, il sistema applica il valore predefinito.

Il tempo di scadenza può essere impostato anche in fase di runtime utilizzando un valore predefinito hardcoded o facendo riferimento a una variabile di flusso. Ad esempio, puoi memorizzare un valore di scadenza del token in una mappa chiave-valore, recuperarlo, assegnarlo a una variabile e farvi riferimento nel criterio. Ad esempio, kvm.oauth.expires_in.

La seguente strofa specifica una variabile di flusso e anche un valore predefinito. Tieni presente che il valore della variabile del flusso ha la precedenza sul valore predefinito specificato.

<RefreshTokenExpiresIn ref="kvm.oauth.expires_in">
    86400000 <!--value in milliseconds-->
</RefreshTokenExpiresIn>

Predefinito

2592000000 ms (30 giorni) (a partire dal 31 maggio 2023)

Presenza

Facoltativo
Tipo Numero intero
Valori validi

Qualsiasi numero intero positivo diverso da zero. Specifica il tempo di scadenza in millisecondi.
Utilizzato con i tipi di concessione
  • authorization_code
  • password
  • refresh_token

Elemento <ResponseType>

<ResponseType>request.queryparam.response_type</ResponseType>

Questo elemento comunica ad Apigee il tipo di concessione richiesto dall'app client. Viene utilizzato solo con i flussi di autorizzazione del codice e del tipo di autorizzazione implicit.

Per impostazione predefinita, Apigee cerca il valore del tipo di risposta in un parametro di query response_type. Se vuoi ignorare questo comportamento predefinito, utilizza l'elemento <ResponseType> per configurare una variabile di flusso contenente il valore del tipo di risposta. Ad esempio, se imposti questo elemento su request.header.response_type, Apigee cerca il tipo di risposta da trasmettere nell'intestazione della richiesta. Vedi anche Recuperare i token OAuth 2.0.

Predefinito

request.formparam.response_type (un x-www-form-urlencoded e specificato nel corpo della richiesta)

Presenza

Facoltativo. Utilizza questo elemento se vuoi ignorare il comportamento predefinito.

Tipo Stringa
Valori validi code (per il tipo di concessione del codice di autorizzazione) o token (per il tipo di concessione implicita)
Utilizzato con i tipi di concessione
  • implicito
  • Utilizzato anche con l'operazione GenerateAuthorizationCode.

Elemento <ReuseRefreshToken>

<ReuseRefreshToken>true</ReuseRefreshToken>

Se impostato su true, il token di aggiornamento esistente viene riutilizzato fino alla scadenza. Se false, Apigee emette un nuovo token di aggiornamento quando viene presentato un token di aggiornamento valido.

Predefinito

false

Presenza

facoltativo
Tipo boolean
Valori validi

true o false
Utilizzato con i tipi di concessione
  • refresh_token

Elemento <RFCCompliantRequestResponse>

<RFCCompliantRequestResponse>[true | false]</RFCCompliantRequestResponse>

Il criterio OAuthV2, con l'operazione GenerateAccessToken, può restituire una risposta non conforme alle specifiche IETF OAuth 2.0 correlate, incluse RFC 6749 e RFC 6750. Se includi l'elemento RFCCompliantRequestResponse nel criterio, con un valore di true, il criterio OAuthV2 restituisce una risposta conforme alla RFC.

La tabella seguente mostra le differenze in alcuni valori restituiti dal criterio OAuthV2, a seconda che l'elemento RFCCompliantRequestResponse sia true o false.

Elemento Il valore è falso o assente Il valore è true
Intestazione HTTP Cache-Control Nessuno fornito Le risposte di errore e non di errore includeranno il campo di intestazione della risposta HTTP Cache-Control per rispettare RFC2616 (Hypertext Transfer Protocol - HTTP/1.1), con un valore di no-store in qualsiasi risposta contenente token, credenziali o altre informazioni sensibili, nonché il campo di intestazione della risposta Pragma con un valore di no-cache.
Proprietà "token_type" nella risposta del token valido

Un valore token_type non conforme.

{
 ...
 "token_type": "BearerToken",
 ...
}

Un valore token_type conforme.

{
 ...
 "token_type": "Bearer",
 ...
}
Proprietà "expires_in" e "refresh_token_expires_in" in una risposta del token valida

Il valore numerico è racchiuso tra virgolette. Esempio:

{
 ...
 "expires_in": "3600",
 "refresh_token_expires_in":
   "345600",
 ...
}

Il valore viene serializzato come numero, non come stringa. Esempio: 

{
 ...
 "expires_in": 3600,
 "refresh_token_expires_in":
   345600,
 ...
}
risposta di errore per un token di aggiornamento scaduto quando grant_type = refresh_token

Le risposte di errore non erano conformi alla RFC 6749. Esempio:

{
 "ErrorCode": "InvalidRequest",
 "Error": "Refresh Token expired"
}

I payload di risposta agli errori includeranno gli elementi "error" e "error_description". Esempio:

{
 "error": "invalid_grant",
 "error_description":
   "refresh token expired"
}

Predefinito

false: per impostazione predefinita, il criterio mostrerà determinati comportamenti non conformi alla RFC come descritto in precedenza.

Presenza

Facoltativo
Tipo Booleano
Valori validi true o false
Utilizzato con i tipi di concessione Tutti

<SecretKey>/<Value>

<SecretKey>
  <Value ref="your-variable-name"/>
</SecretKey>

Fornisce la chiave segreta utilizzata per verificare o firmare i token di accesso in formato JWT con un algoritmo HMAC. Utilizzare solo quando l'algoritmo è HS256, HS384 o HS512. Utilizza l'attributo ref per passare la chiave in una variabile di flusso. Per maggiori informazioni, consulta Utilizzo delle operazioni sui token OAuth JWT.

Apigee applica una lunghezza minima della chiave per gli algoritmi HS256/HS384/HS512. La lunghezza minima della chiave per HS256 è di 32 byte, per HS384 è di 48 byte e per HS512 è di 64 byte. L'utilizzo di una chiave con una potenza inferiore causa un errore di runtime.

Predefinito N/D
Presenza Obbligatorio per gli algoritmi HMAC.
Tipo Stringa
Valori validi Una variabile di flusso

Elemento <Scope>

<Scope>request.queryparam.scope</Scope>

Se questo elemento è presente in uno dei criteri GenerateAccessToken o GenerateAuthorizationCode, viene utilizzato per specificare gli ambiti da concedere al token o al codice. Questi valori vengono in genere passati al criterio nella richiesta da un'app client. Puoi configurare l'elemento in modo che accetti una variabile di flusso, offrendoti la possibilità di scegliere come vengono passati gli ambiti in una richiesta. Nell'esempio seguente, request.queryparam.scope indica che l'ambito deve essere presente come parametro di query, ad esempio ?scope=READ. Per richiedere l'ambito in un'intestazione HTTP, ad esempio, imposta questo valore su request.header.scope.

Se questo elemento viene visualizzato in un criterio "VerifyAccessToken", viene utilizzato per specificare gli ambiti che il criterio deve applicare. In questo tipo di criterio, il valore deve essere un nome di ambito "hardcoded", ovvero non puoi utilizzare variabili. Ad esempio:

<Scope>A B</Scope>

Vedi anche Utilizzo degli ambiti OAuth2 e Recuperare i token OAuth 2.0.

Predefinito

Nessun ambito

Presenza

Facoltativo
Tipo Stringa
Valori validi

Se utilizzata con le policy Generate*, una variabile di flusso.

Se utilizzato con VerifyAccessToken, un elenco di nomi di ambiti (stringhe) separati da spazi.
Utilizzato con i tipi di concessione
  • authorization_code
  • implicito
  • password
  • client_credentials
  • Può essere utilizzato anche con le operazioni GenerateAuthorizationCode e VerifyAccessToken.

Elemento <State>

<State>request.queryparam.state</State>

Nei casi in cui l'app client deve inviare le informazioni sullo stato al server di autorizzazione, questo elemento ti consente di specificare dove Apigee deve cercare i valori di stato. Ad esempio, potrebbe essere inviato come parametro di query o in un'intestazione HTTP. Il valore dello stato viene in genere utilizzato come misura di sicurezza per prevenire attacchi CSRF.

Ad esempio, request.queryparam.state indica che lo stato deve essere presente come parametro di query, ad esempio ?state=HjoiuKJH32. Per richiedere lo stato in un'intestazione HTTP, ad esempio, imposta questo valore su request.header.state. Vedi anche Recuperare i token OAuth 2.0.

Predefinito

Nessuno stato

Presenza

Facoltativo
Tipo Stringa
Valori validi Qualsiasi variabile di flusso accessibile al criterio in fase di runtime
Utilizzato con i tipi di concessione
  • Tutti
  • Può essere utilizzato anche con l'operazione GenerateAuthorizationCode

Elemento <StoreToken>

 <StoreToken>true</StoreToken>

Imposta questo elemento su true quando l'elemento <ExternalAuthorization> è true. L'elemento <StoreToken> indica ad Apigee di memorizzare il token di accesso esterno. In caso contrario, non verrà mantenuto.

Predefinito

falso

Presenza

Facoltativo
Tipo Booleano
Valori validi vero o falso
Utilizzato con i tipi di concessione
  • authorization_code
  • password
  • client_credentials

<SupportedGrantTypes>/<GrantType> elemento

<SupportedGrantTypes>
    <GrantType>authorization_code</GrantType>
    <GrantType>client_credentials</GrantType>
    <GrantType>implicit</GrantType>
    <GrantType>password</GrantType>
</SupportedGrantTypes>

Specifica i tipi di concessione supportati da un endpoint token OAuth su Apigee. Un endpoint può supportare più tipi di concessione (ovvero, un singolo endpoint può essere configurato per distribuire token di accesso per più tipi di concessione). Per saperne di più sugli endpoint, consulta Informazioni sugli endpoint OAuth. Il tipo di concessione viene passato nelle richieste di token in un parametro grant_type.

Se non vengono specificati tipi di autorizzazione supportati, gli unici tipi di autorizzazione consentiti sono authorization_code e implicit. Vedi anche l'elemento <GrantType> (un elemento di livello superiore utilizzato per specificare dove Apigee deve cercare il parametro grant_type passato in una richiesta client. Apigee si assicurerà che il valore del parametro grant_type corrisponda a uno dei tipi di concessione supportati.

Predefinito

authorization _code and implicit

Presenza

Obbligatorio
Tipo Stringa
Valori validi
  • client_credentials
  • authorization_code
  • password
  • implicito

Elemento <Tokens>/<Token>

Utilizzato con le operazioni ValidateToken e InvalidateToken. Vedi anche Approvazione e revoca dei token di accesso. L'elemento <Token> identifica la variabile di flusso che definisce l'origine del token da revocare. Se gli sviluppatori devono inviare token di accesso come parametri di ricercay denominati access_token, ad esempio, utilizza request.queryparam.access_token.

Elemento <UserName>

<UserName>request.queryparam.user_name</UserName>

Questo elemento viene utilizzato solo con il tipo di autorizzazione password. Con il tipo di concessione della password, le credenziali utente (password e nome utente) devono essere rese disponibili al criterio OAuthV2. Gli elementi <PassWord> e <UserName> vengono utilizzati per specificare le variabili in cui Apigee può trovare questi valori. Se questi elementi non sono specificati, il criterio prevede di trovare i valori (per impostazione predefinita) nei parametri del modulo denominati username e password. Se i valori non vengono trovati, il criterio genera un errore. Puoi utilizzare gli elementi <PassWord> e <UserName> per fare riferimento a qualsiasi variabile di flusso contenente le credenziali.

Ad esempio, puoi trasmettere il nome utente in un parametro di query e impostare l'elemento <UserName> nel seguente modo: <UserName>request.queryparam.username</UserName>.Per richiedere il nome utente in un'intestazione HTTP, imposta questo valore su request.header.username.

Il criterio OAuthV2 non esegue altre operazioni con questi valori delle credenziali; Apigee si limita a verificare che siano presenti. Spetta allo sviluppatore dell'API recuperare la richiesta di valori e inviarli a un provider di identità prima dell'esecuzione della policy di generazione dei token.

Vedi anche Recuperare i token OAuth 2.0.

Predefinito

request.formparam.username (un valore x-www-form-urlencoded specificato nel corpo della richiesta)

Presenza

Facoltativo
Tipo Stringa
Valori validi Qualsiasi impostazione della variabile.
Utilizzato con i tipi di concessione password

Verifica dei token di accesso

Una volta configurato un endpoint token per un proxy API, al flusso che espone la risorsa protetta viene collegata una policy OAuthV2 corrispondente che specifica l'operazione VerifyAccessToken.

Ad esempio, per assicurarti che tutte le richieste a un'API siano autorizzate, la seguente policy impone la verifica del token di accesso:

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

Il criterio è associato alla risorsa API da proteggere. Per assicurarti che tutte le richieste a un'API vengano verificate, collega la policy al PreFlow della richiesta ProxyEndpoint, nel seguente modo:

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthAccessToken</Name></Step>
  </Request>
</PreFlow>

I seguenti elementi facoltativi possono essere utilizzati per eseguire l'override delle impostazioni predefinite per l'operazione VerifyAccessToken.

Nome Descrizione
Ambito

Un elenco di ambiti delimitati da spazi. La verifica riuscirà se almeno uno degli ambiti elencati è presente nel token di accesso. Ad esempio, la seguente policy controlla il token di accesso per assicurarsi che contenga almeno uno degli ambiti elencati. Se è presente READ o WRITE, la verifica andrà a buon fine.

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>
AccessToken La variabile in cui è previsto che si trovi il token di accesso. Ad esempio request.queryparam.accesstoken. Per impostazione predefinita, il token di accesso deve essere presentato dall'app nell'intestazione HTTP Authorization, in conformità con la specifica OAuth 2.0. Utilizza questa impostazione se è previsto che il token di accesso venga presentato in una posizione non standard, ad esempio un parametro di query o un'intestazione HTTP con un nome diverso da Authorization.

Vedi anche Verifica dei token di accesso e Recupero dei token OAuth 2.0.

Specificare le posizioni delle variabili di richiesta

Per ogni tipo di concessione, la policy fa ipotesi sulla posizione o sulle informazioni richieste nei messaggi di richiesta. Queste ipotesi si basano sulla specifica OAuth 2.0. Se le tue app devono discostarsi dalla specifica OAuth 2.0, puoi specificare le posizioni previste per ogni parametro. Ad esempio, quando gestisci un codice di autorizzazione, puoi specificare la posizione del codice di autorizzazione, dell'ID client, dell'URI di reindirizzamento e dell'ambito. Questi possono essere specificati come intestazioni HTTP, parametri di ricerca o parametri del modulo.

L'esempio seguente mostra come specificare la posizione dei parametri del codice di autorizzazione richiesti come intestazioni HTTP:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.header.client_id</ClientId>
  <RedirectUri>request.header.redirect_uri</RedirectUri>
  <Scope>request.header.scope</Scope>
  ...

In alternativa, se necessario per supportare la base di app client, puoi combinare intestazioni e parametri di query:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.queryparam.client_id</ClientId>
  <RedirectUri>request.queryparam.redirect_uri</RedirectUri>
  <Scope>request.queryparam.scope</Scope>
  ...

È possibile configurare una sola posizione per parametro.

Variabili di flusso

Le variabili di flusso definite in questa tabella vengono compilate quando vengono eseguite le rispettive policy OAuth e sono quindi disponibili per altre policy o applicazioni eseguite nel flusso del proxy API.

Operazione VerifyAccessToken

Quando viene eseguita l'operazione VerifyAccessToken, un gran numero di variabili di flusso viene compilato nel contesto di esecuzione del proxy. Queste variabili forniscono proprietà relative al token di accesso, all'app sviluppatore e allo sviluppatore. Puoi utilizzare una policy AssignMessage o JavaScript, ad esempio, per leggere una qualsiasi di queste variabili e utilizzarle in base alle esigenze in un secondo momento nel flusso. Queste variabili possono essere utili anche per scopi di debug.

Variabili specifiche per il token

Variabili Descrizione
organization_name Il nome dell'organizzazione in cui viene eseguito il proxy.
developer.id L'ID dello sviluppatore o dell'AppGroup associato all'app client registrata.
developer.app.name Il nome dello sviluppatore o dell'app AppGroup associata all'app client registrata.
client_id L'ID client dell'app client registrata.
grant_type Il tipo di concessione associato alla richiesta. Non supportato per l'operazione VerifyJWTAccessToken.
token_type Il tipo di token associato alla richiesta.
access_token Il token di accesso in fase di verifica.
accesstoken.{custom_attribute} Un attributo personalizzato denominato nel token di accesso.
issued_at La data di emissione del token di accesso espressa in tempo epoca Unix in millisecondi.
expires_in L'ora di scadenza del token di accesso. Espresso in secondi. Sebbene l'elemento ExpiresIn imposti la scadenza in millisecondi, nella risposta del token e nelle variabili di flusso, il valore è espresso in secondi.
status Lo stato del token di accesso (ad es. approvato o revocato).
scope L'ambito (se presente) associato al token di accesso.
apiproduct.<custom_attribute_name> Un attributo personalizzato denominato del prodotto API associato all'app client registrata.
apiproduct.name Il nome del prodotto API associato all'app client registrata.
revoke_reason

(Solo Apigee hybrid) Indica il motivo per cui il token di accesso è stato revocato. Non supportato per l'operazione VerifyJWTAccessToken.

Il valore può essere REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER o TOKEN_REVOKED.

Variabili specifiche per l'app

Queste variabili sono correlate all'app per sviluppatori associata al token.

Variabili Descrizione
app.name
app.id
app.accessType
app.callbackUrl
app.status approvata o revocata
app.scopes
app.appFamily
app.apiproducts
app.appParentStatus
app.appType Ad esempio: Sviluppatore
app.appParentId
app.created_by
app.created_at
app.last_modified_at
app.last_modified_by
app.{custom_attributes} Un attributo personalizzato denominato dell'app client registrata.

Variabili specifiche di AppGroup

Le seguenti variabili di flusso contengono informazioni sull'AppGroup per il token e vengono compilate dalle norme. Questi attributi di AppGroup vengono compilati solo se verifyapikey.{policy_name}.app.appType è "AppGroup".

Variabili Descrizione
appgroup.displayName Il nome visualizzato di AppGroup.
appgroup.name Nome di AppGroup.
appgroup.id L'ID AppGroup.
appOwnerStatus Lo stato del proprietario dell'app: "active" (attivo), "inactive" (non attivo) o "login_lock" (accesso bloccato).
created_at Il timestamp di data/ora di creazione dell'AppGroup.
created_by L'indirizzo email dello sviluppatore che ha creato l'AppGroup.
last_modified_at Il timestamp di data/ora dell'ultima modifica dell'AppGroup.
last_modified_by L'indirizzo email dello sviluppatore che ha modificato per l'ultima volta l'AppGroup.
{appgroup_custom_attributes} Qualsiasi attributo personalizzato AppGroup. Specifica il nome dell'attributo personalizzato.

Variabili specifiche per gli sviluppatori

Se app.appType è "Sviluppatore", vengono compilati gli attributi dello sviluppatore.

Variabili Descrizione
Variabili specifiche per gli sviluppatori
developer.id
developer.userName
developer.firstName
developer.lastName
developer.email
developer.status attiva o non attiva
developer.apps
developer.created_by
developer.created_at
developer.last_modified_at
developer.last_modified_by
developer.{custom_attributes} Un attributo personalizzato denominato dello sviluppatore.

Operazione GenerateAuthorizationCode

Queste variabili vengono impostate quando l'operazione GenerateAuthorizationCode viene eseguita correttamente:

Prefisso: oauthv2authcode.{policy_name}.{variable_name}

Esempio: oauthv2authcode.GenerateCodePolicy.code

Variabile Descrizione
code Il codice di autorizzazione generato durante l'esecuzione della policy.
redirect_uri L'URI di reindirizzamento associato all'app client registrata.
scope L'ambito OAuth facoltativo passato nella richiesta del client.
client_id L'ID client passato nella richiesta del client.

Operazioni GenerateAccessToken e RefreshAccessToken

Queste variabili vengono impostate quando le operazioni GenerateAccessToken e RefreshAccessToken vengono eseguite correttamente. Tieni presente che le variabili del token di aggiornamento non si applicano al flusso del tipo di concessione delle credenziali client.

Prefisso: oauthv2accesstoken.{policy_name}.{variable_name}

Esempio: oauthv2accesstoken.GenerateTokenPolicy.access_token

Nome variabile Descrizione
access_token Il token di accesso generato.
client_id L'ID client dell'app sviluppatore associata a questo token.
expires_in Il valore di scadenza del token. Per ulteriori dettagli, consulta l'elemento <ExpiresIn>. Tieni presente che nella risposta, expires_in è espresso in secondi.
scope Elenco degli ambiti disponibili configurati per il token. Consulta la sezione Utilizzo degli ambiti OAuth2.
status approved o revoked.
token_type È impostato su BearerToken.
developer.email L'indirizzo email dello sviluppatore registrato proprietario dell'app per sviluppatori associata al token.
organization_name L'organizzazione in cui viene eseguito il proxy.
api_product_list Un elenco dei prodotti associati all'app per sviluppatori corrispondente al token.
refresh_count
refresh_token Il token di aggiornamento generato. Tieni presente che i token di aggiornamento non vengono generati per il tipo di concessione delle credenziali client.
refresh_token_expires_in La durata del token di aggiornamento, in secondi.
refresh_token_issued_at Questo valore temporale è la rappresentazione in formato stringa della quantità di timestamp a 32 bit corrispondente. Ad esempio, "Wed, 21 Aug 2013 19:16:47 UTC" corrisponde al valore del timestamp 1377112607413.
refresh_token_status approved o revoked.

GenerateAccessTokenImplicitGrant

Queste variabili vengono impostate quando l'operazione GenerateAccessTokenImplicit viene eseguita correttamente per il flusso del tipo di concessione implicita.

Prefisso: oauthv2accesstoken.{policy_name}.{variable_name}

Esempio: oauthv2accesstoken.RefreshTokenPolicy.access_token

Variabile Descrizione
oauthv2accesstoken.access_token Il token di accesso generato durante l'esecuzione del criterio.
oauthv2accesstoken.{policy_name}.expires_in Il valore di scadenza del token, in secondi. Per ulteriori dettagli, consulta l'elemento <ExpiresIn>.

Riferimento agli errori

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Thrown by operations
steps.oauth.v2.access_token_expired 401 The access token is expired.

VerifyAccessToken
InvalidateToken
steps.oauth.v2.access_token_not_approved 401 The access token was revoked. VerifyAccessToken
steps.oauth.v2.apiproduct_doesnot_exist 401 The requested API product does not exist in any of the API products associated with the access token. VerifyAccessToken
steps.oauth.v2.FailedToResolveAccessToken 500 The policy expected to find an access token in a variable specified in the <AccessToken> element, but the variable could not be resolved. GenerateAccessToken
steps.oauth.v2.FailedToResolveAuthorizationCode 500 The policy expected to find an authorization code in a variable specified in the <Code> element, but the variable could not be resolved. GenerateAuthorizationCode
steps.oauth.v2.FailedToResolveClientId 500 The policy expected to find the Client ID in a variable specified in the <ClientId> element, but the variable could not be resolved. GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken
steps.oauth.v2.FailedToResolveRefreshToken 500 The policy expected to find a refresh token in a variable specified in the <RefreshToken> element, but the variable could not be resolved. RefreshAccessToken
steps.oauth.v2.FailedToResolveToken 500 The policy expected to find a token in a variable specified in the <Tokens> element, but the variable could not be resolved.

ValidateToken
InvalidateToken
steps.oauth.v2.InsufficientScope 403 The access token presented in the request has a scope that does not match the scope specified in the verify access token policy. To learn about scope, see Working with OAuth2 scopes. VerifyAccessToken
steps.oauth.v2.invalid_client 401

This error name is returned when the <GenerateResponse> property of the policy is set to true and the client ID sent in the request is invalid. Check to be sure you are using the correct client key and secret values for the Developer App associated with your proxy. Typically, these values are sent as a Base64 encoded Basic Authorization header.

 GenerateAccessToken
RefreshAccessToken
steps.oauth.v2.InvalidRequest 400 This error name is used for multiple different kinds of errors, typically for missing or incorrect parameters sent in the request. If <GenerateResponse> is set to false, use fault variables (described below) to retrieve details about the error, such as the fault name and cause. GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken
steps.oauth.v2.InvalidAccessToken 401 The authorization header does not have the word Bearer, which is required. For example: Authorization: Bearer your_access_token VerifyAccessToken
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound 401

The currently executing API proxy or operation is not in the Product associated with the access token.

Tips: Be sure that the product associated with the access token is configured correctly. For example, if you use wildcards in resource paths, be sure the wildcards are being used correctly. See Managing API products for details.

See also Oauth2.0 Access Token Verification throws "Invalid API call as no apiproduct match found" error for more guidance on causes for this error.

 VerifyAccessToken
steps.oauth.v2.InvalidClientIdentifier 500

This error name is returned when the <GenerateResponse> property of the policy is set to false and the client ID sent in the request is invalid. Check to be sure you are using the correct client key and secret values for the Developer App associated with your proxy. Typically, these values are sent as a Base64 encoded Basic Authorization header.

GenerateAccessToken
RefreshAccessToken
steps.oauth.v2.InvalidParameter 500 The policy must specify either an access token or an authorization code, but not both. GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
steps.oauth.v2.InvalidTokenType 500 The <Tokens>/<Token> element requires you to specify the token type (for example, refreshtoken). If the client passes the wrong type, this error is thrown. ValidateToken
InvalidateToken
steps.oauth.v2.MissingParameter 500 The response type is token, but no grant types are specified. GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
steps.oauth.v2.UnSupportedGrantType 500

The client specified a grant type that is unsupported by the policy (not listed in the <SupportedGrantTypes> element).

 GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken

JWT token-specific runtime errors

Runtime error codes and descriptions for JWT auth token flows depend on the OAuth2 flow context:

Error codes for JWT token generation and refresh flows

For OAuth2 flows that generate or refresh JWT tokens, error responses adhere to the error responses specified in RFC6749. For details, see Section 5.2 Error Response.

Error codes for the token verification flow

The error codes listed in the following table apply to VerifyAccessToken operation only.

Fault code HTTP status Cause Thrown by operations
oauth.v2.JWTSigningFailed 401 The policy was unable to sign the JWT.

GenerateJWTAccessToken
oauth.v2.InvalidValueForJWTAlgorithm 401 This occurs when the algorithm is not present in the JWT access token or when the value is not supported.

GenerateJWTAccessToken
VerifyJWTAccessToken

oauth.v2.InsufficientKeyLength 401 In Generation of JWT, for a key less than the minimum size for the HS384 or HS512 algorithms

GenerateJWTAccessToken
VerifyJWTAccessToken

oauth.v2.JWTAlgorithmMismatch 401 The algorithm specified in the Generate policy did not match the one expected in the Verify policy. The algorithms specified must match.

VerifyJWTAccessToken
oauth.v2.JWTDecodingFailed 401 The policy was unable to decode the JWT. The JWT is possibly corrupted.

VerifyJWTAccessToken
oauth.v2.MissingMandatoryClaimsInJWT 401 Occurs when the required claims are not present in the Jwt Access token

VerifyJWTAccessToken
oauth.v2.InvalidJWTSignature 401 This occurs when the signature of JWT access token could not be verified or when the signature is invalid.

VerifyJWTAccessToken
oauth.v2.InvalidTypeInJWTHeader 401 Occurs when the JWT's type is not at+Jwt

VerifyJWTAccessToken

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause
InvalidValueForExpiresIn

For the <ExpiresIn> element, valid values are positive integers.
InvalidValueForRefreshTokenExpiresIn For the <RefreshTokenExpiresIn> element, valid values are positive integers.
InvalidGrantType An invalid grant type is specified in the <SupportedGrantTypes> element. See the policy reference for a list of valid types.
ExpiresInNotApplicableForOperation Be sure that the operations specified in the <Operations> element support expiration. For example, the VerifyToken operation does not.
RefreshTokenExpiresInNotApplicableForOperation Be sure that the operations specified in the <Operations> element support refresh token expiration. For example, the VerifyToken operation does not.
GrantTypesNotApplicableForOperation Be sure that the grant types specified in <SupportedGrantTypes> are supported for the specified operation.
OperationRequired

You must specify an operation in this policy using the <Operation> element.
InvalidOperation

You must specify a valid operation in this policy using the <Operation> element.
TokenValueRequired You must specify a token <Token> value in the <Tokens> element.

JWT token-specific deployment errors

These deployment errors are specific to policies that use JWT token operations.

Error name Cause
InvalidValueForAlgorithm The algorithm specified in the <Algorithm> element is not among the list of available algorithms or is not present.
MissingKeyConfiguration The required <SecretKey>, <PrivateKey>, or <PublicKey> elements are missing, depending on which algorithm is used.
EmptyValueElementForKeyConfiguration The required child element <Value> is not defined in the <PrivateKey>, <PublicKey>, or <SecretKey> elements
InvalidKeyConfiguration The <PrivateKey> element is not used with RSA family algorithms or the <SecretKey> element is not used with HS Family algorithms.
EmptyRefAttributeForKeyconfiguration The ref attribute of the child element <Value> of the <PrivateKey>, <PublicKey> or <SecretKey> elements is empty.
InvalidVariableNameForKey The flow variable name specified in the ref attribute of the child element <Value> of the <PrivateKey>, <PublicKey> or <SecretKey> elements does not contain the private prefix.

Fault variables

These variables are set when this policy triggers an error at runtime.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name = "InvalidRequest"
oauthV2.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. oauthV2.GenerateAccesstoken.failed = true
oauthV2.policy_name.fault.name policy_name is the user-specified name of the policy that threw the fault. oauthV2.GenerateAccesstoken.fault.name = InvalidRequest
oauthV2.policy_name.fault.cause policy_name is the user-specified name of the policy that threw the fault. oauthV2.GenerateAccesstoken.cause = Required param : grant_type

Example error response

These responses are sent back to the client if the <GenerateResponse> element is true.

If <GenerateResponse> is true, the policy returns errors in this format for operations that generate tokens and codes. For a complete list, see see OAuth HTTP error response reference.

{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}

If <GenerateResponse> is true, the policy returns errors in this format for verify and validate operations. For a complete list, see see OAuth HTTP error response reference.

{  
   {  
      "fault":{  
         "faultstring":"Invalid Access Token",
         "detail":{  
            "errorcode":"keymanagement.service.invalid_access_token"
         }
      }
   }

Example fault rule

<FaultRule name="OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientResponse</Name>
        <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition>
    </Step>
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

I token in Storage sono sottoposti ad hashing

Se utilizzi Apigee hybrid o Apigee, i token di accesso e di aggiornamento OAuthV2 vengono sottoposti a hashing per impostazione predefinita quando vengono archiviati nel database Cassandra di runtime. L'hashing impedisce l'utilizzo dei token in caso di compromissione del database.

Utilizzo della configurazione OAuth predefinita

Ogni organizzazione (anche un'organizzazione di prova senza costi) su Apigee viene sottoposta al provisioning con un endpoint token OAuth. L'endpoint è preconfigurato con le policy nel proxy API denominato oauth. Puoi iniziare a utilizzare l'endpoint token non appena crei un account su Apigee. Per maggiori dettagli, vedi Informazioni sugli endpoint OAuth.

Eliminazione dei token di accesso

Per impostazione predefinita, i token OAuth2 vengono eliminati dal sistema Apigee 3 giorni (259.200 secondi) dopo la scadenza sia del token di accesso sia del token di aggiornamento (se esistente).

Argomenti correlati