Questa pagina si applica a Apigee e Apigee ibridi.
Visualizza
documentazione di Apigee Edge.
Cosa
OAuthV2 è un criterio sfaccettato per eseguire operazioni relative ai tipi di autorizzazione OAuth 2.0. Questo è il criterio primario utilizzato per configurare gli endpoint OAuth 2.0 su Apigee.
Questo criterio è una norma estendibile e il suo utilizzo potrebbe comportare costi o di utilizzo delle applicazioni, a seconda della licenza Apigee. Per informazioni sui tipi di norme e le implicazioni per l'utilizzo, consulta Tipi di criteri.
Suggerimento: per scoprire di più su OAuth su Apigee, consulta alla home page di OAuth. Fornisce link alle risorse, agli esempi, ai video e altro ancora.
Campioni
VerifyAccessToken
VerifyAccessToken
Questa configurazione del criterio OAuthV2 (con l'operazione VerifyAccessToken) verifica che un Il token di accesso di Apigee inviato ad Apigee è valido. Quando questa operazione relativa ai criteri viene attivata, Apigee cerca un token di accesso valido nella richiesta. Se il token di accesso è valido, la richiesta viene autorizzati a procedere. Se non è valida, tutta l'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, con 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, in base alla configurazione nel tuo sistema Apigee.
Per impostazione predefinita, il criterio OAuthV2 estrae il token di accesso dall'intestazione Authorization
.
rimuovendo il prefisso Bearer
. Puoi modificare questo comportamento predefinito
con l'elemento di configurazione AccessToken
.
GenerateAccessToken
Generazione dei token di accesso
Per esempi che mostrano come richiedere i token di accesso per ciascuno dei tipi di concessioni supportati, consulta l'articolo Ottenere i token OAuth 2.0. L'argomento include esempi di queste operazioni:
GenerateAuthorizationCode
Genera codice di autorizzazione
Per esempi su come richiedere codici di autorizzazione, consulta Richiedere una 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 la sezione Aggiornare un di accesso al token.
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 di flusso di risposta
Genera un token di accesso nel flusso di risposta
A volte potresti dover generare un token di accesso nel flusso di risposta. Ad esempio, può 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 la concessione implicita di testo. In questo caso, utilizzeremo il tipo di concessione della password per generare il token. Come vedrai, il trucco per far funzionare questa operazione è passare in un'intestazione della richiesta di autorizzazione con un .
Innanzitutto, esaminiamo la 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, l'operazione non andrà a buon fine e verrà visualizzato un errore 401 Non autorizzato anche se nel criterio sono specificati i parametri di accesso corretti. Per risolvere il problema, devi impostare un'intestazione della richiesta di autorizzazione.
L'intestazione Authorization deve contenere uno schema di accesso Basic con codifica Base64 client_id:client_secret.
Puoi aggiungere questa intestazione con un criterio JavaScript posizionato subito prima del criterio OAuthV2. in questo modo. "local_clientid" e "local_secret" variabili di contesto devono essere impostate in precedenza 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 Codifica di base credenziali di autenticazione.
Riferimento dell'elemento
Il riferimento al criterio 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'operazioneGenerateAccessToken. Comprende i campi obbligatori e elementi 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>
<OAuthV2> attributi
<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 |
<AccessToken> elemento
<AccessToken>request.header.access_token</AccessToken>
Per impostazione predefinita, quando Operation
è VerifyAccessToken
, il criterio
prevede che il token di accesso venga inviato nel Authorization
un'intestazione come token di connessione; con il prefisso "Bearer", seguito da uno spazio vuoto.
Puoi modificare il valore predefinito usando questo elemento, specificando il nome di una variabile
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
dovrebbe cercare un prefisso, usa
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, potresti usare:
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, potresti usare:
curl "https://API_ENDPOINT/oauth2/validate?token=Rft3dqrs56Blirls56a"
Dove API_ENDPOINT è il dominio utilizzato per accedere alle API, come configurato in il tuo sistema Apigee.
Predefinita: |
N/D |
Presenza: |
Facoltativo |
Tipo: | Stringa |
Valori validi: |
qualsiasi nome di variabile |
Utilizzato con le operazioni: |
|
<AccessTokenPrefix> elemento
<AccessTokenPrefix>Prefix</AccessTokenPrefix>
Per impostazione predefinita, quando Operation
è VerifyAccessToken
, il criterio
prevede che il token di accesso venga inviato nel Authorization
un'intestazione come token di connessione; con il prefisso "Bearer", seguito da uno spazio vuoto.
Se utilizzi l'elemento AccessToken
per
specifica 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à il token di accesso in entrata dall'intestazione della richiesta token
,
in questo modo: se l'intestazione inizia con la parola "KEY" seguito da uno spazio, il criterio rimuoverà quella
e uno spazio, interpretando 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 il
AccessTokenPrefix
, il criterio interpreterà l'intero valore del parametro
specificata nell'elemento AccessToken
come token di accesso.
Questo elemento viene applicato soltanto quando viene utilizzato anche l'elemento AccessToken
.
Predefinita: |
-nessuno- |
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. Algoritmi RSA (RS*)
impiegano una coppia di chiavi pubbliche/segreta mentre gli algoritmi HMAC (HS*) impiegano un segreto condiviso. Questo elemento è obbligatorio
per le operazioni GenerateJWTAccessToken
, VerifyJWTAccessToken
e RefreshJWTAccessToken
.
Predefinito | N/D |
Presenza | Obbligatorio quando si utilizza
GenerateJWTAccessToken , VerifyJWTAccessToken e RefreshJWTAccessToken
operations. |
Tipo | Stringa |
Valori validi | HS256, HS384, HS512, RS256, RS384, RS512 |
<AppEndUser> elemento
<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 specifichi dove Apigee deve cercare l'ID utente finale. Ad esempio, potrebbe essere inviato come query o in un'intestazione HTTP.
Ad esempio request.queryparam.app_enduser
indica che
AppEndUser deve essere presente come parametro di query, ad esempio
ad esempio ?app_enduser=ntesla@theramin.com
. Per richiedere AppEndUser in un messaggio HTTP
ad esempio, imposta questo valore su request.header.app_enduser
.
Se fornisci questa impostazione, puoi includere un ID utente finale dell'app nel token di accesso. Questo è utile se vuoi poter recuperare o revocare i token di accesso OAuth 2.0 entro ID utente. Per ulteriori informazioni, vedi Abilita 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. |
Utilizzati con i tipi di autorizzazione: |
|
<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. Per Ad esempio, potresti voler incorporare un ID utente o un identificatore di sessione in un token di accesso che può essere vengono estratti e controllati durante il runtime.
Questo elemento consente di specificare un valore in una variabile di flusso o da una stringa letterale. Se specificare sia una variabile che una stringa, viene utilizzato il valore specificato nella variabile di flusso. Se non può essere risolta, la stringa è quella predefinita.
Per ulteriori informazioni sull'uso di questo elemento, consulta Personalizzazione di token e Codici di autorizzazione.
Mostrare o nascondere gli attributi personalizzati nel risposta
Ricorda che se imposti l'elemento CreateResponse di questo criterio su true, la rappresentazione JSON completa del token viene restituita nella risposta, incluse le eventuali che hai impostato. In alcuni casi, potresti voler nascondere alcuni o tutti i tuoi 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 diventa 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 è
persistenti. Supponiamo di generare un token di accesso con attributi personalizzati che vuoi nascondere nel
generata. L'impostazione di display=false
consente di raggiungere l'obiettivo. Tuttavia, se un nuovo
viene generato in un secondo momento utilizzando un token di aggiornamento, ovvero gli attributi personalizzati originali
Il token di accesso verrà visualizzato 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,
è semplicemente parte dei metadati del token di accesso.
Il comportamento sarà lo stesso se aggiungi attributi personalizzati a un codice di autorizzazione, quando il token di accesso generato utilizzando questo codice. Gli attributi personalizzati verranno visualizzati nel token di accesso risposta. Anche in questo caso, potrebbe non essere il comportamento previsto.
Per nascondere i segmenti di pubblico in questi casi, hai le seguenti opzioni:
- Reimposta in modo esplicito 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 di accesso a un token usando il criterio GetOAuthV2Info.
- Utilizza un criterio JavaScript di post-elaborazione per estrarre manualmente gli attributi personalizzati che non che vuoi vedere nella risposta.
Vedi anche Personalizzazione di token e Codici di autorizzazione.
Predefinita: |
|
Presenza: |
Facoltativo |
Valori validi: |
|
Utilizzati con i tipi di autorizzazione: |
|
<CacheExpiryInSeconds> elemento
<CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Value 1</CacheExpiryInSeconds>
Questo elemento applica il TTL sulla cache, il 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 variabile 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 è di 180 secondi. |
---|---|
Presenza | Facoltativo |
Tipo | Numero intero |
Valori validi | Qualsiasi numero intero positivo diverso da zero. Specifica la scadenza in secondi. |
Attributi
Nella tabella seguente vengono descritti gli attributi dell'elemento <CacheExpiryInSeconds>
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
riferimento |
Un riferimento alla variabile di flusso contenente il valore per la scadenza della cache, espresso in secondi. Se fornito, il valore della variabile di flusso ha la precedenza sul valore predefinito specificato. |
N/D | Facoltativo |
<ClientId> elemento
<ClientId>request.formparam.client_id</ClientId>
In alcuni casi, l'app client deve inviare l'ID client al server di autorizzazione. Questo
consente di specificare dove Apigee deve cercare l'ID client. L'unico valore
la località che puoi impostare è quella predefinita
posizione, la variabile di flusso request.formparam.client_id
. Impostazione di ClientId
a qualsiasi altra variabile non è supportato.
Vedi anche Recuperare i token OAuth 2.0.
Predefinita: |
request.formparam.client_id (un x-www-form-urlcodificato e specificato nella richiesta corpo) |
Presenza: |
Facoltativo |
Tipo: | Stringa |
Valori validi: | La variabile di flusso: request.formparam.client_id |
Utilizzati con i tipi di autorizzazione: |
Può essere utilizzato anche con l'operazione generateAuthorizationCode. |
<Code> elemento
<Code>request.queryparam.code</Code>
Nel flusso del tipo di concessione dell'autorizzazione, il client deve inviare un codice di autorizzazione alla di autorizzazione (Apigee). Questo elemento ti consente di specificare dove Apigee deve cercare codice di autorizzazione. Ad esempio, può essere inviato come parametro di query, intestazione HTTP o modulo predefinito (predefinito).
La variabile request.queryparam.auth_code
indica che la variabile
il codice di autorizzazione deve essere presente come parametro di query, ad esempio
ad esempio ?auth_code=AfGlvs9
. Per richiedere il codice di autorizzazione in una richiesta
ad esempio, imposta questo valore su request.header.auth_code
. Vedi anche
Ottieni i token OAuth 2.0.
Predefinita: |
request.formparam.code (un x-www-form-urlcodificato e specificato nel corpo della richiesta) |
Presenza: |
facoltativo |
Tipo: | Stringa |
Valori validi: | Qualsiasi variabile di flusso accessibile al criterio in fase di runtime |
Utilizzati con i tipi di autorizzazione: | authorization_code |
<ExpiresIn> elemento
<ExpiresIn>10000</ExpiresIn>
Applica la scadenza dei token di accesso e dei codici di autorizzazione in millisecondi. (Per
di aggiornamento, utilizza <RefreshTokenExpiresIn>
. Il valore della data di scadenza è un
valore generato dal sistema più il valore di <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 viene 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 coppia chiave-valore
mappare, recuperarlo, assegnarlo a una variabile e farvi riferimento nel criterio. Ad esempio:
kvm.oauth.expires_in
.
Apigee mantiene le seguenti entità nella cache per almeno 180 secondi dopo l'accesso alle entità.
- Token di accesso OAuth. Ciò significa che
L'elemento
ExpiresIn
del criterio OAuth v2 non sarà in grado di 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 una variabile di flusso e anche un valore predefinito. Tieni presente che il 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 è descritto in in questo post della community Apigee.
Per impostazione predefinita, i token di accesso scaduti vengono eliminati definitivamente da Apigee Sistema Apigee automaticamente 3 giorni dopo la scadenza. Vedi anche Eliminare definitivamente l'accesso di token
Predefinita: |
Se non specificato, il sistema applica un valore predefinito configurato sul sistema livello. |
Presenza: |
Facoltativo |
Tipo: | Numero intero |
Valori validi: |
|
Utilizzati con i tipi di autorizzazione: |
Utilizzato anche con l'operazione generateAuthorizationCode. |
<ExternalAccessToken> elemento
<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>
Indica ad Apigee dove trovare un token di accesso esterno (un token di accesso non generato Apigee).
La variabile request.queryparam.external_access_token
indica che
il token di accesso esterno deve essere presente come parametro di query, ad esempio
ad esempio ?external_access_token=12345678
. Per richiedere il token di accesso esterno
in un'intestazione HTTP, ad esempio, imposta questo valore
a request.header.external_access_token
. Vedi anche Utilizzo di OAuth di terze parti
Token.
<ExternalAuthorization> elemento
<ExternalAuthorization>true</ExternalAuthorization>
Se questo elemento è falso o non è presente, Apigee convalida i client_id e client_secret di solito con l'archivio di autorizzazioni Apigee. Usa questo elemento quando vuoi lavorare con di terze parti. Per maggiori dettagli sull'uso di questo elemento, consulta Utilizzo di OAuth di terze parti. Token.
Predefinita: |
falso |
Presenza: |
Facoltativo |
Tipo: | Booleano |
Valori validi: | vero o falso |
Utilizzati con i tipi di autorizzazione: |
|
<ExternalAuthorizationCode> elemento
<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>
Indica ad Apigee dove trovare un codice di autorizzazione esterno (un codice di autorizzazione non generato Apigee).
La variabile request.queryparam.external_auth_code
indica che
il codice di autorizzazione esterno deve essere presente come parametro di query, ad esempio
ad esempio ?external_auth_code=12345678
. Per richiedere l'autorizzazione esterna
codice
in un'intestazione HTTP, ad esempio, imposta questo valore
a request.header.external_auth_code
. Vedi anche Utilizzo di OAuth di terze parti
Token.
<ExternalRefreshToken> elemento
<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>
Indica ad Apigee dove trovare un token di aggiornamento esterno (un token di aggiornamento non generato Apigee).
La variabile request.queryparam.external_refresh_token
indica che
il token di aggiornamento esterno deve essere presente come parametro di query, ad esempio
ad esempio ?external_refresh_token=12345678
. Per richiedere il token di aggiornamento esterno
in un'intestazione HTTP, ad esempio, imposta questo valore
a request.header.external_refresh_token
. Vedi anche Utilizzo di OAuth di terze parti
Token.
<GenerateResponse> elemento
<GenerateResponse enabled='true'/>
Se impostato su true
o se l'attributo enabled
viene omesso, il criterio
genera e restituisce una risposta. Ad esempio, per GeneraAccessToken, la risposta potrebbe essere simile a:
{ "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 ai parametri
encoder-decoder. Ad esempio, una variabile di flusso denominata
Il campo oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code
viene compilato con
nuovo codice di autorizzazione. Tieni presente che expires_in è espresso in secondi nella
risposta.
Predefinita: |
true |
Presenza: |
Facoltativo |
Tipo: | string |
Valori validi: | vero o falso |
Utilizzati con i tipi di autorizzazione: |
|
<GenerateErrorResponse> elemento
<GenerateErrorResponse enabled='true'/>
Se impostato su true
, il criterio genera e restituisce una risposta se il criterio
L'attributo ContinueOnError è impostato su true. Se false
(valore predefinito),
viene inviata una risposta. Un insieme di variabili di flusso viene invece compilato con i valori relativi ai parametri
encoder-decoder.
Predefinita: |
falso |
Presenza: |
Facoltativo |
Tipo: | string |
Valori validi: | vero o falso |
Utilizzati con i tipi di autorizzazione: |
|
<GrantType>
<GrantType>request.queryparam.grant_type</GrantType>
Indica al criterio dove trovare il parametro del tipo di concessione passato in una richiesta. In base alle nella specifica OAuth 2.0, il tipo di autorizzazione deve essere fornito con le richieste per i token di accesso e codici di autorizzazione. La variabile può essere un'intestazione, un parametro di query o un parametro del modulo (impostazione predefinita).
Ad esempio request.queryparam.grant_type
indica che la password
deve essere presente come parametro di query, ad esempio ?grant_type=password
.
Per richiedere il tipo di autorizzazione in un'intestazione HTTP, ad esempio, imposta questo valore
a request.header.grant_type
. Vedi anche Recuperare i token OAuth 2.0.
Predefinita: |
request.formparam.grant_type (un x-www-form-urlcodificato e specificato nella richiesta corpo) |
Presenza: |
Facoltativo |
Tipo: | string |
Valori validi: | Una variabile, come spiegato in precedenza. |
Utilizzati con i tipi di autorizzazione: |
|
<Operation> elemento
<Operation>GenerateAuthorizationCode</Operation>
L'operazione OAuth 2.0 eseguita dal criterio.
Predefinita: |
Se |
Presenza: |
Facoltativo |
Tipo: | Stringa |
Valori validi: |
Operazioni aggiuntive del token di accesso JWT Se preferisci utilizzare i token di accesso JWT anziché di stringhe opace, sono disponibili anche le seguenti operazioni per la generazione e la convalida dei token JWT. Per maggiori dettagli, vedi Utilizzo delle operazioni del token OAuth JWT:
|
<PassWord> elemento
<PassWord>request.queryparam.password</PassWord>
Questo elemento viene utilizzato solo con il tipo di concessione della password. Con
il tipo di concessione della password, le credenziali utente (password e nome utente) devono essere messe a disposizione del
Criterio OAuthV2. Gli elementi <PassWord>
e <UserName>
sono
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
di flusso contenente le credenziali.
Ad esempio, puoi passare la password in una richiesta di token utilizzando un parametro di query e impostare
come questo:
<PassWord>request.queryparam.password</PassWord>
.
a
richiedi la password in un'intestazione HTTP, imposta questo valore
a request.header.password
.
Il criterio OAuthV2 non fa altro con questi valori delle credenziali; Apigee è semplicemente per verificare la loro presenza. Spetta allo sviluppatore dell'API recuperare la richiesta di valori e e li invii a un provider di identità prima dell'esecuzione del criterio di generazione dei token.
Vedi anche Recuperare i token OAuth 2.0.
Predefinita: |
request.formparam.password (un x-www-form-urlcodificato e specificato nella richiesta corpo) |
Presenza: |
Facoltativo |
Tipo: | Stringa |
Valori validi: | Qualsiasi variabile di flusso disponibile per il criterio in fase di runtime. |
Utilizzati 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.
Da utilizzare solo se
Il valore dell'elemento Algorithm
è RS256, RS384 o RS512. Per ulteriori informazioni, vedi
Utilizzo delle operazioni del token OAuth JWT.
Predefinito | N/D |
Presenza | Obbligatorio quando il valore dell'elemento Algorithm è uno tra
HS256, HS384 o HS512. |
Tipo | Stringa |
Valori validi | Una variabile di flusso contenente una stringa che rappresenta un valore di 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/certificata in una variabile di flusso. Da utilizzare solo se
Il valore dell'elemento Algorithm
è RS256, RS384 o RS512.
Predefinito | N/D |
Presenza | Per verificare un JWT firmato con un algoritmo RSA, devi utilizzare il certificato, JWKS o Elementi di valore. |
Tipo | Stringa |
Valori validi | Una stringa o una variabile di flusso. |
<RedirectUri> elemento
<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 implicite. Il reindirizzamento L'URI indica al server di autorizzazione (Apigee) dove inviare un codice di autorizzazione (per il codice di autorizzazione) tipo di autorizzazione) o token di accesso (per il tipo di autorizzazione implicita). È importante capire quando questo parametro è obbligatorio, quando è facoltativo e come viene utilizzato:
-
(obbligatorio) Se un URL di callback è registrato con l'app sviluppatore associata a le chiavi client della richiesta e, se
redirect_uri
è presente nella richiesta, allora i due devono corrispondere esattamente. Se non corrispondono, viene restituito un errore. Per informazioni sulla registrazione di app sviluppatore su Apigee e sulla specifica di un URL di callback, vedi Registrare app e gestire l'API chiave. - (Facoltativo) Se è stato registrato un URL di callback e
redirect_uri
non è presente dalla richiesta, Apigee reindirizza all'URL di callback registrato. - (obbligatorio) Se un URL di callback non è registrato,
redirect_uri
è obbligatorio. Tieni presente che in questo caso Apigee accetterà QUALSIASI URL. Questo caso può presentare problema di sicurezza e pertanto deve essere utilizzato solo con client attendibili app. Se le app client non sono attendibili, la best practice è quella di richiedere sempre registrazione di un URL di callback.
Puoi inviare questo parametro in un parametro di query o in un'intestazione. La
la variabile request.queryparam.redirect_uri
indica che la proprietà RedirectUri
deve essere presente come parametro di query, ad esempio
ad esempio ?redirect_uri=login.myapp.com
. Per richiedere RedirectUri in un HTTP
ad esempio, imposta questo valore su request.header.redirect_uri
. Consulta
inoltre procurarsi i token OAuth 2.0.
Predefinita: |
request.formparam.redirect_uri (un x-www-form-urlcodificato e specificato nella richiesta corpo) |
Presenza: |
Facoltativo |
Tipo: | Stringa |
Valori validi: | Qualsiasi variabile di flusso accessibile nel criterio in fase di runtime |
Utilizzati con i tipi di autorizzazione: |
Utilizzato anche con l'operazione CreateAuthorizationCode. |
<RefreshToken> elemento
<RefreshToken>request.queryparam.refreshtoken</RefreshToken>
Quando richiedi un token di accesso utilizzando un token di aggiornamento, devi fornire il token di aggiornamento nel la richiesta. Questo elemento consente di specificare dove Apigee deve cercare il token di aggiornamento. Per può essere inviato come parametro di query, intestazione HTTP o parametro modulo (predefinito).
La variabile request.queryparam.refreshtoken
indica che l'aggiornamento
il token deve essere presente come parametro di query, ad esempio
ad esempio ?refresh_token=login.myapp.com
. Per richiedere RefreshToken in una finestra HTTP
ad esempio, imposta questo valore su request.header.refresh_token
. Consulta
inoltre procurarsi i token OAuth 2.0.
Predefinita: |
request.formparam.refresh_token (un x-www-form-urlcodificato e specificato nella richiesta corpo) |
Presenza: |
Facoltativo |
Tipo: | Stringa |
Valori validi: | Qualsiasi variabile di flusso accessibile nel criterio in fase di runtime |
Utilizzati con i tipi di autorizzazione: |
|
<RefreshTokenExpiresIn> elemento
<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 alle norme OAuth massime
la scadenza del token di aggiornamento. 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 coppia chiave-valore
mappare, recuperarlo, assegnarlo a una variabile e farvi riferimento nel criterio. Per
ad esempio kvm.oauth.expires_in
.
La stanza seguente specifica una variabile di flusso e anche un valore predefinito. Tieni presente che il 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: |
|
Utilizzati con i tipi di autorizzazione: |
|
<ResponseType> elemento
<ResponseType>request.queryparam.response_type</ResponseType>
Questo elemento indica ad Apigee il tipo di concessione richiesto dall'app client. Viene utilizzato solo con il codice di autorizzazione e i flussi di tipo di autorizzazione implicita.
Per impostazione predefinita, Apigee cerca il valore del tipo di risposta in una query response_type
. Se desideri eseguire l'override di questo comportamento predefinito, utilizza lo strumento <ResponseType> in
configurare una variabile di flusso contenente il valore del tipo di risposta. Ad esempio, se imposti questo
su request.header.response_type
, Apigee cerca il tipo di risposta da
nell'intestazione della richiesta. Vedi anche Recuperare i token OAuth 2.0.
Predefinita: |
request.formparam.response_type (un x-www-form-urlcodificato e specificato nella richiesta corpo) |
Presenza: |
Facoltativo. Utilizza questo elemento se vuoi 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) |
Utilizzati con i tipi di autorizzazione: |
|
<ReuseRefreshToken> elemento
<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
presentati.
Predefinita: |
|
Presenza: |
facoltativo |
Tipo: | boolean |
Valori validi: |
|
Utilizzato con il tipo di autorizzazione: |
|
<RFCCompliantRequestResponse> elemento
<RFCCompliantRequestResponse>[true | false]</RFCCompliantRequestResponse>
Quando true
, il criterio è conforme a RFC6749
standard e consente i seguenti comportamenti conformi:
- Le risposte di errore e non di errore includeranno la risposta HTTP
Cache-Control
campo header per rispettare lo standard RFC2616 (Hypertext Transfer Protocol -- HTTP/1.1), con valoreno-store
in qualsiasi risposta contenente token, credenziali o altre informazioni sensibili, nonché Campo di intestazione della rispostaPragma
con il valoreno-cache
. - La proprietà
expires_in
sarà in formato alfanumerico. Per coerenza, il valorerefresh_token_expires_in
sarà anch'esso alfanumerico. - Le risposte OAuthV2 per la generazione di token includeranno le
Bearer
conformi a RFC campo di intestazione anzichéBearerToken
. - I messaggi di errore nei payload di risposta saranno nel formato
{"error" : "xxx", "error_description" :"yyy"}
per gli errori del token di aggiornamento.
Predefinita: |
|
Presenza: |
Facoltativo |
Tipo: | Booleano |
Valori validi: | true o false |
Utilizzati con i tipi di autorizzazione: | 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
quando l'algoritmo è HS256, HS384 o HS512. Utilizza l'attributo ref
per passare la chiave in una variabile di flusso. Per ulteriori informazioni, vedi
Utilizzo delle operazioni del token OAuth JWT.
Apigee applica un'intensità 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 a potenza inferiore causa un errore di runtime.
Predefinito | N/D |
Presenza | Obbligatorio per gli algoritmi HMAC. |
Tipo | Stringa |
Valori validi | Una variabile di flusso |
<Scope> elemento
<Scope>request.queryparam.scope</Scope>
Se questo elemento è presente in uno dei valori
e i criteri, viene utilizzato per specificare gli ambiti in cui concedere il token o il codice. Questi valori sono
vengono generalmente trasmessi alle norme nella richiesta da un'app client. Puoi configurare l'elemento
una variabile di flusso, per darti la possibilità di scegliere come vengono passati gli ambiti in una richiesta. Nel
nell'esempio seguente, request.queryparam.scope
indica che l'ambito deve
Essere presente come parametro di query, come, ad esempio, ?scope=READ
. Per richiedere il
scope in un'intestazione HTTP, ad esempio imposta questo valore
a request.header.scope
.
Se questo elemento viene visualizzato in "VerifyAccessToken" viene usato per specificare quale gli ambiti che il criterio deve applicare. In questo tipo di criterio, il valore deve essere impostato come hardcoded ambito non puoi usare le variabili. Ad esempio:
<Scope>A B</Scope>
Vedi anche Utilizzo di OAuth2 ambiti e Recupera 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 con VerifyAccessToken, un elenco di nomi di ambiti (stringhe) separati da spazi. |
Utilizzati con i tipi di autorizzazione: |
|
<State> elemento
<State>request.queryparam.state</State>
Nei casi in cui l'app client deve inviare le informazioni sullo stato al server di autorizzazione, questo elemento consente di specificare dove Apigee deve cercare i valori dello stato. Ad esempio, 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, come, ad esempio, ?state=HjoiuKJH32
. Per richiedere
lo stato in un'intestazione HTTP, ad esempio imposta questo valore
a 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 |
Utilizzati con i tipi di autorizzazione: |
|
<StoreToken> elemento
<StoreToken>true</StoreToken>
Imposta questo elemento su true
quando <ExternalAuthorization>
è true
. L'elemento <StoreToken>
comunica ad Apigee
per archiviare il token di accesso esterno. In caso contrario, non verrà mantenuto.
Predefinita: |
falso |
Presenza: |
Facoltativo |
Tipo: | Booleano |
Valori validi: | vero o falso |
Utilizzati con i tipi di autorizzazione: |
|
<SupportedGrantTypes>/<GrantType> elemento
<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 autorizzazione (ovvero, un singolo endpoint può essere configurato per distribuire l'accesso
per più tipi di concessioni). Per ulteriori informazioni sugli endpoint, consulta Informazioni su OAuth
endpoint. Il tipo di concessione viene passato nelle richieste di token in un grant_type
.
Se non viene specificato alcun tipo di autorizzazione supportato, gli unici tipi di autorizzazione consentiti sono
authorization_code
e implicit
. Vedi anche l'elemento <GrantType> (un elemento di livello superiore utilizzato per
specifica dove Apigee deve cercare il parametro grant_type
passato in
una richiesta del client. Apigee si assicurerà che il valore del parametro grant_type
corrisponde a uno dei tipi di autorizzazione supportati).
Predefinita: |
autorizzazione _code e implicita |
Presenza: |
Obbligatorio |
Tipo: | Stringa |
Valori validi: |
|
<Tokens>/<Token> elemento
Utilizzato con le operazioni ConvalidaToken e InvalidateToken. Vedi anche Approvazione e
revoca dei token di accesso. Il <Token> identifica la variabile di flusso che definisce
l'origine del token da revocare. Se gli sviluppatori devono inviare i token di accesso come
parametri di ricerca denominati access_token
, ad esempio
utilizza request.queryparam.access_token
.
<UserName> elemento
<UserName>request.queryparam.user_name</UserName>
Questo elemento viene utilizzato solo con il tipo di concessione della password. Con
il tipo di concessione della password, le credenziali utente (password e nome utente) devono essere messe a disposizione del
Criterio OAuthV2. Gli elementi <PassWord>
e <UserName>
sono
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
di flusso contenente le credenziali.
Ad esempio, puoi passare il nome utente in un parametro di query e impostare
<UserName>
elemento come questo:
<UserName>request.queryparam.username</UserName>
.
Da richiedere
il nome utente in un'intestazione HTTP, imposta questo valore
a request.header.username
.
Il criterio OAuthV2 non fa altro con questi valori delle credenziali; Apigee è semplicemente per verificare la loro presenza. Spetta allo sviluppatore dell'API recuperare la richiesta di valori e e li invii a un provider di identità prima dell'esecuzione del criterio di generazione dei token.
Vedi anche Recuperare i token OAuth 2.0.
Predefinita: |
request.formparam.username (un x-www-form-urlcodificato e specificato nella richiesta corpo) |
Presenza: |
Facoltativo |
Tipo: | Stringa |
Valori validi: | Qualsiasi impostazione di variabile. |
Utilizzati con i tipi di autorizzazione: | password |
Verificare l'accesso token
Una volta configurato un endpoint token per un proxy API, un criterio OAuthV2 corrispondente che
specifica che l'operazione VerifyAccessToken
è collegata al flusso che espone
risorsa protetta.
Ad esempio, per garantire che tutte le richieste a un'API siano autorizzate, il seguente criterio forza la verifica del token di accesso:
<OAuthV2 name="VerifyOAuthAccessToken"> <Operation>VerifyAccessToken</Operation> </OAuthV2>
Il criterio è associato alla risorsa API da proteggere. Per garantire che tutte le richieste a un Le API sono state verificate. Collega il criterio alla richiesta ProxyEndpoint PreFlow come segue:
<PreFlow> <Request> <Step><Name>VerifyOAuthAccessToken</Name></Step> </Request> </PreFlow>
I seguenti elementi facoltativi possono essere utilizzati per sostituire le impostazioni predefinite per Operazione VerifyAccessToken.
Nome | Descrizione |
---|---|
Ambito |
Un elenco di ambiti delimitati da spazi. La verifica avrà esito positivo se almeno uno dei sono presenti nel token di accesso. Ad esempio, il seguente criterio controlla il token di accesso per assicurarti che contenga almeno uno degli ambiti elencati. Se READ o WRITE è presente, la verifica verrà riuscire. <OAuthV2 name="ValidateOauthScopePolicy"> <Operation>VerifyAccessToken</Operation> <Scope>READ WRITE</Scope> </OAuthV2> |
AccessToken | La variabile in cui dovrebbe essere posizionato il token di accesso. Ad esempio:
request.queryparam.accesstoken . Per impostazione predefinita, il token di accesso dovrebbe essere
presentato dall'app nell'intestazione HTTP Autorizzazione, in base alla specifica OAuth 2.0. Usa questa
se è previsto che il token di accesso venga presentato in una posizione non standard, come
un parametro di query o un'intestazione HTTP con un nome diverso da Authorization. |
Vedi anche Verifica dell'accesso e Recuperare i token OAuth 2.0.
Specificare le posizioni delle variabili di richiesta
Per ogni tipo di concessione, le norme fanno ipotesi sulla località o sulle informazioni richieste. nei messaggi di richiesta. Queste ipotesi si basano sulla specifica OAuth 2.0. Se le tue app devi deviare dalla specifica OAuth 2.0, puoi specificare le località previste per ogni parametro. Ad esempio, quando gestisci un codice di autorizzazione, puoi specificare la posizione il codice di autorizzazione, l'ID client, l'URI di reindirizzamento e l'ambito. Queste possono essere specificate come Intestazioni HTTP, parametri di ricerca o parametri del modulo.
L'esempio seguente mostra come specificare la località del codice di autorizzazione richiesto come intestazioni HTTP:
... <GrantType>request.header.grant_type</GrantType> <Code>request.header.code</Code> <ClientId>request.header.client_id</ClientId> <RedirectUri>request.header.redirect_uri</RedirectUri> <Scope>request.header.scope</Scope> ...
In alternativa, se necessario per supportare la base di app client, puoi combinare intestazioni e query parametri:
... <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 i rispettivi criteri OAuth vengono e, di conseguenza, sono disponibili per altri criteri o applicazioni in esecuzione nel proxy API flusso di lavoro.
Operazione VerifyAccessToken
Quando viene eseguita l'operazione VerifyAccessToken, viene compilata un numero elevato di variabili di flusso nel contesto di esecuzione del proxy. Queste variabili forniscono proprietà correlate all'accesso token, app sviluppatore e sviluppatore. Puoi usare un criterioAssignMessage o JavaScript, ad esempio per leggere una qualsiasi di queste variabili e utilizzarle in base alle esigenze più avanti nel flusso. Questi possono essere utili anche per il debug.
Variabili specifiche per i token
Variabili | Descrizione |
---|---|
organization_name |
Il nome dell'organizzazione su cui viene eseguito il proxy. |
developer.id |
L'ID dello sviluppatore AppGroup associati all'app client registrata. |
developer.app.name |
Il nome dello sviluppatore o 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 Unix. dell'epoca in millisecondi. |
expires_in |
La scadenza del token di accesso. Espressa in
secondi. Anche se ExpiresIn
imposta la scadenza in millisecondi nella risposta del token e
variabili di flusso, il valore viene 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 al client registrato dell'app. |
apiproduct.name |
Il nome del prodotto API associato all'app client registrata. |
revoke_reason |
(Solo Apigee hybrid) Indica perché il token di accesso è stato revocato. Non supportato per l'operazione Il valore può essere |
Variabili specifiche per 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 contenenti informazioni sul
AppGroup
per il token e vengono completati dal criterio. Questi attributi AppGroup vengono compilati solo se
verifyapikey.{policy_name}.app.appType
è "AppGroup".
Variabili | Descrizione |
---|---|
appgroup.displayName |
Il nome visualizzato AppGroup. |
appgroup.name |
Nome dell'AppGroup. |
appgroup.id |
L'ID AppGroup. |
appOwnerStatus |
Lo stato del proprietario dell'app: "attivo", "non attivo" o "login_lock". |
created_at |
La data e l'ora di creazione dell'AppGroup. |
created_by |
L'indirizzo email dello sviluppatore che ha creato l'AppGroup. |
last_modified_at |
La data e l'ora dell'ultima modifica di AppGroup. |
last_modified_by |
L'indirizzo email dello sviluppatore che ha modificato l'ultima volta l'AppGroup. |
{appgroup_custom_attributes} |
Qualsiasi attributo AppGroup personalizzato. Specifica il nome dell'attributo personalizzato. |
Variabili specifiche per sviluppatori
Se app.appType
è
"Sviluppatore", gli attributi sviluppatore vengono compilati.
Variabili | Descrizione |
---|---|
Variabili specifiche per sviluppatori | |
developer.id |
|
developer.userName |
|
developer.firstName |
|
developer.lastName |
|
developer.email |
|
developer.status |
attivo o non attivo |
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. |
GenerateAuthorizationCode operazione
Queste variabili vengono impostate quando viene eseguita l'operazione generateAuthorizationCode correttamente:
Prefisso: oauthv2authcode.{policy_name}.{variable_name}
Esempio: oauthv2authcode.GenerateCodePolicy.code
Variabile | Descrizione |
---|---|
code |
Il codice di autorizzazione generato durante l'esecuzione del 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 trasmesso nella richiesta del client. |
GeneraAccessToken e Operazioni di RefreshAccessToken
Queste variabili vengono impostate quando vengono eseguite le operazioni generativeAccessToken e RefreshAccessToken correttamente. Tieni presente che le variabili token di aggiornamento non si applicano alla concessione delle credenziali del client del tipo di flusso.
Prefisso: oauthv2accesstoken.{policy_name}.{variable_name}
Esempio: oauthv2accesstoken.GenerateTokenPolicy.access_token
Nome variabile | Descrizione |
---|---|
access_token |
Il token di accesso generato. |
client_id |
L'ID client dell'app sviluppatore associata a questo token. |
expires_in |
Il valore di scadenza del token. Consulta la sezione <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 con il token. |
organization_name |
L'organizzazione in cui viene eseguito il proxy. |
api_product_list |
Un elenco dei prodotti associati all'app sviluppatore corrispondente del token. |
refresh_count |
|
refresh_token |
Il token di aggiornamento generato. Tieni presente che i token di aggiornamento non vengono generati 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 di tempo è la rappresentazione stringa del timestamp a 32 bit corrispondente quantità. Ad esempio, "Mer, 21 ago 2013 19:16:47 UTC" corrisponde al valore timestamp di 1377112607413. |
refresh_token_status |
approved o revoked . |
GenerateAccessTokenImplicitGrant
Queste variabili vengono impostate quando l'operazioneGenerateAccessTokenImplicit viene eseguita correttamente per il flusso dei tipi 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, espresso in secondi. Per informazioni dettagliate, consulta l'elemento <ExpiresIn>. |
Informazioni sugli errori
Questa sezione descrive i codici e i messaggi di errore restituiti, nonché le variabili di errore impostate da Apigee quando questo criterio attiva un errore. È importante sapere se stai sviluppando regole di errore per per gestire gli errori. Per saperne di più, consulta Cosa devi sapere sugli errori relativi ai criteri e sulla gestione di errore.
Errori di runtime
Questi errori possono verificarsi quando il criterio viene eseguito.
Codice di errore | Stato HTTP | Causa | Generato 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 dovrebbe trovare un token di accesso in una variabile specificata in
<AccessToken> elemento, 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 nel
<Code> elemento, ma non è stato possibile risolvere la variabile. |
GenerateAuthorizationCode |
steps.oauth.v2.FailedToResolveClientId |
500 |
Il criterio dovrebbe trovare l'ID client in una variabile specificata nel
<ClientId> elemento, 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 nel
<RefreshToken> elemento, ma non è stato possibile risolvere la variabile. |
RefreshAccessToken |
steps.oauth.v2.FailedToResolveToken |
500 |
Il criterio dovrebbe trovare un token in una variabile specificata nel
<Tokens> elemento, 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ù 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 errore viene utilizzato per diversi tipi di errori, in genere per gli errori mancanti
o parametri errati nella richiesta. Se <GenerateResponse> è
impostata su false , utilizza le variabili di errore (descritte di seguito) per recuperare i dettagli
l'errore, ad esempio il nome e la causa. |
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
steps.oauth.v2.InvalidAccessToken |
401 |
L'intestazione dell'autorizzazione non contiene la parola Bearer , che è obbligatoria. Per
esempio: Authorization: Bearer your_access_token |
VerifyAccessToken |
steps.oauth.v2.InvalidAPICallAsNo\ |
401 |
L'operazione o il proxy 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 il valore i caratteri jolly vengano utilizzati correttamente. Vedi Gestione dei prodotti API per maggiori dettagli. Vedi anche La verifica del token di accesso Oauth2.0 genera il messaggio "Chiamata API non valida perché non è stata trovata nessuna corrispondenza con apiproduct" errore per ulteriori indicazioni sulle cause dell'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 token
(ad es. refreshtoken ). Se il cliente trasmette il tipo errato,
viene restituito un errore. |
ValidateToken InvalidateToken |
steps.oauth.v2.MissingParameter |
500 |
Il tipo di risposta è token , ma non è specificato alcun tipo di concessione. |
GenerateAuthorizationCode GenerateAccessTokenImplicitGrant |
steps.oauth.v2.UnSupportedGrantType |
500 |
Il client ha specificato un tipo di concessione non supportato dal criterio (non elencato nel
|
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
Errori di runtime specifici del token JWT
I codici di errore 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 di token, consulta Codici di errore per i flussi di generazione e aggiornamento di token JWT riportati di seguito.
- Per il flusso di verifica del token, consulta Codici di errore per i flussi di verifica dei token riportati di seguito.
Codici di errore per i flussi di generazione e aggiornamento 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 di errore.
Codici di errore per il flusso di verifica del token
I codici di errore elencati nella seguente tabella si applicano solo al funzionamento di VerifyAccessToken.
Codice di errore | Stato HTTP | Causa | Generato dalle operazioni |
---|---|---|---|
oauth.v2.JWTSigningFailed |
401 |
Il criterio non è stato in grado di 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 degli algoritmi HS384 o HS512 |
|
oauth.v2.JWTAlgorithmMismatch |
401 |
L'algoritmo specificato nel criterio 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 di accesso Jwt |
|
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 positivi
numeri interi e -1 . |
InvalidGrantType |
È stato specificato un tipo di concessione non valido in <SupportedGrantTypes>
. Consulta la guida di riferimento alle norme per un elenco dei tipi validi. |
ExpiresInNotApplicableForOperation |
Assicurati che le operazioni specificate nell'elemento <Operations> supportino
la scadenza del periodo di conservazione. Ad esempio, l'operazione VerifyToken non esegue questa operazione. |
RefreshTokenExpiresInNotApplicableForOperation |
Assicurati che le operazioni specificate nell'elemento <Operations> supportino l'aggiornamento
e la scadenza del token. Ad esempio, l'operazione VerifyToken non lo fa. |
GrantTypesNotApplicableForOperation |
Assicurati che i tipi di autorizzazione specificati in <SupportedGrantTypes> siano supportati per
dell'operazione specificata. |
OperationRequired |
Devi specificare un'operazione in questo criterio utilizzando l' |
InvalidOperation |
Devi specificare un'operazione valida in questo criterio utilizzando il metodo
Elemento |
TokenValueRequired |
Devi specificare un valore del token <Token> nel
Elemento <Tokens> . |
Errori di deployment specifici per i token JWT
Questi errori di deployment sono specifici dei criteri che utilizzano le operazioni del token JWT.
Nome errore | Causa |
---|---|
InvalidValueForAlgorithm |
L'algoritmo specificato nell'elemento <Algorithm> non è
nell'elenco degli algoritmi disponibili o non è presente. |
MissingKeyConfiguration |
I seguenti valori obbligatori sono <SecretKey> , <PrivateKey> o
Elementi <PublicKey> mancanti, a seconda dell'algoritmo utilizzato. |
EmptyValueElementForKeyConfiguration |
L'elemento secondario obbligatorio <Value> non è definito nel
Elementi <PrivateKey> , <PublicKey> o <SecretKey> |
InvalidKeyConfiguration |
L'elemento <PrivateKey> non viene utilizzato con gli algoritmi della famiglia RSA o <SecretKey>
non viene utilizzato con gli algoritmi HS Family. |
EmptyRefAttributeForKeyconfiguration |
Attributo ref dell'elemento secondario <Value> di
gli elementi <PrivateKey> , <PublicKey> o <SecretKey> sono vuoti. |
InvalidVariableNameForKey |
Il nome della variabile di flusso specificato nell'attributo ref dell'elemento secondario
l'elemento <Value> di <PrivateKey> ,
Gli elementi <PublicKey> o <SecretKey> non
contengono il prefisso private . |
Variabili di errore
Queste variabili vengono impostate quando il criterio attiva un errore in fase di runtime.
Variabili | Dove | Esempio |
---|---|---|
fault.name="fault_name" |
fault_name è il nome dell'errore, come elencato nella precedente tabella Errori di runtime. Il nome dell'errore è 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 inviate al client se <GenerateResponse>
è true.
Se <GenerateResponse>
è true, il criterio restituisce errori
in questo formato per le operazioni che generano token e codici. Per un elenco completo, vedi
Errore HTTP OAuth
riferimento della risposta.
{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}
Se <GenerateResponse>
è true, il criterio restituisce errori
per le operazioni di verifica
e convalida. Per un elenco completo, vedi Errore HTTP OAuth
riferimento della risposta.
{ { "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 in Storage sono sottoposti ad hashing
Se utilizzi Apigee hybrid o Apigee, i token di accesso OAuthV2 e di aggiornamento sono sottoposti ad hashing per impostazione predefinita se archiviati nel database Cassandra del runtime. Hashing impedisce l'utilizzo dei token in caso di compromissione del database.
Utilizzare il protocollo OAuth predefinito configurazione
A ogni organizzazione (anche in prova gratuita) su Apigee viene eseguito il provisioning di un token OAuth endpoint. L'endpoint è preconfigurato con criteri nel proxy API chiamato oauth. Puoi iniziare a utilizzare l'endpoint del token non appena lo crei un account su Apigee. Per Per maggiori dettagli, consulta la pagina Informazioni su OAuth endpoint.
Eseguire l'eliminazione definitiva dei token di accesso
Per impostazione predefinita, i token OAuth2 vengono eliminati definitivamente dal sistema Apigee per 3 giorni (259.200 secondi) dopo che il token di accesso e il token di aggiornamento (se esistente) sono scaduti.
Comportamento non conforme a RFC
Per impostazione predefinita, il criterio OAuthV2, con l'operazione GeneraAccessToken, restituisce una risposta del token che contiene alcune proprietà non compatibili con RFC. La tabella seguente mostra le non conformi proprietà restituite dal criterio OAuthV2 e dalle corrispondenti proprietà conformi.
OAuthV2 restituisce: | La proprietà conforme alla specifica 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 alla specifica RFC è:
{"error" : "invalid_grant", "error_description" :"refresh token expired"}