Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Cosa
OAuthV2 è un criterio eterogeneo 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 Edge.
Suggerimento: per saperne di più su OAuth su Apigee Edge, consulta la home page di OAuth. Fornisce link a risorse, esempi, video e altro ancora. Consulta l'esempio avanzato di OAuth su GitHub per una buona dimostrazione di come viene utilizzato questo criterio in un'applicazione funzionante.
Esempi
VerifyAccessToken
VerifyAccessToken
Questa configurazione dei criteri OAuthV2 (con l'operazione VerificationAccessToken) verifica che un token di accesso inviato ad Apigee Edge sia valido. Quando viene attivata questa operazione del criterio, Edge cerca un token di accesso valido nella richiesta. Se il token di accesso è valido, la richiesta può procedere. Se non è valida, l'intera elaborazione si interrompe e viene restituito un errore nella risposta.
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuth-v20-2"> <DisplayName>OAuth v2.0 2</DisplayName> <Operation>VerifyAccessToken</Operation> <AccessTokenPrefix>Bearer</AccessTokenPrefix> <!-- Optional, default is Bearer --> </OAuthV2>
Nota: sono supportati solo i token di connessione OAuth 2.0. I token MAC (Message Authentication Code) non sono supportati.
Ad esempio:
$ curl -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282
Per impostazione predefinita, Edge accetta i token di accesso nell'intestazione Authorization
con il prefisso Bearer
. Puoi modificare questa impostazione predefinita con l'elemento
<AccessToken>
.
GenerateAccessToken
Generazione dei token di accesso
Per esempi che mostrano come richiedere token di accesso per ciascuno dei tipi di autorizzazione supportati, consulta la sezione Richiedere token di accesso e codici di autorizzazione. L'argomento include esempi di queste operazioni:
GenerateAuthorizationCode
Genera codice di autorizzazione
Per esempi che mostrano come richiedere i codici di autorizzazione, consulta Richiesta di un codice di autorizzazione.
RefreshAccessToken
Aggiornare un token di accesso
Per esempi che mostrano come richiedere token di accesso utilizzando un token di aggiornamento, consulta la sezione Aggiornare un token di accesso.
Token di 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.
Diamo innanzitutto 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, l'operazione non andrà a buon fine e verrà visualizzato un errore 401 Non autorizzato, anche se nel criterio vengono 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 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 "local_clientid" e "local_secret" devono essere precedentemente impostate e disponibili nel flusso:
var client_id = context.getVariable("local_clientid"); var client_secret = context.getVariable("local_secret"); context.setVariable("request.header.Authorization","Basic "+CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1 .parse(client_id + ':' + client_secret)));
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, consulta le descrizioni degli elementi in questa sezione.
<OAuthV2 name="GenerateAccessToken"> <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type --> <Operation>GenerateAccessToken</Operation> <!-- This is in millseconds, so expire in an hour --> <ExpiresIn>3600000</ExpiresIn> <SupportedGrantTypes> <GrantType>client_credentials</GrantType> </SupportedGrantTypes> <GrantType>request.queryparam.grant_type</GrantType> <GenerateResponse/> </OAuthV2>
Attributi <OAuthV2>
<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">
La tabella seguente descrive gli attributi comuni a tutti gli elementi principali dei criteri:
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
name |
Il nome interno della norma. Il valore dell'attributo Facoltativamente, utilizza l'elemento |
N/A | Obbligatorie |
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, VerificationAccessToken prevede che il token di accesso venga inviato nell'intestazione Authorization
.
Puoi modificare il valore predefinito utilizzando questo elemento. Ad esempio, request.queryparam.access_token
indica che il token di accesso deve essere presente come parametro di ricerca denominato access_token
.
<AccessToken>request.header.access_token</AccessToken>
:
curl https://myorg-myenv.apigee.net/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"Esempio in cui è specificato
<AccessToken>request.queryparam.access_token</AccessToken>
:
curl "https://myorg-myenv.apigee.net/oauth2/validate?access_token:Rft3dqrs56Blirls56a"
Predefinito: |
N/A |
Presenza: |
Facoltativo |
Tipo: | Stringa |
Utilizzata per le operazioni: |
|
Elemento <AccessTokenPrefisso>
<AccessTokenPrefix>Bearer</AccessTokenPrefix>
Per impostazione predefinita, VerificationAccessToken prevede che il token di accesso venga inviato in un'intestazione di autorizzazione come token di connessione. Ad esempio:
-H "Authorization: Bearer Rft3dqrs56Blirls56a"
Attualmente, l'unico prefisso supportato è Bearer.
Predefinito: |
Bearer |
Presenza: |
Facoltativo |
Tipo: | Stringa |
Valori validi: |
Bearer |
Utilizzata per le operazioni: |
|
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 Edge deve cercare l'ID utente finale. Ad esempio, potrebbe essere inviato come parametro di ricerca 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 AppEndUser in un'intestazione
HTTP, imposta questo valore su request.header.app_enduser
.
Se specifichi questa impostazione, puoi includere un ID utente finale dell'app nel token di accesso. Questa funzionalità è utile se vuoi essere in grado di recuperare o revocare i token di accesso OAuth 2.0 in base all'ID utente finale. Per maggiori informazioni, consulta la sezione Attivare il recupero e la revoca dei token di accesso OAuth 2.0 per ID utente finale, ID app o entrambi.
Predefinito: |
N/A |
Presenza: |
Facoltativo |
Tipo: | Stringa |
Valori validi: |
Qualsiasi variabile di flusso accessibile al criterio in fase di runtime. |
Utilizzata 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 durante il 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 è l'impostazione predefinita.
Per ulteriori informazioni sull'uso di questo elemento, vedi Personalizzazione di token e codici di autorizzazione.
Visualizzare o nascondere gli attributi personalizzati nella risposta
Ricorda che se imposti l'elemento GeneraResponse di questo criterio su true, nella risposta viene restituita la rappresentazione JSON completa del token, inclusi gli eventuali attributi personalizzati che hai impostato. In alcuni casi, potresti voler nascondere alcuni o tutti gli attributi personalizzati nella risposta in modo che non siano visibili alle app client.
Per impostazione predefinita, gli attributi personalizzati vengono visualizzati nella risposta. Se vuoi nasconderli, puoi impostare il parametro display su false. Ad esempio:
<Attributes> <Attribute name="employee_id" ref="employee.id" display="false"/> <Attribute name="employee_name" ref="employee.name" display="false"/> </Attributes>
Il valore dell'attributo display
non è persistente. Supponiamo che generi un token di accesso con attributi personalizzati che vuoi nascondere nella
risposta generata. Imposta display=false
per raggiungere l'obiettivo. Tuttavia, se un nuovo token di accesso viene generato in un secondo momento utilizzando un token di aggiornamento, gli attributi personalizzati originali del token di accesso verranno visualizzati nella risposta del token di aggiornamento. Questo perché Edge non ricorda che
l'attributo display
era originariamente impostato su false
nel criterio di generazione del token di accesso, in quanto l'attributo
personalizzato fa semplicemente parte dei metadati del token di accesso.
Vedrai lo stesso comportamento se aggiungi attributi personalizzati a un codice di autorizzazione: quando viene generato un token di accesso utilizzando quel codice, gli attributi personalizzati vengono 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, potrebbe essere necessario recuperare i valori personalizzati originali dal token di accesso originale utilizzando il criterio GetOAuthV2Info.
- Utilizza un criterio JavaScript di post-elaborazione per estrarre manualmente gli attributi personalizzati che non vuoi visualizzare nella risposta.
Vedi anche Personalizzazione di token e codici di autorizzazione.
Predefinito: |
|
Presenza: |
Facoltativo |
Valori validi: |
|
Utilizzata con i tipi di autorizzazione: |
|
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 Edge deve cercare l'ID client. L'unica località valida che puoi impostare è quella predefinita, la variabile di flusso request.formparam.client_id
. L'impostazione di ClientId
su qualsiasi altra variabile non è supportata.
Vedi anche Richiedere token di accesso e codici di autorizzazione.
Predefinito: |
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 |
Utilizzata con i tipi di autorizzazione: |
Può essere utilizzato anche con l'operazione GeneraAuthorizationCode. |
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 Edge). Questo elemento consente di specificare dove Edge deve cercare il codice di autorizzazione. Ad esempio, potrebbe essere inviato come parametro di ricerca, intestazione HTTP o parametro modulo (valore predefinito).
La variabile request.queryparam.auth_code
indica che il codice di autorizzazione deve essere presente come parametro di ricerca, 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
Richiedere token di accesso e
codici di autorizzazione.
Predefinito: |
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 |
Utilizzata con i tipi di autorizzazione: | authorization_code |
Elemento<TIMESTAMPIn>
<ExpiresIn>10000</ExpiresIn>
Applica il tempo di scadenza dei token di accesso e dei codici di autorizzazione in millisecondi. (Per i token di aggiornamento, utilizza <RefreshTokenExpiresIn>
.) Il valore della 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
.
Con Apigee Edge per il cloud pubblico, Edge mantiene nella cache le seguenti entità per almeno 180 secondi dopo l'accesso alle entità.
- Token di accesso OAuth. Ciò significa che un token revocato può comunque avere esito positivo per un massimo di tre minuti, fino alla scadenza del limite di cache.
- 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>
Edge non supporta un modo per forzare la scadenza di un token dopo la sua creazione. Se devi forzare la scadenza del token (ad esempio in base a una condizione), una possibile soluzione è descritta in questo post della community Apigee.
Per impostazione predefinita, i token di accesso scaduti vengono eliminati definitivamente dal sistema Apigee Edge automaticamente 3 giorni dopo la scadenza. Vedi anche Eliminazione definitiva dei token di accesso
Private Cloud: per un'installazione Edge per cloud privato, il valore predefinito è impostato dalla proprietà conf_keymanagement_oauth_auth_code_expiry_time_in_millis
.
Per impostare questa proprietà:
- Apri il file
message-processor.properties
in un editor. Se il file non esiste, crealo:vi /opt/apigee/customer/application/message-processor.properties
- Imposta la proprietà come preferisci:
conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000
- Assicurati che il file delle proprietà sia di proprietà dell'utente "apigee":
chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
- Riavvia il processore di messaggi.
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
Predefinito: |
Se non specificato, il sistema applica un valore predefinito configurato a livello di sistema. |
Presenza: |
Facoltativo |
Tipo: | Numero intero |
Valori validi: |
|
Utilizzata con i tipi di autorizzazione: |
Utilizzato anche con l'operazione GeneraAuthorizationCode. |
Elemento <ExternalAccessToken>
<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>
Indica ad Apigee Edge dove trovare un token di accesso esterno (un token di accesso non generato da Apigee Edge).
La variabile request.queryparam.external_access_token
indica che
il token di accesso esterno deve essere presente come parametro di ricerca, 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
. Vedi anche Utilizzo di token OAuth di terze parti.
Elemento <ExternalAuthorization>
<ExternalAuthorization>true</ExternalAuthorization>
Se questo elemento è false o non è presente, Edge convalida i valori client_id e client_secret normalmente rispetto all'archivio autorizzazioni Apigee Edge. Utilizza questo elemento quando vuoi lavorare con token OAuth di terze parti. Per maggiori dettagli sull'utilizzo di questo elemento, consulta la pagina relativa all'utilizzo di token OAuth di terze parti.
Predefinito: |
false |
Presenza: |
Facoltativo |
Tipo: | Booleano |
Valori validi: | true o false |
Utilizzata con i tipi di autorizzazione: |
|
Elemento <ExternalAuthorizationCode>
<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>
Indica ad Apigee Edge dove trovare un codice di autenticazione esterno (un codice di autenticazione non generato da Apigee Edge).
La variabile request.queryparam.external_auth_code
indica che
il codice di autorizzazione esterno deve essere presente come parametro di ricerca, 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
. Vedi anche Utilizzo di token OAuth di terze parti.
Elemento <ExternalrefreshToken>
<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>
Indica ad Apigee Edge dove trovare un token di aggiornamento esterno (un token di aggiornamento non generato da Apigee Edge).
La variabile request.queryparam.external_refresh_token
indica che
il token di aggiornamento esterno deve essere presente come parametro di ricerca, 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
. Vedi anche Utilizzo di token OAuth di terze parti.
Elemento <GeneraResponse>
<GenerateResponse enabled='true'/>
Se viene impostato su true
, il criterio genera e restituisce una risposta. Ad esempio, per GeneraAccessToken, 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 false
, non viene inviata alcuna risposta. Un insieme di variabili di flusso viene invece completato 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 creato. Tieni presente che expires_in è espresso in secondi nella
risposta.
Predefinito: |
false |
Presenza: |
Facoltativo |
Tipo: | stringa |
Valori validi: | true o false |
Utilizzata con i tipi di autorizzazione: |
|
Elemento <GeneraErrorResponse>
<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.
Predefinito: |
false |
Presenza: |
Facoltativo |
Tipo: | stringa |
Valori validi: | true o false |
Utilizzata con i tipi di autorizzazione: |
|
<GrantType>
<GrantType>request.queryparam.grant_type</GrantType>
Indica al criterio dove trovare il parametro del tipo di autorizzazione trasmesso 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 di 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 Richiedere token di accesso e codici di autorizzazione.
Predefinito: |
request.formparam.grant_type (un x-www-form-urlcodificato e specificato nel corpo della richiesta) |
Presenza: |
Facoltativo |
Tipo: | stringa |
Valori validi: | Una variabile, come spiegato in precedenza. |
Utilizzata con i tipi di autorizzazione: |
|
Elemento <Operation>
<Operation>GenerateAuthorizationCode</Operation>
L'operazione OAuth 2.0 eseguita dal criterio.
Predefinito: |
Se |
Presenza: |
Facoltativo |
Tipo: | Stringa |
Valori validi: |
|
Elemento <PassWord>
<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>
vengono utilizzati per specificare le variabili in cui Edge può trovare questi valori. Se questi elementi non sono specificati,
il criterio prevede di trovare i valori (per impostazione predefinita) nei parametri del formato 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 esegue altre operazioni con questi valori delle credenziali; Edge si limita a verificare che siano presenti. Spetta allo sviluppatore dell'API recuperare la richiesta dei valori e inviarle a un provider di identità prima che venga eseguito il criterio di generazione del token.
Vedi anche Richiedere token di accesso e codici di autorizzazione.
Predefinito: |
request.formparam.password (un x-www-form-urlcodificato e specificato nel corpo della richiesta) |
Presenza: |
Facoltativo |
Tipo: | Stringa |
Valori validi: | Qualsiasi variabile di flusso disponibile per il criterio in fase di runtime. |
Utilizzata con i tipi di autorizzazione: | password |
Elemento < RedirectUri>
<RedirectUri>request.queryparam.redirect_uri</RedirectUri>
Specifica dove Edge deve cercare il parametro redirect_uri
nella
richiesta.
Informazioni sugli URI di reindirizzamento
Gli URI di reindirizzamento vengono utilizzati con il codice di autorizzazione e i tipi di autorizzazione impliciti. L'URI di reindirizzamento indica al server di autorizzazione (Edge) dove inviare un codice di autorizzazione (per il tipo di concessione del codice di autorizzazione) o un 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 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 Edge e sulla specifica di un URL di callback, consulta Registrare app e gestire le chiavi API. - (Facoltativo) Se un URL di callback è registrato e
redirect_uri
non è presente nella richiesta, Edge reindirizza all'URL di callback registrato. - (Obbligatorio) Se un URL di callback non è registrato, devi specificare
redirect_uri
. Tieni presente che in questo caso Edge 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 ricerca o in un'intestazione. La variabile request.queryparam.redirect_uri
indica che RedirectUri deve essere presente come parametro di ricerca, 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 Richiedere token di accesso e codici di autorizzazione.
Predefinito: |
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 |
Utilizzata con i tipi di autorizzazione: |
Utilizzato anche con l'operazione GeneraAuthorizationCode. |
Elemento <refreshToken>
<RefreshToken>request.queryparam.refreshtoken</RefreshToken>
Se richiedi un token di accesso utilizzando un token di aggiornamento, devi fornire il token di aggiornamento nella richiesta. Questo elemento consente di specificare dove Edge deve cercare il token di aggiornamento. Ad esempio, potrebbe essere inviato come parametro di ricerca, intestazione HTTP o parametro di modulo (valore predefinito).
La variabile request.queryparam.refreshtoken
indica che il token di aggiornamento deve essere presente come parametro di ricerca, ad esempio ?refresh_token=login.myapp.com
. Ad esempio, per richiedere il valore UpdateToken in un'intestazione HTTP, imposta questo valore su request.header.refresh_token
. Vedi anche Richiedere token di accesso e codici di autorizzazione.
Predefinito: |
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 |
Utilizzata con i tipi di autorizzazione: |
|
Elemento <refreshTokenexpirationIn>
<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>
Applica il tempo di 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,
per impostazione predefinita la scadenza è indefinita.
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"> 3600000 <!--default value in milliseconds--> </RefreshTokenExpiresIn>
Private Cloud: per un'installazione Edge per cloud privato, il valore predefinito è impostato dalla proprietà conf_keymanagement_oauth_refresh_token_expiry_time_in_millis
.
Per impostare questa proprietà:
- Apri il file
message-processor.properties
in un editor. Se il file non esiste, crealo:vi /opt/apigee/customer/application/message-processor.properties
- Imposta la proprietà come preferisci:
conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000
- Assicurati che il file delle proprietà sia di proprietà dell'utente "apigee":
chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
- Riavvia il processore di messaggi.
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
Predefinito: |
Se non specificato, il sistema applica un valore predefinito configurato a livello di sistema. |
Presenza: |
Facoltativo |
Tipo: | Numero intero |
Valori validi: |
|
Utilizzata con i tipi di autorizzazione: |
|
"refresh_token_expires_in" : "0"
.Elemento <ResponseType>
<ResponseType>request.queryparam.response_type</ResponseType>
Questo elemento indica a Edge il tipo di concessione richiesto dall'app client. Viene utilizzato solo con il codice di autorizzazione e i flussi di tipo di autorizzazione impliciti.
Per impostazione predefinita, Edge 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
, Edge cerca il tipo di risposta da passare nell'intestazione della richiesta. Vedi anche Richiedere token di accesso e codici di autorizzazione.
Predefinito: |
request.formparam.response_type (un x-www-form-urlcoded e specificato nel corpo della richiesta) |
Presenza: |
Campo 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 autorizzazione implicita) |
Utilizzata con i tipi di autorizzazione: |
|
Elemento <ReuserefreshToken>
<ReuseRefreshToken>true</ReuseRefreshToken>
Se il criterio viene impostato su true
, il token di aggiornamento esistente viene riutilizzato fino alla scadenza. Se false
, quando viene presentato un token di aggiornamento valido, viene emesso un nuovo token di aggiornamento da Apigee Edge.
Predefinito: |
|
Presenza: |
facoltativo |
Tipo: | boolean |
Valori validi: |
|
Utilizzata con il tipo di autorizzazione: |
|
Elemento <Scope>
<Scope>request.queryparam.scope</Scope>
Se questo elemento è presente in uno dei criteri GeneraAccessToken o GeneraAuthorizationCode, viene utilizzato per specificare a quali ambiti concedere il token o il codice. Questi valori in genere vengono passati al criterio nella richiesta da un'app client. Puoi configurare l'elemento in modo che utilizzi una variabile di flusso per scegliere in che modo passare 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 Richiesta di token di accesso e codici di autorizzazione.
Predefinito: |
Nessun ambito |
Presenza: |
Facoltativo |
Tipo: | Stringa |
Valori validi: |
Se utilizzata con i criteri Genera*, una variabile di flusso. Se utilizzato con VerificationAccessToken, un elenco separato da spazi di nomi di ambiti (stringhe). |
Utilizzata con i tipi di autorizzazione: |
|
Elemento <State>
<State>request.queryparam.state</State>
Nei casi in cui l'app client deve inviare le informazioni sullo stato al server di autorizzazione, questo elemento consente di specificare dove Edge deve cercare i valori dello stato. Ad esempio, potrebbe essere inviato come parametro di ricerca 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 ricerca, ad esempio ?state=HjoiuKJH32
. Ad esempio, per richiedere lo stato in un'intestazione HTTP, imposta questo valore su request.header.state
. Vedi anche Richiedere token di accesso e codici di autorizzazione.
Predefinito: |
Nessuno stato |
Presenza: |
Facoltativo |
Tipo: | Stringa |
Valori validi: | Qualsiasi variabile di flusso accessibile al criterio in fase di runtime |
Utilizzata 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 Edge di archiviare il token di accesso esterno. In caso contrario, non sarà salvata.
Predefinito: |
false |
Presenza: |
Facoltativo |
Tipo: | Booleano |
Valori validi: | true o false |
Utilizzata 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 Edge. Un endpoint può supportare più tipi di concessioni (vale a dire, è possibile configurare un singolo endpoint per la distribuzione di 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 vengono specificati tipi di autorizzazione supportati, gli unici tipi di autorizzazione consentiti sono
authorization_code
e implicit
. Vedi anche l'elemento <GrantType> (un elemento di livello superiore utilizzato per specificare dove Apigee Edge deve cercare il parametro grant_type
che viene passato in una richiesta del client). Edge si assicurerà che il valore del parametro grant_type
corrisponda a uno dei tipi di autorizzazione supportati).
Predefinito: |
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. Se gli sviluppatori devono inviare token di accesso come
parametri di query denominati access_token
, ad esempio,
utilizza request.queryparam.access_token
.
Elemento <UserName>
<UserName>request.queryparam.user_name</UserName>
Questo elemento viene utilizzato solo con il tipo di 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>
vengono utilizzati per specificare le variabili in cui Edge può trovare questi valori. Se questi elementi non sono specificati,
il criterio prevede di trovare i valori (per impostazione predefinita) nei parametri del formato 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 ricerca 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 esegue altre operazioni con questi valori delle credenziali; Edge si limita a verificare che siano presenti. Spetta allo sviluppatore dell'API recuperare la richiesta dei valori e inviarle a un provider di identità prima che venga eseguito il criterio di generazione del token.
Vedi anche Richiedere token di accesso e codici di autorizzazione.
Predefinito: |
request.formparam.username (un x-www-form-urlcoded e specificato nel corpo della richiesta) |
Presenza: |
Facoltativo |
Tipo: | Stringa |
Valori validi: | Impostazione di qualsiasi variabile. |
Utilizzata con i tipi di autorizzazione: | password |
Verificare i token di accesso
Dopo aver configurato un endpoint token per un proxy API, un criterio OAuthV2 corrispondente che specifica l'operazione VerifyAccessToken
viene associato al flusso che espone la risorsa protetta.
Ad esempio, per garantire che tutte le richieste a un'API siano autorizzate, il seguente criterio 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, collega il criterio al pre-flusso della richiesta ProxyEndpoint, come segue:
<PreFlow> <Request> <Step><Name>VerifyOAuthAccessToken</Name></Step> </Request> </PreFlow>
I seguenti elementi facoltativi possono essere usati per eseguire l'override delle impostazioni predefinite per l'operazione VerificationAccessToken.
Nome | Descrizione |
---|---|
Ambito |
Un elenco di ambiti delimitati 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 avrà esito positivo. <OAuthV2 name="ValidateOauthScopePolicy"> <Operation>VerifyAccessToken</Operation> <Scope>READ WRITE</Scope> </OAuthV2> |
AccessToken | La variabile in cui si prevede che si trovi il token di accesso. Ad esempio
request.queryparam.accesstoken . Per impostazione predefinita, il token di accesso dovrebbe essere
presentato dall'app nell'intestazione HTTP di autorizzazione, in base alla specifica OAuth 2.0. Utilizza questa impostazione se il token di accesso deve essere visualizzato 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 Richiesta di token di accesso e codici di autorizzazione.
Specificare le posizioni delle variabili di richiesta
Per ogni tipo di autorizzazione, il criterio formula ipotesi sulla località 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 ciascun parametro. Ad esempio, quando gestisci un codice di autorizzazione, puoi specificare la località del codice di autorizzazione, l'ID client, l'URI di reindirizzamento e l'ambito. Questi possono essere specificati come intestazioni HTTP, parametri di query o parametri 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 dell'app client, puoi combinare intestazioni e parametri di query:
... <GrantType>request.header.grant_type</GrantType> <Code>request.header.code</Code> <ClientId>request.queryparam.client_id</ClientId> <RedirectUri>request.queryparam.redirect_uri</RedirectUri> <Scope>request.queryparam.scope</Scope> ...
È possibile configurare una sola località per parametro.
Variabili di flusso
Le variabili di flusso definite in questa tabella vengono compilate quando vengono eseguiti i rispettivi criteri OAuth e, pertanto, sono disponibili per altri criteri o applicazioni in esecuzione nel flusso proxy API.
Operazione VerificationAccessToken
L'operazione VerificationAccessToken viene eseguita; un numero elevato di variabili di flusso è completato nel contesto di esecuzione del proxy. Queste variabili forniscono proprietà relative al token di accesso, all'app dello sviluppatore, allo sviluppatore e all'azienda. Ad esempio, puoi utilizzare un criterio AssegnaMessage o JavaScript per leggere una qualsiasi di queste variabili e utilizzarle in base alle esigenze in un secondo momento nel flusso. Queste variabili possono essere utili anche per scopi di debug.
proxy.pathsuffix
). Non è necessario impostare esplicitamente la variabile flow.resource.name.
Se i prodotti API non sono configurati con ambienti e proxy API validi, flow.resource.name
deve essere impostato esplicitamente per completare le variabili dei prodotti API nel flusso. Per maggiori dettagli sulla configurazione del prodotto, vedi Utilizzo dell'API Edge Management
per pubblicare le API.
Variabili specifiche per token
Variabili | Descrizione |
---|---|
organization_name |
Il nome dell'organizzazione su cui viene eseguito il proxy. |
developer.id |
L'ID dello sviluppatore associato all'app client registrata. |
developer.app.name |
Il nome dello sviluppatore associato all'app client registrata. |
client_id |
L'ID client dell'app client registrata. |
grant_type |
Il tipo di autorizzazione associato alla richiesta. |
token_type |
Il tipo di token associato alla richiesta. |
access_token |
Il token di accesso che è 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 hybrid) Indica il motivo per cui il token di accesso è stato revocato. 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 sviluppatori
Se app.appType è "Company", gli attributi dell'azienda vengono compilati e se app.appType è "Developer", vengono compilati gli attributi sviluppatore.
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. |
Variabili specifiche dell'azienda
Se app.appType è "Company", gli attributi dell'azienda vengono compilati e se app.appType è "Developer", vengono compilati gli attributi sviluppatore.
Variabili | Descrizione |
---|---|
company.id |
|
company.displayName |
|
company.apps |
|
company.appOwnerStatus |
|
company.created_by |
|
company.created_at |
|
company.last_modified_at |
|
company.last_modified_by |
|
company.{custom_attributes} |
Un attributo personalizzato denominato dell'azienda. |
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 trasmesso nella richiesta del client. |
client_id |
L'ID client trasmesso nella richiesta del client. |
Operazioni generateAccessToken e refreshAccessToken
Queste variabili vengono impostate quando le operazioni generateAccessToken e refreshAccessToken vengono eseguite correttamente. Tieni presente che le variabili dei token di aggiornamento non si applicano al flusso del tipo di concessione delle credenziali client.
Prefisso: oauthv2accesstoken.{policy_name}.{variable_name}
Esempio: oauthv2accesstoken.GenerateTokenPolicy.access_token
Nome variabile | Descrizione |
---|---|
access_token |
Il token di accesso che è stato generato. |
client_id |
L'ID client dell'app sviluppatore associata 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 per sviluppatori associata al token. |
organization_name |
L'organizzazione su 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 che è stato generato. Tieni presente che i token di aggiornamento non vengono generati per il tipo di concessione delle credenziali client. |
refresh_token_expires_in |
La durata del token di aggiornamento, in secondi. |
refresh_token_issued_at |
Questo valore temporale è la rappresentazione in formato stringa della quantità del timestamp a 32 bit corrispondente. Ad esempio, "Mer, 21 Aug 2013 19:16:47 UTC" corrisponde al valore del timestamp 1377112607413. |
refresh_token_status |
approved o revoked . |
GenerateAccessTokenImplicitGrant
Queste variabili vengono impostate quando l'operazione 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 quando il criterio viene eseguito. |
oauthv2accesstoken.{policy_name}.expires_in |
Il valore di scadenza del token, espresso in secondi. Consulta l'elemento <ExpiresIn> per i dettagli. |
Riferimento errore
Questa sezione descrive i codici e i messaggi di errore restituiti e le variabili di errore impostate da Edge 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. |
VerificationAccessToken |
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. |
GeneraAccessToken TranslateAuthorizationCode generareAccessTokenImplicitGrant 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. |
ConvalidaToken |
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à Nota: ti consigliamo di modificare le condizioni delle regole di errore esistenti in modo da rilevare entrambi i nomi |
GeneraAccessToken AggiornaAccessToken |
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. |
GeneraAccessToken TranslateAuthorizationCode generareAccessTokenImplicitGrant refreshAccessToken |
steps.oauth.v2.InvalidAccessToken |
401 | L'intestazione di autorizzazione non contiene la parola "Bearer", che è obbligatoria. Ad
esempio: Authorization: Bearer your_access_token |
VerifyAccessToken |
steps.oauth.v2.InvalidAPICallAsNo\ |
401 |
Il proxy API 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 maggiori dettagli, vedi Creare prodotti basati su API. Consulta anche questo post della community di Apigee per ulteriori indicazioni sulle cause di questo errore. |
VerifyAccessToken |
steps.oauth.v2.InvalidClientIdentifier |
500 |
Questo nome di errore viene restituito quando la proprietà |
GeneraAccessToken |
steps.oauth.v2.InvalidParameter |
500 | Il criterio deve specificare un token di accesso o un codice di autorizzazione, ma non entrambi. | DataflowAuthorizationCode generareAccessTokenImplicitGrant |
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. |
ConvalidaToken InvalidateToken |
steps.oauth.v2.MissingParameter |
500 | Il tipo di risposta è token , ma non è specificato alcun tipo di autorizzazione. |
DataflowAuthorizationCode generareAccessTokenImplicitGrant |
steps.oauth.v2.UnSupportedGrantType |
500 |
Il client ha specificato un tipo di autorizzazione non supportato dal criterio (non elencato nell'elemento <SupportedGrantTypes>). Nota: attualmente esiste un bug per cui gli errori relativi ai tipi di autorizzazione non supportati non vengono generati correttamente. Se si verifica un errore di tipo di autorizzazione non supportato, il proxy non entra nel flusso di errori, come previsto. |
GeneraAccessToken TranslateAuthorizationCode generareAccessTokenImplicitGrant refreshAccessToken |
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 VerificationToken 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 Nota: se l'elemento |
InvalidOperation |
Devi specificare un'operazione valida in questo criterio utilizzando
l'elemento Nota: se l'elemento |
TokenValueRequired |
Devi specificare un valore <Token> del token nell'elemento <Tokens> . |
Variabili di errore
Queste variabili vengono impostate quando questo criterio attiva un errore in fase di runtime.
<GenerateResponse>
è impostato su
false
. Se <GenerateResponse>
è
true
, il criterio restituisce immediatamente una risposta al client se si verifica un errore:
il flusso degli errori viene ignorato e queste variabili non vengono compilate. Per maggiori informazioni, consulta Cosa devi sapere sugli errori relativi ai criteri.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
Nota: per l'operazione VerificationAccessToken, il nome dell'errore include questo suffisso: |
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.
errorcode
della risposta di errore. Non fare affidamento sul testo in faultstring
, perché potrebbe cambiare.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>
Schema dei criteri
Ogni tipo di criterio è definito da uno schema XML (.xsd
). Come riferimento, gli schemi dei criteri sono disponibili in GitHub.
Utilizzare la configurazione OAuth predefinita
Il provisioning di ogni organizzazione (anche di un'organizzazione di prova senza costi) su Apigee Edge viene eseguito 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 Edge. 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 Edge 3 giorni (259.200 secondi) dopo la scadenza del token di accesso e del token di aggiornamento (se esistente). In alcuni casi potrebbe essere necessario modificare questa impostazione predefinita. Ad esempio, potresti voler ridurre il tempo di eliminazione definitiva per risparmiare spazio su disco se viene generato un numero elevato di token.
Se ti trovi su Edge per cloud privato, puoi modificare questa impostazione predefinita impostando le proprietà dell'organizzazione come spiegato in questa sezione. (L'eliminazione definitiva dei token scaduti di 3 giorni si applica a Edge per Private Cloud versione 4.19.01 e successive. Per le versioni precedenti, l'intervallo predefinito di eliminazione definitiva è 180 giorni).
Aggiornamento delle impostazioni di eliminazione definitiva per Edge Private Cloud 4.16.01 e versioni successive
Nota: sono interessati solo i token generati dopo l'applicazione di queste impostazioni; le impostazioni non si applicano ai token generati in precedenza.
- Apri questo file per la modifica:
/opt/apigee/customer/application/message-processor.properties
- Aggiungi la seguente proprietà per impostare il numero di secondi di attesa prima di eliminare definitivamente un token
dopo la scadenza:
conf_keymanagement_oauth.access.token.purge.after.seconds=<number of seconds>
- Riavvia il processore dei messaggi. Ad esempio:
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
<ExpiresIn>
e
<RefreshTokenExpiresIn>
.
Aggiornamento delle impostazioni di eliminazione definitiva per Edge Private Cloud 4.15.07
Nota: sono interessati solo i token generati dopo l'applicazione di queste impostazioni; le impostazioni non si applicano ai token generati in precedenza.
-
Imposta valori positivi per gli attributi
<ExpiresIn>
e<RefreshTokenExpiresIn>
nel criterio OAuthV2. I valori sono espressi in millisecondi. Ad esempio:<ExpiresIn>1000</ExpiresIn> <RefreshTokenExpiresIn>10000</RefreshTokenExpiresIn>
-
Esegui di nuovo il deployment del proxy.
-
Utilizza questa API per aggiornare le proprietà di eliminazione definitiva del token per la tua organizzazione:
POST https://<host-name>/v1/organizations/<org-name>
Payload:
<Organization name="AutomationOrganization"> <Description>Desc</Description> <Properties> <Property name="keymanagement.oauth20.access.token.purge">true</Property> <Property name="keymanagement.oauth20.access.token.purge.after.seconds">120</Property> </Properties> </Organization>
-
Riavvia il processore dei messaggi. Ad esempio:
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
Questa API imposta la proprietà di eliminazione definitiva del token su true per l'organizzazione denominata AutomationOrganization. In questo caso, il token di accesso verrà eliminato definitivamente dal database 120 secondi dopo la scadenza sia del token che del token di aggiornamento.
Comportamento non conforme alle specifiche RFC
Il criterio OAuthV2 restituisce una risposta del token che contiene determinate proprietà non compatibili con RFC. La tabella seguente mostra le proprietà non conformi restituite dal criterio OAuthV2 e le corrispondenti proprietà conformi.
OAuthV2 restituisce: | La proprietà conforme a RFC è: |
---|---|
"token_type":"BearerToken" |
"token_type":"Bearer"
|
"expires_in":"3600" |
"expires_in":3600
Il valore conforme è un numero, non una stringa. |
Inoltre, la risposta di errore per un token di aggiornamento scaduto quando grant_type = refresh_token
è:
{"ErrorCode" : "invalid_request", "Error" :"Refresh Token expired"}
Tuttavia, la risposta conforme a RFC è:
{"error" : "invalid_grant", "error_description" :"refresh token expired"}