Questa pagina è stata tradotta dall'API Cloud Translation.

Criterio GetOAuthV2Info

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

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 in base a un valore in un token o in un codice di autorizzazione. Ogni volta che si verifica la convalida del token, le variabili vengono compilate automaticamente con i valori degli attributi dei token. Tuttavia, nei casi in cui la convalida del token non si sia verificata, puoi utilizzare questa funzionalità per completare in modo esplicito le variabili con i valori degli attributi di un token. Vedi anche Personalizzazione di token e codici di autorizzazione.

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

Questo criterio è un criterio estendibile e il suo utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni di utilizzo, consulta Tipi di criteri.

Esempi

Gli esempi riportati di seguito utilizzano il criterio Ottieni informazioni OAuth V2 per recuperare informazioni sui vari componenti del flusso di lavoro OAuth2 e quindi 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" (i dettagli effettivi dell'implementazione dipendono da te):

<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 insieme di variabili con i dati del profilo.

Potrai quindi accedere alle variabili utilizzando JavaScript o un altro mezzo. L'esempio seguente 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 farle precedere da "oauthv2accesstoken". Per un elenco completo delle variabili disponibili tramite il token di accesso, consulta Variabili dei token di accesso.

Codice di autorizzazione

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

L'esempio seguente prevede di trovare il token di accesso in un parametro del modulo denominato "code" (i dettagli effettivi dell'implementazione spetta a te):

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

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

Potrai quindi accedere alle variabili utilizzando JavaScript o un altro mezzo. L'esempio seguente 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 farle precedere da "oauthv2authcode". Per un elenco completo delle variabili disponibili tramite il codice di autorizzazione, consulta Variabili del codice di autorizzazione.

Token di aggiornamento

Per ricevere 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" (i dettagli effettivi dell'implementazione dipendono da te):

<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.

Potrai quindi accedere a queste variabili utilizzando JavaScript o un altro mezzo. L'esempio seguente 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 farle precedere da "oauthv2refreshtoken". Per un elenco completo delle variabili disponibili tramite il token di aggiornamento, consulta Aggiornare le variabili del token.

Statiche

In alcuni rari casi, potrebbe essere necessario ottenere il profilo di un token configurato in modo statico (uno che non è accessibile tramite una variabile). Puoi farlo fornendo 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 completa un insieme di variabili con le informazioni sul client. In questo caso, il criterio prevede di trovare l'ID client in un parametro di query denominato client_id. Dato l'ID client, il criterio cerca il profilo del client e compila un insieme di variabili con i dati del profilo. Le variabili avranno come prefisso oauthv2client.

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

Potrai quindi accedere alle variabili utilizzando JavaScript o un altro mezzo. Ad esempio, per recuperare il nome dell'app dello sviluppatore 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 agli elementi 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>

Attributi <GetOAuthV2Info>

<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 della norma. Il valore dell'attributo `name` può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri. Facoltativamente, utilizza l'elemento `<DisplayName>` per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.	N/A	Obbligatorio
`continueOnError`	Impostalo su `false` per restituire un errore in caso di errore di un criterio. Questo è il comportamento previsto per la maggior parte dei criteri. Imposta su `true` per fare in modo che l'esecuzione del flusso continui anche in caso di errore di un criterio. Vedi anche: Le regole di errore vengono attivate SOLO in stato di errore (informazioni su continueOnError) Gestione dei guasti all'interno del flusso di corrente	false	Facoltativo
`enabled`	Imposta il criterio su `true` per applicare il criterio. Impostala su `false` per disattivare il criterio. Il criterio non verrà applicato anche se rimane associato a un flusso.	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

Predefinito	N/A Se ometti questo elemento, viene utilizzato il valore dell'attributo `name` del criterio.
Presenza	Facoltativo
Tipo	Stringa

N/A

Se ometti questo elemento, viene utilizzato il valore dell'attributo name del criterio.

Presenza Facoltativo

Tipo Stringa

Elemento <AccessToken>

Recupera il profilo per un token di accesso. Puoi passare una variabile contenente la stringa del token di accesso o una stringa token letterale (caso raro). In questo esempio, il token di accesso viene recuperato da un parametro di query passato in una richiesta. Utilizza l'elemento <<UnknownAccessTokenStatus>> se vuoi restituire informazioni per un token revocato o scaduto.

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

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

Elemento <AuthorizationCode>

Recupera il profilo per un codice di autorizzazione. Passi in una variabile contenente la stringa del codice di autorizzazione o in una stringa token letterale (caso raro). In questo esempio, il codice di autorizzazione viene recuperato da un parametro di query trasmesso in una richiesta. Per un elenco delle variabili compilate da questa operazione, consulta "Variabili di flusso".

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

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

Elemento <ClientId>

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

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

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

Elemento <ignoreAccessTokenStatus>

Restituisce le informazioni sul token anche se è scaduto o revocato. Questo elemento può essere utilizzato solo con i token di accesso. Per impostazione predefinita, le informazioni relative ad altre entità come token di aggiornamento e codici di autorizzazione vengono restituite indipendentemente dal loro stato.

<IgnoreAccessTokenStatus>true</IgnoreAccessTokenStatus>

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

Elemento <refreshToken>

Recupera il profilo per un token di aggiornamento. Passi all'interno di una variabile contenente la stringa del token di aggiornamento o di una stringa token letterale (casi rari). In questo esempio, il token di aggiornamento viene recuperato da un parametro di query passato in una richiesta. Per un elenco delle variabili compilate da questa operazione, consulta "Variabili di flusso".

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

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

Variabili di flusso

Il criterio GetOAuthV2Info compila queste variabili ed è generalmente utilizzato nei casi in cui hai bisogno dei dati del profilo, ma in cui non si è ancora verificata una concessione o una convalida. .

Variabili ID client

Queste variabili vengono compilate quando è 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 viene impostato l'elemento AccessToken:

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 è 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}

Aggiorna variabili token

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

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). Per riferimento, gli schemi dei criteri sono disponibili su GitHub.

Messaggi di errore

Questa sezione descrive i codici e i messaggi di errore che vengono restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta gli articoli Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi quando il criterio viene eseguito. I nomi di errore mostrati di seguito sono le stringhe assegnate alla variabile fault.name quando si verifica un errore. Consulta la sezione Variabili di errore riportata di seguito per ulteriori dettagli.

Codice di errore	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 alle norme è 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 alle norme 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 Oauth2.0 genera l'errore "Chiamata API non valida perché non è stata trovata alcuna corrispondenza 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, consulta il messaggio riportato nell'interfaccia utente.

Variabili di errore

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

Variabili	Dove	Esempio
`fault.name="fault_name"`	`fault_name` è il nome dell'errore, come indicato nella tabella Errori di runtime riportata sopra. Il nome del guasto è l'ultima parte del codice di errore.	`fault.name 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>