Règle GetOAuthV2Info

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

icône de la règle

Objet

Récupère les attributs des jetons d'accès, des jetons d'actualisation, des codes d'autorisation et des attributs de l'application cliente, et renseigne les variables avec les valeurs de ces attributs.

Cette règle est utile lorsque vous devez configurer un comportement conditionnel dynamique en fonction d'une valeur figurant dans un jeton ou un code d'authentification. Chaque fois que des validations de jeton sont effectuées, les variables sont automatiquement renseignées avec les valeurs d'attributs de jeton. Toutefois, dans le cas où la validation des jetons n'a pas eu lieu, vous pouvez utiliser cette fonctionnalité pour renseigner explicitement les variables avec les valeurs d'attribut d'un jeton. Voir également Personnaliser des jetons et des codes d'autorisation.

Le jeton d'accès que vous transmettez à cette règle doit être valide, sinon la règle renverra une erreur invalid_access_token.

Cette règle est une règle extensible et son utilisation peut avoir des conséquences sur le coût ou l'utilisation, en fonction de votre licence Apigee. Pour en savoir plus sur les types de règles et les implications en termes d'utilisation, consultez la section Types de règles.

Exemples

Les exemples suivants utilisent la règle GetOAuthV2 pour récupérer des informations sur différents composants du workflow OAuth2, puis accéder à ces informations dans le code.

Jeton d'accès

Pour obtenir une référence à un jeton d'accès, utilisez l'élément <AccessToken> dans votre règle.

L'exemple suivant s'attend à trouver le jeton d'accès dans un paramètre de requête nommé "access_token" (les détails de la mise en œuvre réelle sont de votre ressort) :

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

À partir du jeton d'accès, la règle recherche le profil du jeton et remplit un ensemble de variables avec les données de profil.

Vous pouvez ensuite accéder aux variables à l'aide de JavaScript ou d'un autre moyen. L'exemple suivant récupère les champs d'application associés au jeton d'accès à l'aide de JavaScript :

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

Notez que vous devez accéder à ces variables dans le code en ajoutant "oauthv2accesstoken". Pour obtenir la liste complète des variables disponibles via le jeton d'accès, consultez la section Variables de jeton d'accès.

Code d’autorisation

Pour obtenir les attributs de code d'autorisation, utilisez l'élément <AuthorizationCode> de votre règle.

L'exemple suivant s'attend à trouver le jeton d'accès dans un paramètre de formulaire nommé "code" (les détails de la mise en œuvre réelle sont de votre ressort) :

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

Selon le code d'authentification, la règle recherche les informations du code et remplit un ensemble de variables avec les données du code d'authentification.

Vous pouvez ensuite accéder aux variables à l'aide de JavaScript ou d'un autre moyen. L'exemple suivant récupère un attribut personnalisé associé au code d'autorisation à l'aide de JavaScript :

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

Notez que pour accéder à ces variables dans le code, vous devez leur ajouter le préfixe "oauthv2authcode". Pour obtenir la liste complète des variables disponibles via le code d'authentification, consultez la section Variables de code d'autorisation.

Jeton d'actualisation

Pour obtenir les attributs de jeton d'actualisation, utilisez l'élément <RefreshToken> de votre règle.

L'exemple suivant s'attend à trouver le jeton d'accès dans un paramètre de requête nommé "refresh_token" (les détails de la mise en œuvre réelle sont de votre ressort) :

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

À partir du jeton d'actualisation, la règle recherche les informations du jeton d'actualisation et remplit un ensemble de variables avec les données du jeton d'actualisation.

Vous pouvez ensuite accéder aux variables à l'aide de JavaScript ou d'un autre moyen. L'exemple suivant récupère un attribut personnalisé associé au jeton d'actualisation à l'aide de JavaScript :

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

Notez que pour accéder aux variables dans le code, vous devez leur ajouter le préfixe "oauthv2refreshtoken". Pour obtenir la liste complète des variables disponibles via le jeton d'actualisation, consultez la section Actualiser les variables de jeton.

Statique

Dans de rares cas, vous devrez peut-être obtenir le profil d'un jeton configuré de manière statique (ce qui n'est pas accessible via une variable). Pour ce faire, indiquez la valeur du jeton d'accès en tant qu'élément.

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

Vous pouvez également effectuer cette opération avec tous les autres types de jetons (ID client, code d'autorisation et jetons d'actualisation).

ID client

Cet exemple montre comment récupérer des informations sur l'application cliente à l'aide de l'ID client. Lors de l'exécution, la règle renseigne un ensemble de variables avec des informations sur le client. Dans ce cas, la règle s'attend à trouver l'ID client dans un paramètre de requête appelé client_id. À l'aide de l'ID client, la règle recherche le profil du client et remplit un ensemble de variables avec les données de profil. Les variables seront précédées du préfixe oauthv2client. 

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

