Norme di GetOAuthV2Info

Policy estensibile

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Il criterio GetOAuthV2Info 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.

Questa norma è 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 viene eseguita la convalida del token, le variabili vengono compilate automaticamente con i valori degli attributi del token. Tuttavia, nei casi in cui la convalida del token non è avvenuta, puoi utilizzare questa funzionalità per compilare esplicitamente le variabili con i valori degli attributi di un token. Vedi anche Personalizzazione di token e codici di autorizzazione.

Un token di accesso che trasmetti a questa policy deve essere valido, altrimenti la policy genererà un errore invalid_access_token.

Queste norme sono estendibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di policy e sulle implicazioni di utilizzo, consulta Tipi di policy.

Esempi

I seguenti esempi utilizzano il criterio Get OAuth V2 Info per recuperare informazioni su 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> nella tua policy.

Il seguente esempio prevede di trovare il token di accesso in un parametro di ricerca denominato "access_token" (i dettagli di implementazione effettivi 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.

Puoi quindi accedere alle variabili utilizzando JavaScript o un altro metodo. Il seguente esempio 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, consulta Variabili del token di accesso.

Codice di autorizzazione

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

Il seguente esempio prevede di trovare il token di accesso in un parametro del modulo denominato "code" (i dettagli di implementazione effettivi dipendono da te):

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

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

Puoi quindi accedere alle variabili utilizzando JavaScript o un altro metodo. 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 aggiungere 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 del token di aggiornamento, utilizza l'elemento <RefreshToken> nel tuo criterio.

Il seguente esempio prevede di trovare il token di accesso in un parametro di ricerca denominato "refresh_token" (i dettagli di implementazione effettivi 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.

Puoi quindi accedere a queste variabili utilizzando JavaScript o un altro mezzo. Il seguente esempio 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 anteporre "oauthv2refreshtoken". Per un elenco completo delle variabili disponibili tramite il token di aggiornamento, consulta Variabili del token di aggiornamento.

Statico

In alcuni rari casi, potrebbe essere necessario ottenere il profilo di un token configurato staticamente (uno 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 compila un insieme di variabili con le informazioni del client. In questo caso, la policy 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 il prefisso oauthv2client. 

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

Puoi quindi accedere alle variabili utilizzando JavaScript o un altro metodo. Ad esempio, per ottenere il nome dell'app sviluppatore e l'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>

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 Presence
name

Il nome interno del criterio. Il valore dell'attributo name può 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 su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri.

Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche:

 falso Facoltativo
enabled

Imposta su true per applicare il criterio.

Imposta su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso.

 true Facoltativo
async

Questo attributo è stato ritirato.

 falso Deprecato

Elemento <DisplayName>

Da utilizzare insieme 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/D

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

Elemento <AccessToken>

Recupera il profilo per un token di accesso. Passi una variabile che contiene la stringa del token di accesso o una stringa del 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 <IgnoreAccessTokenStatus> se vuoi restituire informazioni per un token revocato o scaduto.

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

Predefinito:

request.formparam.access_token (un parametro 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.

Elemento <AuthorizationCode>

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

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

Predefinito:

request.formparam.access_token (un parametro 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.

Elemento <ClientId>

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 delle variabili compilate da questa operazione, vedi "Variabili di flusso". 

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

Predefinito:

request.formparam.access_token (un parametro 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.

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 per altre entità, come i token di aggiornamento e i codici di autorizzazione, vengono restituite indipendentemente dal loro stato.

<IgnoreAccessTokenStatus>true</IgnoreAccessTokenStatus>

Predefinito:

false

Presenza:

Facoltativo
Tipo: Booleano
Valori validi: vero o falso

Elemento <RefreshToken>

Recupera il profilo per un token di aggiornamento. Passi una variabile che contiene la stringa del token di aggiornamento o una stringa del token letterale (caso raro). 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, vedi "Variabili di flusso". 

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

Predefinito:

request.formparam.access_token (un parametro 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 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 stata eseguita 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}

Variabili del token di accesso

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

Aggiorna le variabili token di aggiornamento

Queste variabili vengono compilate 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 policy è definito da uno schema XML (.xsd). Per riferimento, gli schemi delle policy sono disponibili su GitHub.

Messaggi di errore

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes. The error names shown below are the strings that are assigned to the fault.name variable when an error occurs. See the Fault variables section below for more details.

Fault code HTTP status Cause
steps.oauth.v2.access_token_expired 500 The access token sent to the policy is expired.
steps.oauth.v2.authorization_code_expired 500 The authorization code sent to the policy is expired.
steps.oauth.v2.invalid_access_token 500 The access token sent to the policy is invalid.
steps.oauth.v2.invalid_client-invalid_client_id 500 The client ID sent to the policy is invalid.
steps.oauth.v2.invalid_refresh_token 500 The refresh token sent to the policy is invalid.
steps.oauth.v2.invalid_request-authorization_code_invalid 500 The authorization code sent to the policy is invalid.
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound 401 Please see Oauth2.0 Access Token Verification throws "Invalid API call as no apiproduct match found" error for information about troubleshooting this error.
steps.oauth.v2.refresh_token_expired 500 The refresh token sent to the policy is expired.

Deployment errors

Refer to the message reported in the UI for information about deployment errors.

Fault variables

These variables are set when this policy triggers an error at runtime.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "IPDeniedAccess"
oauthV2.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. oauthV2.GetTokenInfo.failed = true
oauthV2.policy_name.fault.name policy_name is the user-specified name of the policy that threw the fault. oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id
oauthV2.policy_name.fault.cause policy_name is the user-specified name of the policy that threw the fault. oauthV2.GetTokenInfo.cause = ClientID is Invalid

Example error response

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

Example fault rule

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

Argomenti correlati