Questa pagina si applica ad Apigee e Apigee hybrid.
Visualizza la documentazione di Apigee Edge.
Cosa
OAuthV2 è un criterio sfaccettato per l'esecuzione di operazioni relative ai tipi di concessione OAuth 2.0. Si tratta del criterio principale utilizzato per configurare gli endpoint OAuth 2.0 su Apigee.
Questo criterio è un criterio estensibile e il suo utilizzo potrebbe comportare implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni per l'utilizzo, consulta Tipi di criteri.
Per scoprire di più su OAuth su Apigee, consulta la home page di OAuth. Fornisce link a risorse, esempi, video e altro ancora.
Samples
VerifyAccessToken
VerifyAccessToken
Questa configurazione del criterio 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, l'elaborazione viene interrotta e viene restituito un errore nella risposta.
<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 API, come configurato nel 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, consulta Ottenere token OAuth 2.0. L'argomento include esempi di queste operazioni:
GenerateAuthorizationCode
Generare il codice di autorizzazione
Per esempi su come richiedere i codici di autorizzazione, consulta Richiedere un codice di autorizzazione.
RefreshAccessToken
Aggiornare un token di accesso
Per esempi che mostrano come richiedere token di accesso utilizzando un token di aggiornamento, consulta Aggiornare 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, consulta Utilizzare i 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 farlo 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 approvazione implicita. In questo caso, utilizzeremo il tipo di autorizzazione con password per generare il token. Come vedrai, il trucco per far funzionare questa operazione è passare un'intestazione di richiesta di autorizzazione con un criterio JavaScript.
Innanzitutto, diamo un'occhiata al 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 questo criterio nel flusso di risposta, l'operazione non andrà a buon fine con un errore 401 Non autorizzato anche se i parametri di accesso corretti sono specificati nel criterio. Per risolvere il problema, devi impostare un'intestazione di richiesta di autorizzazione.
L'intestazione Authorization deve contenere uno schema di accesso di base con il valore client_id:client_secret codificato in Base64.
Puoi aggiungere questa intestazione con un criterio JavaScript posizionato appena prima del criterio OAuthV2, come mostrato di seguito. 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)));
Consulta anche Codificare le credenziali di autenticazione di base.
Riferimento elemento
Il riferimento ai criteri descrive gli elementi e gli attributi dei criteri OAuthV2.
Il criterio di esempio mostrato di seguito è una delle molte configurazioni possibili. Questo esempio mostra un criterio OAuthV2 configurato per l'operazione GenerateAccessToken. Sono inclusi elementi obbligatori e facoltativi. Per maggiori 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 | Presenza |
---|---|---|---|
name |
Il nome interno del criterio. Il valore dell'attributo Se vuoi, utilizza l'elemento |
N/D | Obbligatorio |
continueOnError |
Imposta su Imposta su |
falso | Facoltativo |
enabled |
Imposta su Imposta |
true | Facoltativo |
async |
Questo attributo è stato ritirato. |
falso | Ritirato |
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 |
---|---|
Presenza | Facoltativo |
Tipo | Stringa |
Elemento <AccessToken>
<AccessToken>request.header.access_token</AccessToken>
Per impostazione predefinita, quando Operation
è VerifyAccessToken
, il criterio
si aspetta che il token di accesso venga inviato nell'intestazione Authorization
come token bearer, ovvero con un 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, per impostazione predefinita il criterio 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 API, come configurato nel sistema Apigee.
Predefinito |
N/D |
Presenza |
Facoltativo |
Tipo | Stringa |
Valori validi |
qualsiasi nome di variabile |
Utilizzato con le operazioni |
|
Elemento <AccessTokenPrefix>
<AccessTokenPrefix>Prefix</AccessTokenPrefix>
Per impostazione predefinita, quando Operation
è VerifyAccessToken
, il criterio
si aspetta che il token di accesso venga inviato nell'intestazione Authorization
come token bearer, ovvero con un 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 estrarrà quindi il token di accesso in entrata dall'intestazione della richiesta token
,
nel seguente modo: se l'intestazione inizia con la parola "KEY" seguita da uno spazio, il criterio rimuoverà il prefisso e lo spazio e interpreterà il valore rimanente come token di accesso. Se il prefisso specificato non è presente nell'intestazione, il criterio genera un errore.
Se specifichi l'elemento AccessToken
e non specifichi l'elemento
AccessTokenPrefix
, il criterio 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 |
-none- |
Presenza |
Facoltativo |
Tipo | Stringa |
Valori validi |
qualsiasi stringa |
Utilizzato con le operazioni |
|
<Algorithm>
<Algorithm>algorithm-here</Algorithm>
Specifica l'algoritmo di crittografia utilizzato per firmare un token di accesso JWT. Gli algoritmi RSA (RS*) impiegano 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 se 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 debba 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
. Ad esempio, per richiedere AppEndUser in un'intestazione HTTP, 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 ulteriori informazioni, consulta Attivare il recupero e la revoca dei token di accesso OAuth 2.0 in base all'ID utente finale, all'ID app o a entrambi.
Predefinito |
N/D |
Presenza |
Facoltativo |
Tipo | Stringa |
Valori validi |
Qualsiasi variabile di flusso accessibile al criterio in fase di esecuzione. |
Utilizzato con i tipi di concessione |
|
<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 possa essere estratto e controllato in fase di esecuzione.
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 del flusso. Se la variabile non può essere risolta, la stringa è predefinita.
Per ulteriori informazioni sull'utilizzo di questo elemento, consulta Personalizzare i token e i codici di autorizzazione.
Mostrare o nascondere gli attributi personalizzati nella risposta
Ricorda che se imposti l'elemento GenerateResponse di questo criterio su true, la rappresentazione JSON completa del token viene restituita nella risposta, inclusi eventuali attributi personalizzati impostati. 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 conservato. Supponiamo che tu generi 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 accade perché Apigee non ricorda che
l'attributo display
è stato impostato originariamente su false
nel criterio di generazione del token di accesso. L'attributo personalizzato fa semplicemente parte dei metadati del token di accesso.
Lo stesso comportamento si verifica se aggiungi attributi personalizzati a un codice di autorizzazione: quando viene generato un token di accesso utilizzando questo codice, gli attributi personalizzati vengono visualizzati nella risposta del token di accesso. Anche in questo caso, questo 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 nel criterio del token di aggiornamento e imposta la loro visualizzazione su false. In questo caso, potrebbe essere necessario recuperare i valori personalizzati originali dall'attributo access token originale utilizzando il criterio GetOAuthV2Info.
- Utilizza un criterio JavaScript di post-elaborazione per estrarre manualmente gli attributi personalizzati che non vuoi visualizzare nella risposta.
Consulta anche Personalizzare token e codici di autorizzazione.
Predefinito |
|
Presenza |
Facoltativo |
Valori validi |
|
Utilizzato con i tipi di concessione |
|
Elemento <CacheExpiryInSeconds>
<CacheExpiryInSeconds ref="propertyset.settings.token-ttl">60</CacheExpiryInSeconds>
Questo elemento può essere utilizzato solo con l'operazione VerifyAccessToken
. Specifica
il time-to-live (TTL) nella cache dell'token di accesso per l'esecuzione del determinato criterio. La primeira volta che Apigee verifica un token di accesso OAuth 2, deve recuperarlo da un accumulo permanente. Si tratta di un'operazione relativamente costosa, pertanto Apigee memorizza nella cache il risultato della ricerca del token, incluso lo stato del token, l'elenco dei prodotti per i quali è valido e gli eventuali attributi personalizzati associati al token. Le invocazioni successive di
OAuthV2/VerifyAccessToken
fino allo scadere del TTL leggeranno il risultato memorizzato nella cache in memoria, il che significa che la verifica del token sarà molto più rapida.
Il TTL predefinito per la cache del token di accesso è 180 secondi. Questo elemento ti consente di ridurre questo TTL, sacrificando il rendimento in favore della correttezza. Un esempio in cui questa operazione 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 questa 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 la data e l'ora di scadenza in secondi. |
Utilizzato con le operazioni |
|
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 specificato, 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.
Consulta anche Ottenere i token OAuth 2.0.
Predefinito |
request.formparam.client_id (un valore x-www-form-urlencoded 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 |
Può essere utilizzato anche con l'operazione GenerateAuthorizationCode. |
Elemento <Code>
<Code>request.queryparam.code</Code>
Nel flusso del tipo di concessione dell'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 (valore predefinito).
La variabile request.queryparam.auth_code
indica che il codice di autorizzazione deve essere presente come parametro di query, ad esempio ?auth_code=AfGlvs9
. Ad esempio, per richiedere il codice di autorizzazione in un'intestazione HTTP, imposta questo valore su request.header.auth_code
. Consulta anche
Ottenere i token OAuth 2.0.
Predefinito |
request.formparam.code (un valore 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 la data e l'ora di scadenza dei token di accesso e dei codici di autorizzazione in millisecondi. Per i token di aggiornamento, utilizza <RefreshTokenExpiresIn>
. Il valore dell'ora di scadenza è un valore generato dal sistema più il valore <ExpiresIn>
. Se <ExpiresIn>
è impostato su -1, il token o il codice scade in base alla scadenza massima del token di accesso OAuth. Se <ExpiresIn>
non è specificato, il sistema applica un valore predefinito configurato a livello di sistema.
La data e l'ora di scadenza possono essere impostate anche in fase di esecuzione 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 di valori chiave, recuperarlo, assegnarlo a una variabile e farvi riferimento nel criterio. Ad esempio,
kvm.oauth.expires_in
.
Apigee mantiene memorizzate nella cache le seguenti entità per un minimo di 180 secondi dopo che sono state accese.
- Token di accesso OAuth. Ciò significa che l'elemento
ExpiresIn
del 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 sui token OAuth e sulle entità KMS.
La stanza seguente specifica una variabile di flusso e 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 è описана в questo post della community di Apigee.
Per impostazione predefinita, i token di accesso scaduti vengono eliminati automaticamente dal sistema Apigee Apigee 3 giorni dopo la scadenza. Vedi anche Eseguire la pulizia 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 |
|
Utilizzato con i tipi di concessione |
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
. Ad esempio, per richiedere il token di accesso esterno in un'intestazione HTTP, imposta questo valore su request.header.external_access_token
. Consulta anche Utilizzare i token OAuth di terze parti.
Elemento <ExternalAuthorization>
<ExternalAuthorization>true</ExternalAuthorization>
Se questo elemento è falso o non è presente, Apigee convalida client_id e client_secret normalmente rispetto allo store di autorizzazione Apigee. Utilizza questo elemento quando vuoi utilizzare token OAuth di terze parti. Per informazioni dettagliate sull'utilizzo di questo elemento, consulta Utilizzare i token OAuth di terze parti.
Predefinito |
falso |
Presenza |
Facoltativo |
Tipo | Booleano |
Valori validi | true o false |
Utilizzato con i tipi di concessione |
|
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
. Consulta anche Utilizzare i 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
. Ad esempio, per richiedere il token di aggiornamento esterno
in un'intestazione HTTP, imposta questo valore su request.header.external_refresh_token
. Consulta anche Utilizzare i 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 alla seguente:
{ "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. Al contrario, un insieme di variabili di flusso viene compilato con valori correlati alla funzione del criterio. Ad esempio, una variabile di flusso denominata
oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code
viene compilata con il codice di autorizzazione appena creato. Tieni presente che expires_in è espresso in secondi nella risposta.
Predefinito |
true |
Presenza |
Facoltativo |
Tipo | string |
Valori validi | true o false |
Utilizzato con i tipi di concessione |
|
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. Al contrario, un insieme di variabili di flusso viene compilato con valori correlati alla funzione del criterio.
Predefinito |
falso |
Presenza |
Facoltativo |
Tipo | string |
Valori validi | true o false |
Utilizzato con i tipi di concessione |
|
<GrantType>
<GrantType>request.queryparam.grant_type</GrantType>
Indica al criterio 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 di modulo (predefinito).
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
. Consulta anche Ottenere i token OAuth 2.0.
Predefinito |
request.formparam.grant_type (un valore 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 |
|
Elemento <Operation>
<Operation>GenerateAuthorizationCode</Operation>
L'operazione OAuth 2.0 eseguita dal criterio.
Predefinito |
Se |
Presenza |
Facoltativo |
Tipo | Stringa |
Valori validi |
Operazioni aggiuntive sui token di accesso JWT Se preferisci utilizzare token di accesso JWT anziché token di stringa opaci, sono disponibili anche le seguenti operazioni per generare e convalidare i token JWT. Per maggiori dettagli, consulta Utilizzare le operazioni sui token OAuth JWT:
|
Elemento <PassWord>
<PassWord>request.queryparam.password</PassWord>
Questo elemento viene utilizzato solo con il tipo di autorizzazione con password. Con il tipo di concessione della password, le credenziali utente (password e nome utente) devono essere rese disponibili per il 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 si aspetta 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 passare la password in una richiesta di token utilizzando un parametro di query e impostare l'elemento come segue:
<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 del criterio di generazione del token.
Consulta anche Ottenere i token OAuth 2.0.
Predefinito |
request.formparam.password (un valore x-www-form-urlencoded specificato nel corpo della richiesta) |
Presenza |
Facoltativo |
Tipo | Stringa |
Valori validi | Qualsiasi variabile di flusso disponibile per il criterio in fase di esecuzione. |
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 i 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 ulteriori informazioni, consulta la sezione Utilizzare le operazioni sui token OAuth JWT.
Predefinito | N/D |
Presenza | Obbligatorio quando il valore dell'elemento Algorithm è uno di
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 su un token di accesso in formato JWT firmato con un algoritmo RSA. Utilizza l'attributo ref
per
passare 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 stringa o una variabile di flusso. |
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 il codice di autorizzazione e i tipi di autorizzazione impliciti. 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 nell'app per sviluppatori associata alle chiavi client della richiesta e se
redirect_uri
è presente nella richiesta, i due elementi devono corrispondere esattamente. Se non corrispondono, viene restituito un errore. Per informazioni su come registrare le app per sviluppatori su Apigee e specificare un URL di callback, consulta Registrare le 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,
redirect_uri
è obbligatorio. 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 Ottenere token OAuth 2.0.
Predefinito |
request.formparam.redirect_uri (un valore 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 esecuzione |
Utilizzato con i tipi di concessione |
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 di modulo (valore predefinito).
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
. Ad esempio, per richiedere il token di aggiornamento in un'intestazione HTTP, imposta questo valore su request.header.refresh_token
. Consulta anche Ottenere token OAuth 2.0.
Predefinito |
request.formparam.refresh_token (un valore 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 esecuzione |
Utilizzato con i tipi di concessione |
|
Elemento <RefreshTokenExpiresIn>
<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>
Applica la scadenza dei token di aggiornamento in millisecondi. Il valore della data e dell'ora di scadenza è un valore generato dal sistema più il valore <RefreshTokenExpiresIn>
. Se <RefreshTokenExpiresIn>
è impostato su -1, il token di aggiornamento scade in base alla scadenza massima del token di aggiornamento OAuth. Se <RefreshTokenExpiresIn>
non è specificato, il sistema applica il valore predefinito.
La data e l'ora di scadenza possono essere impostate anche in fase di esecuzione 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 di valori chiave, recuperarlo, assegnarlo a una variabile e farvi riferimento nel criterio. Ad esempio, kvm.oauth.expires_in
.
La stanza seguente specifica una variabile di flusso e un valore predefinito. Tieni presente che il valore della variabile flow ha la precedenza sul valore predefinito specificato.
<RefreshTokenExpiresIn ref="kvm.oauth.expires_in"> 86400000 <!--value in milliseconds--> </RefreshTokenExpiresIn>
Predefinito |
2592000000 ms (30 giorni) (in vigore dal 31 maggio 2023) |
Presenza |
Facoltativo |
Tipo | Numero intero |
Valori validi |
|
Utilizzato con i tipi di concessione |
|
Elemento <ResponseType>
<ResponseType>request.queryparam.response_type</ResponseType>
Questo elemento indica ad Apigee il tipo di concessione richiesto dall'app client. Viene utilizzato solo con i flussi di tipo di autorizzazione e codice di autorizzazione impliciti.
Per impostazione predefinita, Apigee cerca il valore del tipo di risposta in un parametro della 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
passare nell'intestazione della richiesta. Consulta anche Ottenere i token OAuth 2.0.
Predefinito |
request.formparam.response_type (un valore x-www-form-urlencoded specificato nel corpo della richiesta) |
Presenza |
Facoltativo. Utilizza questo elemento se vuoi sostituire il comportamento predefinito. |
Tipo | Stringa |
Valori validi | code (per il tipo di autorizzazione con codice di autorizzazione) o token
(per il tipo di autorizzazione implicita) |
Utilizzato con i tipi di concessione |
|
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 |
|
Presenza |
facoltativo |
Tipo | boolean |
Valori validi |
|
Utilizzato con i tipi di concessione |
|
Elemento <RFCCompliantRequestResponse>
<RFCCompliantRequestResponse>[true | false]</RFCCompliantRequestResponse>
Se true
, il criterio è conforme agli standard RFC6749 e abilita i seguenti comportamenti conformi:
- Le risposte con errori e senza errori includeranno il campo dell'intestazione della risposta HTTP
Cache-Control
per rispettare il protocollo RFC2616 (Hypertext Transfer Protocol - HTTP/1.1), con un valoreno-store
in qualsiasi risposta contenente token, credenziali o altre informazioni sensibili, nonché il campo dell'intestazione della rispostaPragma
con un valoreno-cache
. - La proprietà
expires_in
sarà in formato alfanumerico. Per coerenza, ancherefresh_token_expires_in
sarà alfanumerico. - Le risposte OAuthV2 per la generazione di token includeranno il campo dell'intestazione
Bearer
conforme allo standard RFC anzichéBearerToken
. - I messaggi di errore nei payload di risposta avranno il seguente formato:
{"error" : "xxx", "error_description" :"yyy"}
per gli errori relativi ai token di aggiornamento.
Predefinito |
|
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. Utilizza solo
se l'algoritmo è uno dei seguenti: HS256, HS384 o HS512. Utilizza l'attributo ref
per passare la chiave in una variabile di flusso. Per ulteriori informazioni, consulta la sezione Utilizzare le operazioni sui token OAuth JWT.
Apigee applica una robustezza minima della chiave per gli algoritmi HS256/HS384/HS512. La lunghezza minima della chiave per HS256 è 32 byte, per HS384 è 48 byte e per HS512 è 64 byte. L'utilizzo di una chiave con un'intensità 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 a cui concedere il token o il codice. Questi valori vengono solitamente passati al criterio nella richiesta da un'app client. Puoi configurare l'elemento in modo che accetti una variabile di flusso, dandoti la possibilità di scegliere come vengono trasmessi gli ambiti in una richiesta. Nel
seguente esempio, 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 "hard coded", non puoi utilizzare variabili. Ad esempio:
<Scope>A B</Scope>
Consulta anche Utilizzo degli ambiti OAuth2 e Ottenere token OAuth 2.0.
Predefinito |
Nessun ambito |
Presenza |
Facoltativo |
Tipo | Stringa |
Valori validi |
Se utilizzata con i criteri Generate*, una variabile di flusso. Se utilizzato con VerifyAccessToken, un elenco di nomi di ambito (stringhe) separati da spazi. |
Utilizzato con i tipi di concessione |
|
Elemento <State>
<State>request.queryparam.state</State>
Nei casi in cui l'app client debba inviare le informazioni sullo stato al server di autorizzazione, questo elemento consente di specificare dove Apigee deve cercare i valori dello 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 impedire 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
. Consulta anche Ottenere 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 |
|
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 | true o false |
Utilizzato con i tipi di concessione |
|
Elemento <SupportedGrantTypes>/<GrantType>
<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 del token OAuth su Apigee. Un endpoint può supportare più tipi di concessioni, ovvero un singolo endpoint può essere configurato per distribuire token di accesso per più tipi di concessioni. 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 concessione supportati, gli unici tipi di concessione consentiti sono
authorization_code
e implicit
. Consulta anche l'elemento <GrantType>, che è un elemento di livello superiore utilizzato per specificare dove Apigee deve cercare il parametro grant_type
passato in una richiesta del client. Apigee si assicurerà che il valore del parametro grant_type
sia uguale a uno dei tipi di concessione supportati.
Predefinito |
authorization _code e implicit |
Presenza |
Obbligatorio |
Tipo | Stringa |
Valori validi |
|
Elemento <Tokens>/<Token>
Utilizzato con le operazioni ValidateToken e InvalidateToken. Consulta anche Approvare e revocare i 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 ricerca denominati access_token
, ad esempio, devono utilizzare request.queryparam.access_token
.
Elemento <UserName>
<UserName>request.queryparam.user_name</UserName>
Questo elemento viene utilizzato solo con il tipo di autorizzazione con password. Con il tipo di concessione della password, le credenziali utente (password e nome utente) devono essere rese disponibili per il 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 si aspetta 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 passare il nome utente in un parametro di query e impostare l'elemento <UserName>
come segue:
<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 del criterio di generazione del token.
Consulta anche Ottenere 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, un criterio OAuthV2 corrispondente che
specifica l'operazione VerifyAccessToken
viene associato al flusso che espone la
risorsa protetta.
Ad esempio, per garantire che tutte le richieste a un'API siano autorizzate, il seguente criterio 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 siano verificate, collega il criterio al PreFlow della richiesta ProxyEndpoint come segue:
<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 andrà a buon fine se nel token di accesso è presente almeno uno degli scopi elencati. Ad esempio, il seguente criterio 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 si prevede che si trovi il token di accesso. Ad esempio,
request.queryparam.accesstoken . Per impostazione predefinita, il token di accesso dovrebbe essere presentato dall'app nell'intestazione HTTP Authorization, in base alla specifica OAuth 2.0. Utilizza questa
impostazione se si prevede 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. |
Consulta anche Verificare i token di accesso e Ottenere i token OAuth 2.0.
Specificare le posizioni delle variabili di richiesta
Per ogni tipo di concessione, il criterio fa delle supposizioni 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 ciascun parametro. Ad esempio, quando gestisci un codice di autorizzazione, puoi specificare la posizione del codice di autorizzazione, l'ID client, l'URI di reindirizzamento e l'ambito. Questi possono essere specificati come intestazioni HTTP, parametri di ricerca o parametri di modulo.
L'esempio seguente mostra come specificare la posizione dei parametri obbligatori del codice di autorizzazione 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 dei clienti, 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 località per parametro.
Variabili di flusso
Le variabili di flusso definite in questa tabella vengono compilate quando vengono eseguiti i rispettivi criteri OAuth e, di conseguenza, sono disponibili per altri criteri o applicazioni in esecuzione nel flusso del proxy API.
Operazione VerifyAccessToken
Quando viene eseguita l'operazione VerifyAccessToken, viene compilato un numero elevato di variabili di flusso nel contesto di esecuzione del proxy. Queste variabili forniscono proprietà relative al token di accesso, all'app per sviluppatori e allo sviluppatore. Puoi utilizzare un criterio AssignMessage o JavaScript, ad esempio, per leggere una di queste variabili e utilizzarla in base alle esigenze in un secondo momento nel flusso. Queste variabili possono essere utili anche per scopi di debug.
Variabili specifiche per token
Variabili | Descrizione |
---|---|
organization_name |
Il nome dell'organizzazione in cui viene eseguito il proxy. |
developer.id |
L'ID dello sviluppatore o del 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 dell'epoca di 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, nelle variabili di risposta e di flusso del token 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 della revoca del token di accesso. Non supportato per l'operazione Il valore può essere |
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 per AppGroup
Le seguenti variabili di flusso contenenti informazioni sul
AppGroup
per il token e che vengono compilate dal criterio. Questi attributi AppGroup vengono compilati solo se
verifyapikey.{policy_name}.app.appType
è "AppGroup".
Variabili | Descrizione |
---|---|
appgroup.displayName |
Il nome visualizzato di AppGroup. |
appgroup.name |
Nome del gruppo di app. |
appgroup.id |
L'ID gruppo di app. |
appOwnerStatus |
Lo stato del proprietario dell'app: "active", "inactive" o "login_lock". |
created_at |
Il timestamp della data/dell'ora di creazione del gruppo di app. |
created_by |
L'indirizzo email dello sviluppatore che ha creato il gruppo di app. |
last_modified_at |
Il timestamp della data/dell'ora dell'ultima modifica di AppGroup. |
last_modified_by |
L'indirizzo email dello sviluppatore che ha modificato per ultimo il gruppo di app. |
{appgroup_custom_attributes} |
Qualsiasi attributo AppGroup personalizzato. Specifica il nome dell'attributo personalizzato. |
Variabili specifiche per lo sviluppatore
Se app.appType
è "Sviluppatore", gli attributi dello sviluppatore vengono compilati.
Variabili | Descrizione |
---|---|
Variabili specifiche per lo sviluppatore | |
developer.id |
|
developer.userName |
|
developer.firstName |
|
developer.lastName |
|
developer.email |
|
developer.status |
attive o non attive |
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 quando viene eseguito il criterio. |
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 di 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 cliente dell'app per sviluppatori 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 Utilizzo degli ambiti OAuth2. |
status |
approved o revoked . |
token_type |
È impostato su BearerToken . |
developer.email |
L'indirizzo email dello sviluppatore registrato che possiede l'app sviluppatore 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 del 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 stringa della quantità del timestamp a 32 bit corrispondente. Ad esempio, "Wed, 21 Aug 2013 19:16:47 UTC" corrisponde al valore del timestamp di 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 quando viene eseguito il criterio. |
oauthv2accesstoken.{policy_name}.expires_in |
Il valore di scadenza del token, in secondi. Per maggiori dettagli, consulta l'elemento <ExpiresIn>. |
Riferimento all'errore
Questa sezione descrive i codici di errore e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta Informazioni importanti sugli errori relativi alle norme e Gestione degli errori.
Errori di runtime
Questi errori possono verificarsi durante l'esecuzione del criterio.
Codice guasto | Stato HTTP | Causa | Lanciato dalle operazioni |
---|---|---|---|
steps.oauth.v2.access_token_expired |
401 |
Il token di accesso è scaduto. |
|
steps.oauth.v2.access_token_not_approved |
401 |
Il token di accesso è stato revocato. | VerifyAccessToken |
steps.oauth.v2.apiresource_doesnot_exist |
401 |
La risorsa richiesta non esiste in nessuno dei prodotti API associati al token di accesso. | VerifyAccessToken |
steps.oauth.v2.FailedToResolveAccessToken |
500 |
Il criterio si aspettava di trovare un token di accesso in una variabile specificata nell'elemento
<AccessToken> , ma non è stato possibile risolvere la variabile. |
GenerateAccessToken |
steps.oauth.v2.FailedToResolveAuthorizationCode |
500 |
Il criterio si aspettava di trovare un codice di autorizzazione in una variabile specificata nell'elemento
<Code> , ma non è stato possibile risolvere la variabile. |
GenerateAuthorizationCode |
steps.oauth.v2.FailedToResolveClientId |
500 |
Il criterio si aspettava di trovare l'ID cliente in una variabile specificata nell'elemento
<ClientId> , ma non è stato possibile risolvere la variabile. |
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
steps.oauth.v2.FailedToResolveRefreshToken |
500 |
Il criterio si aspettava di trovare un token di aggiornamento in una variabile specificata nell'elemento
<RefreshToken> , ma non è stato possibile risolvere la variabile. |
RefreshAccessToken |
steps.oauth.v2.FailedToResolveToken |
500 |
Il criterio si aspettava di trovare un token in una variabile specificata nell'elemento
<Tokens> , ma non è stato possibile risolvere la variabile. |
|
steps.oauth.v2.InsufficientScope |
403 | Il token di accesso presentato nella richiesta ha un ambito che non corrisponde all'ambito specificato nel criterio di verifica del token di accesso. Per saperne di più sugli ambiti, consulta Utilizzo degli ambiti OAuth2. | VerifyAccessToken |
steps.oauth.v2.invalid_access_token |
401 |
Il token di accesso inviato dal client non è valido. | VerifyAccessToken |
steps.oauth.v2.invalid_client |
401 |
Questo nome dell'errore viene restituito quando la proprietà |
GenerateAccessToken RefreshAccessToken |
steps.oauth.v2.invalid_request |
400 | Questo nome di errore viene utilizzato per più tipi di errori, in genere per parametri mancanti o errati inviati nella richiesta. Se <GenerateResponse> è impostato su false , utilizza le variabili di guasto (descritte di seguito) per recuperare i dettagli sull'errore, ad esempio il nome e la causa del guasto. |
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
steps.oauth.v2.InvalidAccessToken |
401 |
L'intestazione di autorizzazione non contiene la parola Bearer , che è obbligatoria. Ad esempio: Authorization: Bearer your_access_token |
VerifyAccessToken |
steps.oauth.v2.InvalidAPICallAsNo\ |
401 |
Il proxy o l'operazione dell'API attualmente in esecuzione non è nel prodotto associato al token di accesso. Suggerimenti:assicurati che il prodotto associato al token di accesso sia configurato correttamente. Ad esempio, se utilizzi caratteri jolly nei percorsi delle risorse, assicurati che vengano utilizzati correttamente. Per maggiori dettagli, consulta Gestione dei prodotti API. Consulta anche La verifica del token di accesso OAuth2.0 genera l'errore "Richiesta API non valida perché non è stata trovata alcuna corrispondenza per apiproduct" per ulteriori indicazioni sulle cause di questo errore. |
VerifyAccessToken |
steps.oauth.v2.InvalidClientIdentifier |
500 |
Questo nome dell'errore viene restituito quando la proprietà |
|
steps.oauth.v2.InvalidParameter |
500 |
Il criterio deve specificare un token di accesso o un codice di autorizzazione, ma non entrambi. | GenerateAuthorizationCode GenerateAccessTokenImplicitGrant |
steps.oauth.v2.InvalidTokenType |
500 |
L'elemento <Tokens>/<Token> richiede di specificare il tipo di token (ad esempio refreshtoken ). Se il client passa il tipo errato, viene generato questo errore. |
ValidateToken InvalidateToken |
steps.oauth.v2.MissingParameter |
500 |
Il tipo di risposta è token , ma non sono specificati tipi di concessione. |
GenerateAuthorizationCode GenerateAccessTokenImplicitGrant |
steps.oauth.v2.UnSupportedGrantType |
500 |
Il client ha specificato un tipo di concessione non supportato dalle norme (non elencato nell'elemento
|
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
Errori di runtime specifici del token JWT
I codici e le descrizioni degli errori di runtime per i flussi di token di autenticazione JWT dipendono dal contesto del flusso OAuth2:
- Se il contesto del flusso è la generazione o l'aggiornamento del token, consulta Codici di errore per i flussi di generazione e aggiornamento dei token JWT di seguito.
- Per il flusso di verifica del token, consulta la sezione Codici di errore per i flussi di verifica del token di seguito.
Codici di errore per i flussi di generazione e aggiornamento dei token JWT
Per i flussi OAuth2 che generano o aggiornano i token JWT, le risposte di errore devono rispettare quelle specificate in RFC6749. Per maggiori dettagli, consulta la sezione 5.2 Risposta di errore.
Codici di errore per il flusso di verifica del token
I codici di errore elencati nella tabella seguente si applicano solo all'operazione VerifyAccessToken.
Codice guasto | Stato HTTP | Causa | Lanciato dalle operazioni |
---|---|---|---|
oauth.v2.JWTSigningFailed |
401 |
Il criterio non è riuscito a firmare il JWT. |
|
oauth.v2.InvalidValueForJWTAlgorithm |
401 |
Questo accade quando l'algoritmo non è presente nel token di accesso JWT o quando il valore non è supportato. |
|
oauth.v2.InsufficientKeyLength |
401 |
Nella generazione di JWT, per una chiave inferiore alle dimensioni minime per gli algoritmi HS384 o HS512 |
|
oauth.v2.JWTAlgorithmMismatch |
401 |
L'algoritmo specificato nel criterio Genera non corrisponde a quello previsto nel criterio Verifica. Gli algoritmi specificati devono corrispondere. |
|
oauth.v2.JWTDecodingFailed |
401 |
Il criterio non è riuscito a decodificare il JWT. Il JWT potrebbe essere danneggiato. |
|
oauth.v2.MissingMandatoryClaimsInJWT |
401 |
Si verifica quando i claim richiesti non sono presenti nel token di accesso JWT |
|
oauth.v2.InvalidJWTSignature |
401 |
Ciò si verifica quando non è stato possibile verificare la firma del token di accesso JWT o quando la firma non è valida. |
|
oauth.v2.InvalidTypeInJWTHeader |
401 |
Si verifica quando il tipo di JWT non è at+Jwt |
|
Errori di deployment
Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.
Nome dell'errore | Causa |
---|---|
InvalidValueForExpiresIn |
Per l'elemento |
InvalidValueForRefreshTokenExpiresIn |
Per l'elemento <RefreshTokenExpiresIn> , i valori validi sono numeri interi positivi e -1 . |
InvalidGrantType |
Nell'elemento <SupportedGrantTypes>
è specificato un tipo di concessione non valido. Consulta il riferimento alle norme per un elenco dei tipi validi. |
ExpiresInNotApplicableForOperation |
Assicurati che le operazioni specificate nell'elemento <Operations> supportino la scadenza. Ad esempio, l'operazione VerifyToken non lo fa. |
RefreshTokenExpiresInNotApplicableForOperation |
Assicurati che le operazioni specificate nell'elemento <Operations> supportino la scadenza del
token di aggiornamento. Ad esempio, l'operazione VerifyToken non lo fa. |
GrantTypesNotApplicableForOperation |
Assicurati che i tipi di concessione specificati in <SupportedGrantTypes> siano supportati per
l'operazione specificata. |
OperationRequired |
Devi specificare un'operazione in questo criterio utilizzando l'elemento |
InvalidOperation |
Devi specificare un'operazione valida in questo criterio utilizzando l'elemento
|
TokenValueRequired |
Devi specificare un valore del token <Token> nell'elemento
<Tokens> . |
Errori di deployment specifici per i token JWT
Questi errori di deployment sono specifici dei criteri che utilizzano le operazioni sui token JWT.
Nome dell'errore | Causa |
---|---|
InvalidValueForAlgorithm |
L'algoritmo specificato nell'elemento <Algorithm> non è
presente nell'elenco degli algoritmi disponibili o non è presente. |
MissingKeyConfiguration |
Gli elementi <SecretKey> , <PrivateKey> o
<PublicKey> obbligatori mancano, a seconda dell'algoritmo utilizzato. |
EmptyValueElementForKeyConfiguration |
L'elemento secondario obbligatorio <Value> non è definito negli elementi
<PrivateKey> , <PublicKey> o <SecretKey> |
InvalidKeyConfiguration |
L'elemento <PrivateKey> non viene utilizzato con gli algoritmi della famiglia RSA o l'elemento <SecretKey>
non viene utilizzato con gli algoritmi della famiglia HS. |
EmptyRefAttributeForKeyconfiguration |
L'attributo ref dell'elemento secondario <Value> degli elementi <PrivateKey> , <PublicKey> o <SecretKey> è vuoto. |
InvalidVariableNameForKey |
Il nome della variabile di flusso specificato nell'attributo ref dell'elemento secondario <Value> degli elementi <PrivateKey> , <PublicKey> o <SecretKey> non contiene il prefisso private . |
Variabili di errore
Queste variabili vengono impostate quando questo criterio attiva un errore in fase di runtime.
Variabili | Dove | Esempio |
---|---|---|
fault.name="fault_name" |
fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime sopra. Il nome dell'errore è l'ultima parte del codice dell'errore. | fault.name = "invalid_request" |
oauthV2.policy_name.failed |
policy_name è il nome specificato dall'utente del criterio che ha generato l'errore. | oauthV2.GenerateAccesstoken.failed = true |
oauthV2.policy_name.fault.name |
policy_name è il nome specificato dall'utente del criterio che ha generato l'errore. | oauthV2.GenerateAccesstoken.fault.name = invalid_request
|
oauthV2.policy_name.fault.cause |
policy_name è il nome specificato dall'utente del criterio che ha generato l'errore. | oauthV2.GenerateAccesstoken.cause = Required param : grant_type |
Esempio di risposta di errore
Queste risposte vengono inviate al client se l'elemento <GenerateResponse>
è true.
Se <GenerateResponse>
è true, il criterio restituisce errori in questo formato per le operazioni che generano token e codici. Per un elenco completo, consulta
Riferimento alle risposte di errore HTTP OAuth.
{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}
Se <GenerateResponse>
è true, il criterio restituisce errori in questo formato per le operazioni di verifica e convalida. Per un elenco completo, consulta la documentazione di riferimento per le risposte di errore HTTP OAuth.
{ { "fault":{ "faultstring":"Invalid Access Token", "detail":{ "errorcode":"keymanagement.service.invalid_access_token" } } }
Esempio di regola di errore
<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 nello spazio di archiviazione sono sottoposti ad hashing
Se utilizzi Apigee Hybrid o Apigee, i token di accesso e di aggiornamento OAuth 2.0 vengono sottoposti ad hashing per impostazione predefinita quando vengono archiviati nel database Cassandra di runtime. L'hashing impedisce l'utilizzo dei token se il database viene compromesso.
Utilizzo della configurazione OAuth predefinita
Per ogni organizzazione (anche per quelle con prova gratuita) su Apigee viene eseguito il provisioning di un endpoint del token OAuth. L'endpoint è preconfigurato con i criteri nel proxy API chiamato oauth. Puoi iniziare a utilizzare l'endpoint del token non appena crei un account su Apigee. Per maggiori dettagli, vedi Informazioni sugli endpoint OAuth.
Pulizia dei token di accesso
Per impostazione predefinita, i token OAuth2 vengono eliminati dal sistema Apigee 3 giorni (259200 secondi) dopo la scadenza sia del token di accesso sia del token di aggiornamento (se esistente).
Comportamento non conforme allo standard RFC
Per impostazione predefinita, il criterio OAuthV2, con l'operazione GenerateAccessToken, restituisce una risposta del token che contiene determinate proprietà non conformi allo standard RFC. La tabella seguente mostra le proprietà non conformi restituite dal criterio OAuthV2 e le proprietà conformi corrispondenti.
OAuthV2 restituisce: | La proprietà conforme a RFC è: |
---|---|
"token_type":"BearerToken" |
"token_type":"Bearer"
|
"expires_in":"3600" |
"expires_in":3600
Il valore conforme è un numero, non una stringa. |
Inoltre, la risposta di errore per un token di aggiornamento scaduto quando grant_type = refresh_token
è:
{"ErrorCode" : "invalid_request", "Error" :"Refresh Token expired"}
Tuttavia, la risposta conforme allo standard RFC è:
{"error" : "invalid_grant", "error_description" :"refresh token expired"}