Norme di GetOAuthV2Info

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

La funzionalità del token di accesso JWT è attualmente disponibile per Apigee e per Apigee Hybrid 1.7.0 e versioni successive. Consulta Utilizzare i token OAuth JWT.

Cosa

Recupera gli attributi dei token di accesso, dei token di aggiornamento, dei codici di autorizzazione e degli attributi dell'app client e compila le variabili con i valori di questi attributi.

Questo criterio è utile quando devi configurare un comportamento dinamico e condizionale basato su un valore in un token o in un codice di autorizzazione. Ogni volta che viene eseguita la convalida del token, le variabili vengono completate automaticamente con i valori degli attributi del token. Tuttavia, nei casi in cui la convalida del token non sia avvenuta, puoi utilizzare questa funzionalità per compilare esplicitamente le variabili con i valori degli attributi di un token. Consulta anche Personalizzare token e codici di autorizzazione.

Un token di accesso passato a questo criterio deve essere valido, altrimenti il criterio restituirà un errore invalid_access_token.

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 criteri e sulle implicazioni per l'utilizzo, consulta Tipi di criteri.

NOTA

Il percorso della risorsa utilizzato per chiamare un proxy con questo criterio deve essere incluso nel prodotto utilizzato per generare il token originale. In altre parole, se chiami il proxy con il percorso /tokeninfo, il percorso della risorsa /tokeninfo deve essere incluso nel prodotto utilizzato per generare il token. In caso contrario, verrà visualizzato un errore di tipo InvalidAPICallAsNoApiProductMatchFound.

Per ulteriori informazioni, vedi GetOAuthV2Info non riesce se il token generato utilizzando un prodotto con percorsi di risorse in Community Apigee.

Esempi

I seguenti esempi utilizzano il criterio Get OAuth V2 Info per recuperare informazioni su vari componenti del flusso di lavoro OAuth2 e poi accedere a queste informazioni all'interno del codice.

Token di accesso

Per ottenere un riferimento a un token di accesso, utilizza l'elemento <AccessToken> nel criterio.

L'esempio seguente prevede di trovare il token di accesso in un parametro di query denominato "access_token" (stai a te decidere i dettagli dell'implementazione effettiva):

<GetOAuthV2Info name="MyTokenAttrsPolicy">
  <AccessToken ref="request.queryparam.access_token"></AccessToken>
</GetOAuthV2Info>

Dato il token di accesso, il criterio cerca il profilo del token e compila un set di variabili con i dati del profilo.

A questo punto, puoi accedere alle variabili utilizzando JavaScript o altri mezzi. Nell'esempio che segue recupera gli ambiti associati al token di accesso utilizzando JavaScript:

var scope = context.getVariable('oauthv2accesstoken.MyTokenAttrsPolicy.scope');

Tieni presente che per accedere a queste variabili nel codice, devi anteporre il prefisso "oauthv2accesstoken". Per un elenco completo delle variabili disponibili tramite il token di accesso, vedi Accedi alle variabili token.

Codice di autorizzazione

Per ottenere gli attributi del codice di autorizzazione, utilizza l'elemento <AuthorizationCode> nel criterio.

Nell'esempio seguente si prevede di trovare il token di accesso in un parametro del modulo denominato "code" (i dettagli dell'implementazione effettiva dipendono da te):

<GetOAuthV2Info name="MyAuthCodeAttrsPolicy">
  <AuthorizationCode ref="request.formparam.code"></AuthorizationCode>
</GetOAuthV2Info>

Dato il codice di autenticazione, il criterio cerca le informazioni del codice e compila un insieme di variabili con i dati del codice di autenticazione.

A questo punto, puoi accedere alle variabili utilizzando JavaScript o altri mezzi. Nell'esempio che segue recupera un attributo personalizzato associato al codice di autorizzazione utilizzando JavaScript:

var attr = context.getVariable('oauthv2authcode.MyAuthCodeAttrsPolicy.custom_attribute_name');

Tieni presente che per accedere a queste variabili nel codice, devi anteporre il prefisso "oauthv2authcode". Per un elenco completo delle variabili disponibili tramite il codice di autorizzazione, consulta Variabili del codice di autorizzazione.

Token di aggiornamento

Per ottenere gli attributi dei token di aggiornamento, utilizza l'elemento <RefreshToken> nel criterio.

L'esempio seguente prevede di trovare il token di accesso in un parametro di query denominato "refresh_token" (stai a te decidere i dettagli dell'implementazione effettiva):

<GetOAuthV2Info name="MyRefreshTokenAttrsPolicy">
  <RefreshToken ref="request.queryparam.refresh_token"/>
</GetOAuthV2Info>

