Questa pagina si applica ad Apigee e Apigee hybrid.
Visualizza la documentazione di Apigee Edge.
Cosa
OAuthV2 è un criterio multiforme per eseguire operazioni relative al tipo di autorizzazione OAuth 2.0. Questo è il criterio principale utilizzato per configurare gli endpoint OAuth 2.0 su Apigee.
Questo criterio è un criterio estendibile e il suo utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni di utilizzo, consulta Tipi di criteri.
Suggerimento: per scoprire di più su OAuth su Apigee, consulta la home page OAuth. Fornisce link a risorse, esempi, video e altro ancora.
Esempi
VerifyAccessToken
VerifyAccessToken
Questa configurazione dei criteri OAuthV2 (con l'operazione VerificationAccessToken) verifica che un token di accesso inviato ad Apigee sia valido. Quando viene attivata questa operazione con il criterio, Apigee cerca un token di accesso valido nella richiesta. Se il token di accesso è valido, la richiesta può continuare. Se non è valida, l'intera elaborazione si interrompe 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 i token di accesso per ciascuno dei tipi di autorizzazione supportati, consulta la pagina Ottenere i token OAuth 2.0. L'argomento include esempi di queste operazioni:
GenerateAuthorizationCode
Genera codice di autorizzazione
Per esempi che mostrano come richiedere i codici di autorizzazione, consulta l'articolo Richiedere un codice di autorizzazione.
RefreshAccessToken
Aggiornare un token di accesso
Per esempi che mostrano come richiedere i 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 Utilizzo dei token di accesso JWT.
Token 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 ad alcune convalide personalizzate eseguite in un servizio di backend. In questo esempio, il caso d'uso richiede sia un token di accesso che un token di aggiornamento, escludendo il tipo di autorizzazione implicita. In questo caso, utilizzeremo il tipo di autorizzazione della password per generare il token. Come vedrai, il trucco per eseguire questa operazione è passare l'intestazione di una richiesta di autorizzazione con un criterio JavaScript.
Innanzitutto, diamo un'occhiata alla norma 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, verrà restituito un errore 401 Non autorizzato anche se nel criterio vengono specificati i parametri di accesso corretti. Per risolvere questo problema, devi impostare un'intestazione della richiesta di autorizzazione.
L'intestazione Authorization deve contenere uno schema di accesso di base con client_id:client_secret con codifica Base64.
Puoi aggiungere questa intestazione con un criterio JavaScript posizionato subito prima del criterio OAuthV2, in questo modo. Le variabili di contesto "local_clientid" e "local_secret" devono essere precedentemente impostate 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 per gli elementi
Il riferimento ai criteri descrive gli elementi e gli attributi del criterio OAuthV2.
Il criterio di esempio mostrato di seguito è una delle tante configurazioni possibili. Questo esempio mostra un criterio OAuthV2 configurato per l'operazione GeneraAccessToken. Include elementi obbligatori e facoltativi. Per informazioni dettagliate, fai riferimento alle 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 della norma. Il valore dell'attributo Facoltativamente, utilizza l'elemento |
N/A | Obbligatorio |
continueOnError |
Impostalo su Imposta su |
false | Facoltativo |
enabled |
Imposta il criterio su Impostala su |
true | Facoltativo |
async |
Questo attributo è obsoleto. |
false | Deprecata |
Elemento <DisplayName>
Utilizzalo in aggiunta 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/A 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
prevede che il token di accesso venga inviato nell'intestazione Authorization
come token di connessione, ovvero con il prefisso "Bearer", seguito da uno spazio vuoto.
Puoi modificare il valore predefinito utilizzando questo elemento, specificando il nome di una variabile che contiene il token di accesso da verificare. Per impostazione predefinita, quando utilizzi questo elemento, 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:
Se la configurazione del criterio è:
<OAuthV2 name="OAuthV2-Verify-Access-Token-in-Header"> <Operation>VerifyAccessToken</Operation> <AccessToken>request.header.access_token</AccessToken> </OAuthV2>
Per passare il token utilizzando curl, potresti usare:
curl https://API_ENDPOINT/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"
Se la configurazione del criterio è:
<OAuthV2 name="OAuthV2-Verify-Access-Token-in-QueryParam"> <Operation>VerifyAccessToken</Operation> <AccessToken>request.queryparam.token</AccessToken> </OAuthV2>
Per passare il token utilizzando curl, potresti usare:
curl "https://API_ENDPOINT/oauth2/validate?token=Rft3dqrs56Blirls56a"
Dove API_ENDPOINT è il dominio utilizzato per accedere alle API, come configurato nel sistema Apigee.
Predefinita: |
N/D |
Presenza: |
Facoltativo |
Tipo: | Stringa |
Valori validi: |
nome qualsiasi variabile |
Utilizzato per le operazioni: |
|
Elemento <AccessTokenPrefix>
<AccessTokenPrefix>Prefix</AccessTokenPrefix>
Per impostazione predefinita, quando Operation
è VerifyAccessToken
, il criterio
prevede che il token di accesso venga inviato nell'intestazione Authorization
come token di connessione, ovvero con il prefisso "Bearer", seguito da uno spazio vuoto.
Se utilizzi l'elemento AccessToken
per specificare una località diversa per il token di accesso in entrata, puoi utilizzare anche questo elemento AccessTokenPrefix
per specificare un prefisso diverso 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 rimuove tale prefisso e 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
, il criterio interpreterà l'intero valore della
variabile specificata all'interno dell'elemento AccessToken
come token di accesso.
Questo elemento ha effetto solo quando viene utilizzato anche l'elemento AccessToken
.
Predefinita: |
-nessuno- |
Presenza: |
Facoltativo |
Tipo: | Stringa |
Valori validi: |
qualsiasi stringa |
Utilizzato per le operazioni: |
|
<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 secret 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, come,
ad esempio, ?app_enduser=ntesla@theramin.com
. Ad esempio, per richiedere l'elemento 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 maggiori informazioni, consulta Attivare il recupero e la revoca dei token di accesso OAuth 2.0 per ID utente finale, ID app o entrambi.
Predefinita: |
N/D |
Presenza: |
Facoltativo |
Tipo: | Stringa |
Valori validi: |
Qualsiasi variabile di flusso accessibile al criterio in fase di runtime. |
Utilizzato con i tipi di autorizzazione: |
|
<Attributi/Attributo>
<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 consente di specificare un valore in una variabile di flusso o da una stringa letterale. Se specifichi sia una variabile sia una stringa, viene utilizzato il valore specificato nella variabile di flusso. Se la variabile non può essere risolta, la stringa è il valore predefinito.
Per ulteriori informazioni sull'utilizzo di questo elemento, consulta Personalizzazione di token e codici di autorizzazione.
Mostrare o nascondere gli attributi personalizzati nella risposta
Ricorda che, se imposti l'elemento GenerateResponse di questo criterio su true, nella risposta viene restituita la rappresentazione JSON completa del token, inclusi gli eventuali attributi personalizzati che imposti. 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 è persistente. Supponiamo di generare un token di accesso con attributi personalizzati che vuoi nascondere nella risposta generata. L'impostazione di display=false
consente di raggiungere l'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
nel criterio di generazione del 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 un token di accesso viene generato utilizzando questo codice, gli attributi personalizzati verranno visualizzati nella risposta del token di accesso. Anche in questo caso, potrebbe non essere il comportamento previsto.
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 impostane la visualizzazione su false. In questo caso, potresti dover 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.
Predefinita: |
|
Presenza: |
Facoltativo |
Valori validi: |
|
Utilizzato con i tipi di autorizzazione: |
|
Elemento <CacheExpiryInSecond>
<CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Value 1</CacheExpiryInSeconds>
Questo elemento applica il valore TTL sulla cache, che consente la personalizzazione del periodo di tempo per la scadenza del token di accesso memorizzato nella cache. L'intervallo supportato è compreso tra 1 e 180 secondi. Puoi fornire una variabile di flusso e una predefinita. Se fornito, il valore della variabile di flusso ha la precedenza sul valore predefinito specificato.
Questo elemento può essere utilizzato solo con l'operazione VerifyAccessToken
.
Predefinito | N/D
Se ometti questo elemento, il periodo di scadenza predefinito per il token di accesso memorizzato nella cache è 180 secondi. |
---|---|
Presenza | Facoltativo |
Tipo | Numero intero |
Valori validi | Qualsiasi numero intero positivo diverso da zero. Specifica la scadenza in secondi. |
Attributi
La tabella seguente descrive gli attributi dell'elemento <CacheExpiryInSeconds>
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
rif |
Un riferimento alla variabile di flusso contenente il valore per la scadenza della cache, espressa 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 alcuni casi l'app client deve inviare l'ID client al server di autorizzazione. Questo
elemento consente di specificare dove Apigee deve cercare l'ID client. L'unica località valida che puoi impostare è la località predefinita, la variabile di flusso request.formparam.client_id
. L'impostazione di ClientId
su qualsiasi altra variabile non è supportata.
Vedi anche Ottenere i token OAuth 2.0.
Predefinita: |
request.formparam.client_id (un x-www-form-urlcoded e specificato nel corpo della richiesta) |
Presenza: |
Facoltativo |
Tipo: | Stringa |
Valori validi: | Variabile di flusso: request.formparam.client_id |
Utilizzato con i tipi di autorizzazione: |
Può essere utilizzata anche con l'operazione vicino all'autorizzazione. |
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 consente di specificare dove Apigee deve cercare il codice di autorizzazione. Ad esempio, potrebbe essere inviato come parametro di query, intestazione HTTP o parametro modulo (l'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
. Ad esempio, per richiedere il codice di autorizzazione in un'intestazione HTTP, imposta questo valore su request.header.auth_code
. Vedi anche
Ottenere i token OAuth 2.0.
Predefinita: |
request.formparam.code (un x-www-form-urlcoded e 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 autorizzazione: | authorization_code |
Elemento <ExpirationIn>
<ExpiresIn>10000</ExpiresIn>
Applica la scadenza in millisecondi dei token di accesso e dei codici di autorizzazione. (Per i token di aggiornamento, utilizza <RefreshTokenExpiresIn>
.) Il valore della data 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 di scadenza può essere impostata anche in fase di runtime, utilizzando un valore predefinito hardcoded o facendo riferimento a una variabile di flusso. Ad esempio, puoi archiviare 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 conserva le seguenti entità nella cache per almeno 180 secondi dopo l'accesso alle entità.
- 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 stanza seguente specifica anche 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 è descritta in questo post della community di Apigee.
Per impostazione predefinita, i token di accesso scaduti vengono eliminati automaticamente dal sistema Apigee 3 giorni dopo la scadenza. Vedi anche Eliminazione dei token di accesso
Predefinita: |
Se non specificato, il sistema applica un valore predefinito configurato a livello di sistema. |
Presenza: |
Facoltativo |
Tipo: | Numero intero |
Valori validi: |
|
Utilizzato con i tipi di autorizzazione: |
Utilizzato anche con l'operazione GeneraAuthorizationCode. |
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 è false o non è presente, Apigee convalida client_id e client_secret normalmente in base all'archivio di autorizzazione Apigee. Utilizza questo elemento quando vuoi utilizzare token OAuth di terze parti. Per maggiori dettagli sull'utilizzo di questo elemento, consulta Utilizzo di token OAuth di terze parti.
Predefinita: |
false |
Presenza: |
Facoltativo |
Tipo: | Booleano |
Valori validi: | true o false |
Utilizzato con i tipi di autorizzazione: |
|
Elemento <ExternalAuthorizationCode>
<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>
Indica ad Apigee dove trovare un codice di autorizzazione esterno (ovvero 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
. Ad esempio, per richiedere il codice di autorizzazione esterno in un'intestazione HTTP, imposta questo valore su request.header.external_auth_code
. Consulta anche Utilizzare i token OAuth di terze parti.
Elemento <ExternalUpdateToken>
<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 viene 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:
{ "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. Un insieme di variabili di flusso viene invece compilato con i valori relativi alla funzione del criterio. Ad esempio, una variabile di flusso denominata
oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code
viene compilata con il codice di autorizzazione appena
minato. Tieni presente che il valore expires_in è espresso in secondi nella risposta.
Predefinita: |
true |
Presenza: |
Facoltativo |
Tipo: | string |
Valori validi: | true o false |
Utilizzato con i tipi di autorizzazione: |
|
Elemento <GenerateErrorResponse>
<GenerateErrorResponse enabled='true'/>
Se viene impostato su true
, il criterio genera e restituisce una risposta se l'attributo ContinueOnError è impostato su true. Se false
(valore predefinito), non viene inviata alcuna risposta. Un insieme di variabili di flusso viene invece compilato con i valori relativi alla funzione del criterio.
Predefinita: |
false |
Presenza: |
Facoltativo |
Tipo: | string |
Valori validi: | true o false |
Utilizzato con i tipi di autorizzazione: |
|
<GrantType>
<GrantType>request.queryparam.grant_type</GrantType>
Indica al criterio dove trovare il parametro del tipo di autorizzazione passato in una richiesta. In base alla specifica OAuth 2.0, il tipo di autorizzazione deve essere specificato con le richieste di token di accesso e codici di autorizzazione. La variabile può essere un'intestazione, un parametro di query o un parametro modulo (impostazione predefinita).
Ad esempio, request.queryparam.grant_type
indica che la password
deve essere presente come parametro di ricerca, ad esempio ?grant_type=password
.
Ad esempio, per richiedere il tipo di autorizzazione in un'intestazione HTTP, imposta questo valore su request.header.grant_type
. Vedi anche Ottenere i token OAuth 2.0.
Predefinita: |
request.formparam.grant_type (un x-www-form-urlcoded e specificato nel corpo della richiesta) |
Presenza: |
Facoltativo |
Tipo: | string |
Valori validi: | Una variabile, come spiegato in precedenza. |
Utilizzato con i tipi di autorizzazione: |
|
Elemento <Operation>
<Operation>GenerateAuthorizationCode</Operation>
L'operazione OAuth 2.0 eseguita dal criterio.
Predefinita: |
Se |
Presenza: |
Facoltativo |
Tipo: | Stringa |
Valori validi: |
Operazioni aggiuntive relative al token di accesso JWT Se preferisci utilizzare token di accesso JWT anziché token stringa opachi, sono disponibili anche le operazioni seguenti per generare e convalidare i token JWT. Per maggiori dettagli, consulta l'articolo sull'utilizzo delle operazioni del token JWT OAuth:
|
Elemento <PassWord>
<PassWord>request.queryparam.password</PassWord>
Questo elemento viene utilizzato solo con il tipo di autorizzazione della password. Con
il tipo di autorizzazione 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 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 passare la password in una richiesta di token utilizzando un parametro di query e impostare l'elemento in questo 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 fa altro con questi valori delle credenziali; Apigee sta semplicemente verificando che siano presenti. Spetta allo sviluppatore dell'API recuperare la richiesta dei valori e inviarle a un provider di identità prima dell'esecuzione del criterio di generazione del token.
Vedi anche Ottenere i token OAuth 2.0.
Predefinita: |
request.formparam.password (un x-www-form-urlcoded 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 autorizzazione: | 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 trasmettere la chiave in una variabile di flusso.
Utilizzarlo solo quando
il valore dell'elemento Algorithm
è RS256, RS384 o RS512. Per maggiori informazioni, consulta
Utilizzo delle operazioni del token JWT OAuth.
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 di chiave privata RSA con codifica PEM. |
<PublicKey>/<Value>
<PublicKey> <Value ref="variable-name-here"/> </PublicKey>
Specifica la chiave pubblica o il certificato pubblico utilizzati per verificare la firma su un token di accesso in formato JWT firmato con un algoritmo RSA. Utilizza l'attributo ref
per trasmettere la chiave/il certificato in una variabile di flusso. Utilizzarlo 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 il codice di autorizzazione e i tipi di concessioni 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 dello sviluppatore 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 di app per sviluppatori su Apigee e sulla specifica di un URL di callback, consulta Registrare app e gestire le chiavi API. - (Facoltativo) Se è stato 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
. Ad esempio, per richiedere RedirectUri in un'intestazione HTTP, imposta questo valore su request.header.redirect_uri
. Vedi anche Ottenere i token OAuth 2.0.
Predefinita: |
request.formparam.redirect_uri (un x-www-form-urlcoded 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 autorizzazione: |
Utilizzato anche con l'operazione ManageAuthorizationCode. |
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, potrebbe essere inviato come parametro di query, intestazione HTTP o parametro modulo (l'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 l'elemento refreshToken in un'intestazione HTTP, ad esempio, imposta questo valore su request.header.refresh_token
. Vedi anche Ottenere i token OAuth 2.0.
Predefinita: |
request.formparam.refresh_token (un x-www-form-urlcoded 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 autorizzazione: |
|
Elemento <UpdateTokenScadeIn>
<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>
Applica la scadenza dei token di aggiornamento in millisecondi. Il valore della data 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 di scadenza può essere impostata anche in fase di runtime, utilizzando un valore predefinito hardcoded o facendo riferimento a una variabile di flusso. Ad esempio, puoi archiviare 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 stanza seguente specifica anche una variabile di flusso e un valore predefinito. Tieni presente che il valore della variabile di flusso ha la precedenza sul valore predefinito specificato.
<RefreshTokenExpiresIn ref="kvm.oauth.expires_in"> 86400000 <!--value in milliseconds--> </RefreshTokenExpiresIn>
Predefinita: |
2592000000 ms (30 giorni) (in vigore dal 31 maggio 2023) |
Presenza: |
Facoltativo |
Tipo: | Numero intero |
Valori validi: |
|
Utilizzato con i tipi di autorizzazione: |
|
Elemento <ResponseType>
<ResponseType>request.queryparam.response_type</ResponseType>
Questo elemento indica ad Apigee quale tipo di autorizzazione richiede l'app client. Viene utilizzato solo con i flussi di codice di autorizzazione e di tipo di autorizzazione implicito.
Per impostazione predefinita, Apigee cerca il valore del tipo di risposta in un parametro di query response_type
. Se vuoi eseguire l'override di 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. Vedi anche Ottenere i token OAuth 2.0.
Predefinita: |
request.formparam.response_type (un x-www-form-urlcoded e specificato nel corpo della richiesta) |
Presenza: |
Facoltativo. Utilizza questo elemento per eseguire l'override del 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 autorizzazione: |
|
Elemento <ReuseUpdatedToken>
<ReuseRefreshToken>true</ReuseRefreshToken>
Se viene impostato su true
, il token di aggiornamento esistente viene riutilizzato fino alla scadenza. Se false
, quando viene presentato un token di aggiornamento valido, Apigee emette un nuovo token di aggiornamento.
Predefinita: |
|
Presenza: |
facoltativo |
Tipo: | boolean |
Valori validi: |
|
Utilizzato con il tipo di autorizzazione: |
|
Elemento <RFCCompliantRequestResponse>
<RFCCompliantRequestResponse>[true | false]</RFCCompliantRequestResponse>
Se true
, il criterio è conforme agli standard RFC6749 e attiva i seguenti comportamenti conformi:
- Le risposte di errore e non di errore includeranno il campo intestazione della risposta HTTP
Cache-Control
per garantire la conformità a RFC2616 (Hypertext Transfer Protocol -- HTTP/1.1), con un valoreno-store
in qualsiasi risposta contenente token, credenziali o altre informazioni sensibili, nonché il campo di intestazione della rispostaPragma
con un valore pari ano-cache
. - La proprietà
expires_in
sarà in formato alfanumerico. Per coerenza, anche il valorerefresh_token_expires_in
sarà alfanumerico. - Le risposte OAuthV2 per la generazione di token includeranno il campo intestazione
Bearer
compatibile con RFC anzichéBearerToken
. - I messaggi di errore nei payload di risposta saranno nel formato
{"error" : "xxx", "error_description" :"yyy"}
per errori dei token di aggiornamento.
Predefinita: |
|
Presenza: |
Facoltativo |
Tipo: | Booleano |
Valori validi: | true o false |
Utilizzato con i tipi di autorizzazione: | Tutte |
<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. Da 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 del token JWT OAuth.
Apigee applica una forza 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 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 GeneraAccessToken o GeneraAuthorizationCode, viene utilizzato per specificare gli ambiti in cui concedere il token o il codice. Questi valori in genere vengono trasmessi al criterio nella richiesta da un'app client. Puoi configurare l'elemento in modo che utilizzi una variabile di flusso, in modo da scegliere in che modo trasferire 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
. Ad esempio, per richiedere l'ambito in un'intestazione HTTP, 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>
Vedi anche Utilizzo degli ambiti OAuth2 e Ottenere i token OAuth 2.0.
Predefinita: |
Nessun ambito |
Presenza: |
Facoltativo |
Tipo: | Stringa |
Valori validi: |
Se utilizzata con i criteri Genera*, una variabile di flusso. Se utilizzato conVerifyAccessToken, un elenco di nomi di ambiti (stringhe) separati da spazi. |
Utilizzato con i tipi di autorizzazione: |
|
Elemento <State>
<State>request.queryparam.state</State>
Nei casi in cui l'app client deve inviare 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 generalmente utilizzato come misura di sicurezza per prevenire gli attacchi CSRF.
Ad esempio, request.queryparam.state
indica che lo stato deve essere
presente come parametro di query, ad esempio ?state=HjoiuKJH32
. Ad esempio, per richiedere lo stato in un'intestazione HTTP, imposta questo valore su request.header.state
. Vedi anche Ottenere i token OAuth 2.0.
Predefinita: |
Nessuno stato |
Presenza: |
Facoltativo |
Tipo: | Stringa |
Valori validi: | Qualsiasi variabile di flusso accessibile al criterio in fase di runtime |
Utilizzato con i tipi di autorizzazione: |
|
Elemento <StoreToken>
<StoreToken>true</StoreToken>
Imposta questo elemento su true
quando l'elemento <ExternalAuthorization>
è true
. L'elemento <StoreToken>
indica ad Apigee di archiviare il token di accesso esterno. In caso contrario, non sarà persistente.
Predefinita: |
false |
Presenza: |
Facoltativo |
Tipo: | Booleano |
Valori validi: | true o false |
Utilizzato con i tipi di autorizzazione: |
|
Elemento <SupportedGrantTypes>/<GrantType>
<SupportedGrantTypes> <GrantType>authorization_code</GrantType> <GrantType>client_credentials</GrantType> <GrantType>implicit</GrantType> <GrantType>password</GrantType> </SupportedGrantTypes>
Specifica i tipi di autorizzazione supportati da un endpoint del token OAuth su Apigee. Un endpoint può supportare più tipi di concessioni (in altre parole, è possibile configurare un singolo endpoint per la distribuzione dei token di accesso per più tipi di concessioni.) Per saperne di più sugli endpoint, consulta Informazioni sugli endpoint OAuth. Il tipo di autorizzazione viene trasmesso nelle richieste di token in un parametro grant_type
.
Se non viene specificato alcun tipo di autorizzazione supportata, gli unici tipi di autorizzazione consentiti sono authorization_code
e implicit
. Vedi anche l'elemento <GrantType> (che è un elemento di livello superiore utilizzato per specificare dove Apigee deve cercare il parametro grant_type
che viene passato in una richiesta del client). Apigee si assicurerà che il valore del parametro grant_type
corrisponda a uno dei tipi di autorizzazione supportati.
Predefinita: |
autorizzazione_code e implicito |
Presenza: |
Obbligatorio |
Tipo: | Stringa |
Valori validi: |
|
Elemento <Tokens>/<Token>
Utilizzato con le operazioni ConvalidaToken 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. Ad esempio, se gli sviluppatori devono inviare token di accesso come parametri di ricerca denominati access_token
, utilizza request.queryparam.access_token
.
Elemento <UserName>
<UserName>request.queryparam.user_name</UserName>
Questo elemento viene utilizzato solo con il tipo di autorizzazione della password. Con
il tipo di autorizzazione 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 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 passare il nome utente in un parametro di query e impostare
l'elemento <UserName>
in questo 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 fa altro con questi valori delle credenziali; Apigee sta semplicemente verificando che siano presenti. Spetta allo sviluppatore dell'API recuperare la richiesta dei valori e inviarle a un provider di identità prima dell'esecuzione del criterio di generazione del token.
Vedi anche Ottenere i token OAuth 2.0.
Predefinita: |
request.formparam.username (un x-www-form-urlcoded e specificato nel corpo della richiesta) |
Presenza: |
Facoltativo |
Tipo: | Stringa |
Valori validi: | Impostazione qualsiasi variabile. |
Utilizzato con i tipi di autorizzazione: | password |
Verifica dei token di accesso
Dopo aver configurato un endpoint token per un proxy API, al flusso che espone la risorsa protetta viene associato un criterio OAuthV2 corrispondente che specifica l'operazione VerifyAccessToken
.
Ad esempio, per garantire che tutte le richieste a un'API siano autorizzate, il seguente criterio applica la verifica dei 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, associa 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 sostituire le impostazioni predefinite per l'operazione VerificationAccessToken.
Nome | Descrizione |
---|---|
Ambito |
Un elenco di ambiti delimitato da spazi. La verifica avrà esito positivo se almeno uno degli ambiti elencati è presente nel token di accesso. Ad esempio, il criterio seguente controllerà 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 deve trovarsi 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 base alla specifica OAuth 2.0. Utilizza questa impostazione se il token di accesso deve essere 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 Ottenere i token OAuth 2.0.
Specificare le località delle variabili di richiesta
Per ogni tipo di autorizzazione, il criterio fa ipotesi sulla posizione o sulle informazioni richieste nei messaggi di richiesta. Questi presupposti 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, l'ID client, l'URI di reindirizzamento e l'ambito. Possono essere specificati come intestazioni HTTP, parametri di ricerca o parametri di 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 del tuo 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 località per parametro.
Variabili di flusso
Le variabili di flusso definite in questa tabella vengono compilate quando vengono eseguiti i rispettivi criteri OAuth. Pertanto, sono disponibili per altri criteri o applicazioni in esecuzione nel flusso proxy API.
Operazione VerificationAccessToken
Quando viene eseguita l'operazione VerificationAccessToken, un numero elevato di variabili di flusso viene completato nel contesto di esecuzione del proxy. Queste variabili forniscono proprietà relative al token di accesso, all'app per sviluppatori e allo sviluppatore. Ad esempio, puoi utilizzare un criterio AttributionMessage o JavaScript per leggere una qualsiasi di queste variabili e utilizzarle in base alle necessità in un secondo momento nel flusso. Queste variabili possono essere utili anche per il debug.
Variabili specifiche per token
Variabili | Descrizione |
---|---|
organization_name |
Il nome dell'organizzazione in cui è in esecuzione il proxy. |
developer.id |
L'ID dello sviluppatore o del gruppo 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 autorizzazione associato alla richiesta. Non supportata 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 millisecondi per l'epoca di Unix. |
expires_in |
La scadenza del token di accesso. Espressa in secondi. Sebbene l'elemento ExpiresIn imposti la scadenza in millisecondi, nella risposta del token e nelle variabili di flusso, il valore viene espresso in secondi. |
status |
Lo stato del token di accesso (ad esempio 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 ibrido) Indica perché il token di accesso è stato revocato. Non supportata per l'operazione Il valore può essere |
Variabili specifiche per le app
Queste variabili sono correlate all'app sviluppatore 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 contengono informazioni su AppGroup per il token e sono compilate dal criterio. Questi attributi di AppGroup vengono compilati solo se
verifyapikey.{policy_name}.app.appType
è "AppGroup".
Variabili | Descrizione |
---|---|
appgroup.displayName |
Il nome visualizzato del gruppo di app. |
appgroup.name |
Nome del gruppo di app. |
appgroup.id |
L'ID AppGroup. |
appOwnerStatus |
Lo stato del proprietario dell'app: "attivo", "inattivo" o "login_lock". |
created_at |
Il timestamp di data e ora della creazione del gruppo di app. |
created_by |
L'indirizzo email dello sviluppatore che ha creato il gruppo di app. |
last_modified_at |
Il timestamp dell'ultima modifica del gruppo di app. |
last_modified_by |
L'indirizzo email dello sviluppatore che ha modificato il gruppo di app per ultimo. |
{appgroup_custom_attributes} |
Qualsiasi attributo AppGroup personalizzato. Specifica il nome dell'attributo personalizzato. |
Variabili specifiche per sviluppatore
Se app.appType
è "Sviluppatore", gli attributi dello sviluppatore vengono compilati.
Variabili | Descrizione |
---|---|
Variabili specifiche per sviluppatore | |
developer.id |
|
developer.userName |
|
developer.firstName |
|
developer.lastName |
|
developer.email |
|
developer.status |
attivo o inattivo |
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 GeneraAuthorizationCode
Queste variabili vengono impostate quando l'operazione GeneraAuthorizationCode viene eseguita correttamente:
Prefisso: oauthv2authcode.{policy_name}.{variable_name}
Esempio: oauthv2authcode.GenerateCodePolicy.code
Variabile | Descrizione |
---|---|
code |
Il codice di autorizzazione generato quando il criterio viene eseguito. |
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 trasmesso nella richiesta del client. |
Operazioni GeneraAccessToken e UpdateAccessToken
Queste variabili vengono impostate quando le operazioni GeneraAccessToken e AggiornaAccessToken vengono eseguite correttamente. Tieni presente che le variabili token di aggiornamento non si applicano al flusso di tipo di autorizzazione 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 dello sviluppatore associato a questo token. |
expires_in |
Il valore di scadenza del token. Consulta l'elemento <ExpiresIn> per i dettagli. Tieni presente che nella risposta, expires_in è espresso in secondi. |
scope |
Elenco degli ambiti disponibili configurati per il token. Vedi Utilizzo degli ambiti OAuth2. |
status |
approved o revoked . |
token_type |
È impostato su BearerToken . |
developer.email |
L'indirizzo email dello sviluppatore registrato proprietario dell'app sviluppatore associata al token. |
organization_name |
L'organizzazione su 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 autorizzazione 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à corrispondente del timestamp a 32 bit. 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 GeneraAccessTokenImplicit viene eseguita correttamente per il flusso del tipo di autorizzazione 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. Consulta l'elemento <ExpiresIn> per i dettagli. |
Riferimento errore
Questa sezione descrive i codici e i messaggi di errore che vengono restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta gli articoli Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.
Errori di runtime
Questi errori possono verificarsi quando il criterio viene eseguito.
Codice di errore | Stato HTTP | Causa | Generata 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 nessuno dei prodotti API associati al token di accesso. | VerifyAccessToken |
steps.oauth.v2.FailedToResolveAccessToken |
500 |
Il criterio dovrebbe 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 dovrebbe 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 prevedeva di trovare l'ID client 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 dovrebbe 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 dovrebbe 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 a quello specificato nel criterio relativo alla verifica del token di accesso. Per ulteriori informazioni sull'ambito, vedi 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 di errore viene restituito quando la proprietà |
GenerateAccessToken RefreshAccessToken |
steps.oauth.v2.invalid_request |
400 | Questo nome di errore viene utilizzato per diversi tipi di errori, in genere per parametri mancanti o errati inviati nella richiesta. Se <GenerateResponse> è impostato su false , utilizza le variabili di errore (descritte di seguito) per recuperare i dettagli dell'errore, come il nome e la causa dell'errore. |
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 |
L'operazione o il proxy API attualmente in esecuzione non si trova 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 i dettagli, consulta la sezione Gestione dei prodotti basati su API. Consulta anche La verifica del token di accesso Oauth2.0 genera l'errore "Chiamata API non valida perché non è stata trovata alcuna corrispondenza apiproduct" per ulteriori indicazioni sulle cause di questo errore. |
VerifyAccessToken |
steps.oauth.v2.InvalidClientIdentifier |
500 |
Questo nome di 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 trasmette il tipo sbagliato, viene visualizzato questo errore. |
ValidateToken InvalidateToken |
steps.oauth.v2.MissingParameter |
500 |
Il tipo di risposta è token , ma non è specificato alcun tipo di autorizzazione. |
GenerateAuthorizationCode GenerateAccessTokenImplicitGrant |
steps.oauth.v2.UnSupportedGrantType |
500 |
Il client ha specificato un tipo di autorizzazione non supportato dal criterio (non elencato nell'elemento
|
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
Errori di runtime specifici del token JWT
I codici degli errori di runtime e le descrizioni 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 la sezione Codici di errore per i flussi di aggiornamento e generazione di token JWT di seguito.
- Per il flusso di verifica dei token, vedi Codici di errore per i flussi di verifica dei token di seguito.
Codici di errore per i flussi di aggiornamento e generazione di token JWT
Per i flussi OAuth2 che generano o aggiornano token JWT, le risposte di errore rispettano le risposte di errore specificate in RFC6749. Per maggiori dettagli, consulta la Sezione 5.2 Risposta all'errore.
Codici di errore per il flusso di verifica del token
I codici di errore elencati nella tabella seguente si applicano solo all'operazione VerificationAccessToken.
Codice di errore | Stato HTTP | Causa | Generata dalle operazioni |
---|---|---|---|
oauth.v2.JWTSigningFailed |
401 |
Il criterio non è stato in grado di firmare il JWT. |
|
oauth.v2.InvalidValueForJWTAlgorithm |
401 |
Questo si verifica quando l'algoritmo non è presente nel token di accesso JWT o quando il valore non è supportato. |
|
oauth.v2.InsufficientKeyLength |
401 |
In Generazione di JWT, per una chiave inferiore alla dimensione minima per gli algoritmi HS384 o HS512 |
|
oauth.v2.JWTAlgorithmMismatch |
401 |
L'algoritmo specificato nella norma Genera non corrisponde a quello previsto nel criterio di verifica. Gli algoritmi specificati devono corrispondere. |
|
oauth.v2.JWTDecodingFailed |
401 |
Il criterio non è stato in grado di decodificare il JWT. Il JWT potrebbe essere danneggiato. |
|
oauth.v2.MissingMandatoryClaimsInJWT |
401 |
Si verifica quando le attestazioni richieste non sono presenti nel token Jwt Access |
|
oauth.v2.InvalidJWTSignature |
401 |
Questo accade 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 errore | Causa |
---|---|
InvalidValueForExpiresIn |
Per l'elemento |
InvalidValueForRefreshTokenExpiresIn |
Per l'elemento <RefreshTokenExpiresIn> , i valori validi sono numeri interi positivi e -1 . |
InvalidGrantType |
Nell'elemento <SupportedGrantTypes> è stato 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 esegue questa operazione. |
RefreshTokenExpiresInNotApplicableForOperation |
Assicurati che le operazioni specificate nell'elemento <Operations> supportino la scadenza del token di aggiornamento. Ad esempio, l'operazione VerificationToken non esegue questa operazione. |
GrantTypesNotApplicableForOperation |
Assicurati che i tipi di autorizzazione 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 <Token> del token nell'elemento <Tokens> . |
Errori di deployment specifici del token JWT
Questi errori di deployment sono specifici dei criteri che utilizzano le operazioni dei token JWT.
Nome errore | Causa |
---|---|
InvalidValueForAlgorithm |
L'algoritmo specificato nell'elemento <Algorithm> non è
nell'elenco degli algoritmi disponibili o non è presente. |
MissingKeyConfiguration |
Mancano gli elementi obbligatori <SecretKey> , <PrivateKey> o
<PublicKey> , 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 oppure 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 riportata sopra. Il nome del guasto è l'ultima parte del codice di 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 rinviate 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 il riferimento della risposta agli errori 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 il riferimento sulla risposta agli errori 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 OAuthV2 e i token di aggiornamento vengono sottoposti ad hashing per impostazione predefinita quando sono archiviati nel database Cassandra di runtime. L'hashing impedisce l'utilizzo dei token se il database è stato compromesso.
Utilizzare la configurazione OAuth predefinita
A ogni organizzazione (anche se un'organizzazione di prova gratuita) su Apigee viene eseguito il provisioning con un endpoint del token OAuth. L'endpoint è preconfigurato con i criteri nel proxy API chiamato oauth. Puoi iniziare a utilizzare l'endpoint del token non appena crei un account su Apigee. Per maggiori dettagli, consulta Informazioni sugli endpoint OAuth.
Eliminazione dei token di accesso
Per impostazione predefinita, i token OAuth2 vengono eliminati definitivamente dal sistema Apigee 3 giorni (259.200 secondi) dopo la scadenza sia del token di accesso che del token di aggiornamento (se esistente).
Comportamento non conforme a RFC
Per impostazione predefinita, il criterio OAuthV2, con l'operazione generateAccessToken, restituisce una risposta del token che contiene determinate proprietà non compatibili con RFC. La seguente tabella mostra le proprietà non conformi restituite dal criterio OAuthV2 e le corrispondenti proprietà conformi.
.OAuthV2 restituisce: | La proprietà compatibile con 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 relativa a un token di aggiornamento scaduto quando grant_type = refresh_token
è:
{"ErrorCode" : "invalid_request", "Error" :"Refresh Token expired"}
Tuttavia, la risposta conforme a RFC è:
{"error" : "invalid_grant", "error_description" :"refresh token expired"}