Vous pouvez ensuite accéder aux variables à l'aide de JavaScript ou d'un autre moyen. Par exemple, pour obtenir le nom de l'application de développeur et l'adresse e-mail du développeur associés à l'application cliente à l'aide de JavaScript, procédez comme suit :

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

Documentation de référence des éléments

La documentation de référence des éléments décrit les éléments et les attributs de la règle 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>

Attributs <GetOAuthV2Info>

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

The following table describes attributes that are common to all policy parent elements:

Attribute Description Default Presence
name

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

 N/A Required
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies.

Set to true to have flow execution continue even after a policy fails. See also:

 false Optional
enabled

Set to true to enforce the policy.

Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.

 true Optional
async

This attribute is deprecated.

 false Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>
Default

N/A

If you omit this element, the value of the policy's name attribute is used.
Presence Optional
Type String

Élément <AccessToken>

Récupère le profil pour un jeton d'accès. Vous transmettez une variable contenant une chaîne de jeton d'accès ou une chaîne de jeton littérale (cas rare). Dans cet exemple, le jeton d'accès est extrait d'un paramètre de requête transmis dans une requête. Utilisez l'élément <IgnoreAccessTokenStatus> si vous souhaitez renvoyer des informations pour un jeton révoqué ou expiré.

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

Valeur par défaut :

request.formparam.access_token (élément x-www-form-urlencoded spécifié dans le corps de la requête)

Présence :

Facultatif
Type : Chaîne
Valeurs correctes :

Variable de flux contenant une chaîne de jeton d'accès ou une chaîne littérale.

Élément <AuthorizationCode>

Récupère le profil pour un code d'autorisation. Vous transmettez une variable contenant la chaîne de code d'authentification ou une chaîne de jeton littérale (cas rare). Dans cet exemple, le code d'authentification est extrait d'un paramètre de requête transmis dans une requête. Pour obtenir la liste des variables renseignées par cette opération, consultez la section Variables de flux. 

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

Valeur par défaut :

request.formparam.access_token (élément x-www-form-urlencoded spécifié dans le corps de la requête)

Présence :

Facultatif
Type : Chaîne
Valeurs correctes :

Une variable de flux contenant une chaîne de code d'authentification, ou une chaîne littérale.

Élément <ClientId>

Récupère des informations sur un ID client. Dans cet exemple, l'ID client est extrait d'un paramètre de requête transmis dans une requête. Pour obtenir la liste des variables renseignées par cette opération, consultez la section Variables de flux. 

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

Valeur par défaut :

request.formparam.access_token (élément x-www-form-urlencoded spécifié dans le corps de la requête)

Présence :

Facultatif
Type : Chaîne
Valeurs correctes : Une variable de flux contenant une chaîne de code d'authentification, ou une chaîne littérale.

Élément <IgnoreAccessTokenStatus>

Renvoie les informations du jeton même si celui-ci est expiré ou révoqué. Cet élément ne peut être utilisé qu'avec des jetons d'accès. Les informations sur d'autres entités telles que les jetons d'actualisation et les codes d'autorisation sont renvoyées par défaut, quel que soit leur statut.

<IgnoreAccessTokenStatus>true</IgnoreAccessTokenStatus>

Valeur par défaut :

faux

Présence :

Facultatif
Type : Booléen
Valeurs correctes : True ou False

Élément <RefreshToken>

Récupère le profil pour un jeton d'actualisation Vous transmettez une variable contenant la chaîne de jeton d'actualisation ou une chaîne de jeton littérale (cas rare). Dans cet exemple, le jeton d'actualisation est récupéré à partir d'un paramètre de requête transmis dans une requête. Pour obtenir la liste des variables renseignées par cette opération, consultez la section Variables de flux. 

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

Valeur par défaut :

request.formparam.access_token (élément x-www-form-urlencoded spécifié dans le corps de la requête)

Présence :

Facultatif
Type : Chaîne
Valeurs correctes :

Une variable de flux contenant une chaîne de jeton d'actualisation, ou une chaîne littérale.

Variables de flux

La règle GetOAuthV2Info renseigne ces variables. Elle est généralement utilisée lorsque des données de profil sont nécessaires et qu'une autorisation ou une validation n'a pas encore eu lieu. .

Variables d'ID client

Ces variables sont renseignées lorsque l'élément ClientId est défini :

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}

Variables de jeton d'accès

Ces variables sont renseignées lorsque l'élément AccessToken est défini :

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

Variables de code d'autorisation

Ces variables sont renseignées lorsque l'élément AuthorizationCode est défini :

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}

Variables de jeton d'actualisation

Ces variables sont renseignées lorsque l'élément RefreshToken est défini :

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

Schéma

Chaque type de règle est défini par un schéma XML (.xsd). Pour référence, des schémas de règles sont disponibles sur GitHub.

Informations de référence sur les erreurs

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>

Articles associés