Dato il token di aggiornamento, il criterio cerca le informazioni del token di aggiornamento e compila un insieme di variabili con i dati del token di aggiornamento.

Puoi quindi accedere a queste variabili utilizzando JavaScript o un altro metodo. Le seguenti recupera un attributo personalizzato associato al token di aggiornamento utilizzando JavaScript:

var attr = context.getVariable('oauthv2refreshtoken.MyRefreshTokenAttrsPolicy.accesstoken.custom_attribute_name');

Tieni presente che per accedere alle variabili nel codice, devi anteporvi il prefisso "oauthv2refreshtoken". Per un elenco completo delle variabili disponibili tramite il token di aggiornamento, consulta Variabili del token di aggiornamento.

Statica

In alcuni rari casi potrebbe essere necessario ottenere il profilo di un token configurato in modo statico (uno non accessibile tramite una variabile). A tal fine, fornisci il valore del token di accesso come elemento.

<GetOAuthV2Info name="GetTokenAttributes">
  <AccessToken>shTUmeI1geSKin0TODcGLXBNe9vp</AccessToken>
</GetOAuthV2Info>

Puoi farlo anche con tutti gli altri tipi di token (ID client, codice di autorizzazione e token di aggiornamento).

ID client

Questo esempio mostra come recuperare informazioni sull'app client utilizzando l'ID client. Al momento dell'esecuzione, il criterio compila un insieme di variabili con le informazioni del cliente. In questo in questo caso, il criterio prevede di trovare l'ID client in un parametro di ricerca chiamato client_id. Dato l'ID client, il criterio cerca quello del cliente profilo e compila un insieme di variabili con i dati del profilo. Le variabili saranno con prefisso oauthv2client.

<GetOAuthV2Info name="GetClientAttributes">
  <ClientId ref="request.queryparam.client_id"></ClientId>
</GetOAuthV2Info>

A questo punto, puoi accedere alle variabili utilizzando JavaScript o altri mezzi. Ad esempio, per ottenere il nome e l'indirizzo email dello sviluppatore associati all'app client utilizzando JavaScript:

context.getVariable("oauthv2client.GetClientAttributes.developer.email");
context.getVariable("oauthv2client.GetClientAttributes.developer.app.name");

---

Riferimento elemento

Il riferimento all'elemento descrive gli elementi e gli attributi del criterio GetOAuthV2Info.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="GetOAuthV2Info-1"
    <DisplayName>Get OAuth v2.0 Info 1</DisplayName>
    <AccessToken ref="variable"></AccessToken>
    <AuthorizationCode ref="variable"></AuthorizationCode>
    <ClientId ref="variable"></ClientId>
    <RefreshToken ref="variable"></RefreshToken>
</GetOAuthV2Info>

<GetOAuthV2Info> attributi

<GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="Get-OAuth-v20-Info-1">

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

Attributo	Descrizione	Predefinito	Presenza
name	Il nome interno del criterio. Il valore dell'attributo name può Deve contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri. Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.	N/D	Obbligatorio
continueOnError	Imposta il valore su false per restituire un errore quando un criterio non funziona. Si tratta di un comportamento previsto comportamento per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche: Le regole di errore vengono attivate SOLO in uno stato di errore (informazioni su continueOnError) Gestione degli errori all'interno del flusso corrente	falso	Facoltativo
enabled	Imposta su true per applicare il criterio. Imposta false per disattivare il criterio. Il criterio non verrà applicata anche se rimane collegata a un flusso.	true	Facoltativo
async	Questo attributo è stato ritirato.	falso	Ritirato

&lt;DisplayName&gt; elemento

Da utilizzare in aggiunta all'attributo name per etichettare il criterio in editor proxy della UI di gestione con un nome diverso e in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>

Predefinito	N/D Se ometti questo elemento, il valore dell'attributo name del criterio è in uso.
Presenza	Facoltativo
Tipo	Stringa

&lt;AccessToken&gt; elemento

Recupera il profilo per un token di accesso. Passi in una variabile che contiene una stringa del token di accesso o una stringa di token letterale (caso raro). In questo esempio, il token di accesso recuperate da un parametro di query passato in una richiesta. Utilizza <IgnoraAccessTokenStatus> se vuoi restituire informazioni per un token revocato o scaduto.

<AccessToken ref="request.queryparam.access_token"></AccessToken>

Valore predefinito:	request.formparam.access_token (un valore x-www-form-urlencoded specificato nel corpo della richiesta)
Presenza:	Facoltativo
Tipo:	Stringa
Valori validi:	Una variabile di flusso contenente una stringa di token di accesso o una stringa letterale.

&lt;AuthorizationCode&gt; elemento

Recupera il profilo per un codice di autorizzazione. Devi passare una variabile contenente la stringa del codice di autorizzazione o una stringa di token letterale (caso raro). In questo esempio, il codice di autorizzazione è recuperate da un parametro di query passato in una richiesta. Per un elenco delle variabili completate da questa operazione, consulta "Variabili di flusso".

<AuthorizationCode ref="request.queryparam.authorization_code"></AuthorizationCode>

Predefinita:	request.formparam.access_token (un valore x-www-form-urlencoded specificato nel corpo della richiesta)
Presenza:	Facoltativo
Tipo:	Stringa
Valori validi:	Una variabile di flusso contenente una stringa di codice di autorizzazione o una stringa letterale.

&lt;ClientId&gt; elemento

Recupera le informazioni relative a un ID client. In questo esempio, l'ID client viene recuperato da un parametro di query passato in una richiesta. Per un elenco di variabili compilate da questa operazione, consulta "Variabili di flusso".

<ClientId ref="request.queryparam.client_id"></ClientId>

Valore predefinito:	request.formparam.access_token (un valore x-www-form-urlencoded specificato nel corpo della richiesta)
Presenza:	Facoltativo
Tipo:	Stringa
Valori validi:	Una variabile di flusso contenente una stringa di codice di autorizzazione o una stringa letterale.

&lt;IgnoreAccessTokenStatus&gt; elemento

Restituisce le informazioni del token anche se il token è scaduto o revocato. Questo elemento può mostrare solo da usare con i token di accesso. Informazioni per altre entità, come i token di aggiornamento e l'autorizzazione vengono restituiti per impostazione predefinita a prescindere dal loro stato.

<IgnoreAccessTokenStatus>true</IgnoreAccessTokenStatus>

Predefinita:	falso
Presenza:	Facoltativo
Tipo:	Valore booleano
Valori validi:	true o false

&lt;RefreshToken&gt; elemento

Recupera il profilo per un token di aggiornamento. Passi in una variabile che contiene aggiorna la stringa del token o una stringa del token letterale (caso raro). In questo esempio, il token di aggiornamento recuperate da un parametro di query passato in una richiesta. Per un elenco delle variabili completate da questa operazione, consulta "Variabili di flusso".

Nota: questo elemento funziona nello stesso modo sia che utilizzi un token di aggiornamento emessi con un token di accesso JWT o con un token di accesso tradizionale opaco.

<RefreshToken ref="request.queryparam.refresh_token"></RefreshToken>

Predefinita:	request.formparam.access_token (un valore x-www-form-urlencoded specificato nel corpo della richiesta)
Presenza:	Facoltativo
Tipo:	Stringa
Valori validi:	Una variabile di flusso contenente una stringa del token di aggiornamento o una stringa letterale.

Variabili di flusso

Il criterio GetOAuthV2Info compila queste variabili e viene in genere utilizzato nei casi in cui hai bisogno dei dati del profilo, ma non è ancora avvenuta una concessione o una convalida. .

Variabili ID client

Queste variabili vengono compilate quando viene impostato l'elemento ClientId:

oauthv2client.{policy_name}.client_id
oauthv2client.{policy_name}.client_secret
oauthv2client.{policy_name}.redirection_uris // Note the spelling -- 'redirection_uris'
oauthv2client.{policy_name}.developer.email
oauthv2client.{policy_name}.developer.app.name
oauthv2client.{policy_name}.developer.id
oauthv2client.{policy_name}.{developer_app_custom_attribute_name}

Accedi alle variabili token

Queste variabili vengono compilate quando l'elemento AccessToken è impostato:

oauthv2accesstoken.{policy_name}.developer.id
oauthv2accesstoken.{policy_name}.developer.app.name
oauthv2accesstoken.{policy_name}.developer.app.id
oauthv2accesstoken.{policy_name}.developer.email

oauthv2accesstoken.{policy_name}.organization_name
oauthv2accesstoken.{policy_name}.api_product_list

oauthv2accesstoken.{policy_name}.access_token
oauthv2accesstoken.{policy_name}.scope
oauthv2accesstoken.{policy_name}.expires_in //in seconds
oauthv2accesstoken.{policy_name}.status
oauthv2accesstoken.{policy_name}.client_id
oauthv2accesstoken.{policy_name}.accesstoken.{custom_attribute_name}

oauthv2accesstoken.{policy_name}.refresh_token
oauthv2accesstoken.{policy_name}.refresh_token_status
oauthv2accesstoken.{policy_name}.refresh_token_expires_in //in seconds

oauthv2accesstoken.{policy_name}.refresh_count
oauthv2accesstoken.{policy_name}.refresh_token_issued_at
oauthv2accesstoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED

Variabili del codice di autorizzazione

Queste variabili vengono compilate quando viene impostato l'elemento AuthorizationCode:

oauthv2authcode.{policy_name}.code
oauthv2authcode.{policy_name}.scope       
oauthv2authcode.{policy_name}.redirect_uri 
oauthv2authcode.{policy_name}.client_id
oauthv2authcode.{policy_name}.{auth_code_custom_attribute_name}

Variabili token di aggiornamento

Queste variabili vengono completate quando viene impostato l'elemento RefreshToken:

oauthv2refreshtoken.{policy_name}.developer.id
oauthv2refreshtoken.{policy_name}.developer.app.name
oauthv2refreshtoken.{policy_name}.developer.app.id
oauthv2refreshtoken.{policy_name}.developer.email
oauthv2refreshtoken.{policy_name}.organization_name
oauthv2refreshtoken.{policy_name}.api_product_list

oauthv2refreshtoken.{policy_name}.access_token
oauthv2refreshtoken.{policy_name}.scope
oauthv2refreshtoken.{policy_name}.expires_in //in seconds

oauthv2refreshtoken.{policy_name}.status
oauthv2refreshtoken.{policy_name}.client_id
oauthv2refreshtoken.{policy_name}.accesstoken.{custom_attribute_name}

oauthv2refreshtoken.{policy_name}.refresh_token
oauthv2refreshtoken.{policy_name}.refresh_token_status
oauthv2refreshtoken.{policy_name}.refresh_token_expires_in //in seconds

oauthv2refreshtoken.{policy_name}.refresh_count
oauthv2refreshtoken.{policy_name}.refresh_token_issued_at
oauthv2refreshtoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED

Schema

Ogni tipo di criterio è definito da uno schema XML (.xsd). Come riferimento, consulta gli schemi dei criteri sono disponibili su GitHub.

Messaggi di errore

Questa sezione descrive i codici di errore e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. È 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 durante l'esecuzione del criterio. I nomi degli errori mostrati di seguito sono le stringhe assegnate alla variabile fault.name quando si verifica un errore. Per ulteriori dettagli, consulta la sezione sulle variabili di errore di seguito.

Codice guasto	Stato HTTP	Causa
steps.oauth.v2.access_token_expired	500	Il token di accesso inviato al criterio è scaduto.
steps.oauth.v2.authorization_code_expired	500	Il codice di autorizzazione inviato al criterio è scaduto.
steps.oauth.v2.invalid_access_token	500	Il token di accesso inviato al criterio non è valido.
steps.oauth.v2.invalid_client-invalid_client_id	500	L'ID client inviato al criterio non è valido.
steps.oauth.v2.invalid_refresh_token	500	Il token di aggiornamento inviato al criterio non è valido.
steps.oauth.v2.invalid_request-authorization_code_invalid	500	Il codice di autorizzazione inviato al criterio non è valido.
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound	401	Per informazioni sulla risoluzione di questo errore, consulta La verifica del token di accesso OAuth 2.0 genera l'errore "Chiamata API non valida perché non è stata trovata alcuna corrispondenza per apiproduct".
steps.oauth.v2.refresh_token_expired	500	Il token di aggiornamento inviato al criterio è scaduto.

Errori di deployment

Per informazioni sugli errori di deployment, fai riferimento al messaggio riportato nell'interfaccia utente.

Variabili di errore

Queste variabili vengono impostate quando questo criterio attiva un errore in fase di runtime.

Nota: puoi utilizzare queste variabili per creare condizioni delle regole di errore. Per maggiori informazioni, consulta Informazioni importanti sugli errori relativi alle norme.

Variabili	Dove	Esempio
fault.name="fault_name"	fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime sopra. Il nome dell'errore è l'ultima parte del codice dell'errore.	fault.name Matches "IPDeniedAccess"
oauthV2.policy_name.failed	policy_name è il nome specificato dall'utente del criterio che ha generato l'errore.	oauthV2.GetTokenInfo.failed = true
oauthV2.policy_name.fault.name	policy_name è il nome specificato dall'utente del criterio che ha generato l'errore.	oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id
oauthV2.policy_name.fault.cause	policy_name è il nome specificato dall'utente del criterio che ha generato l'errore.	oauthV2.GetTokenInfo.cause = ClientID is Invalid

Esempio di risposta di errore

{  
   "fault":{  
      "faultstring":"ClientId is Invalid",
      "detail":{  
         "errorcode":"keymanagement.service.invalid_client-invalid_client_id"
      }
   }
}

Esempio di regola di errore

<FaultRule name="OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientIdResponse</Name>
    </Step>
    <Condition>(fault.name = "invalid_client-invalid_client_id")</Condition>
</FaultRule>

Argomenti correlati

• Criterio OAuthV2
• Home page OAuth
• Personalizzazione dei token e codici di autorizzazione