Règle OAuthV2

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X.
en savoir plus

Quoi

OAuthV2 est une règle à plusieurs attributs permettant d'effectuer des opérations de type d'octroi OAuth 2.0. Il s'agit de la règle principale utilisée pour configurer les points de terminaison OAuth 2.0 sur Apigee Edge.

Conseil:Si vous souhaitez en savoir plus sur OAuth sur Apigee Edge, consultez la page d'accueil OAuth. Elle fournit des liens vers des ressources, des exemples, des vidéos, etc. Consultez l'exemple OAuth avancé sur GitHub pour découvrir une bonne démonstration de l'utilisation de cette stratégie dans une application fonctionnelle.

Exemples

VerifyAccessToken

VerifyAccessToken

Cette configuration de stratégie OAuthV2 (avec l'opération VerifyAccessToken) vérifie qu'un jeton d'accès envoyé à Apigee Edge est valide. Lorsque cette opération de stratégie est déclenchée, Edge recherche un jeton d'accès valide dans la requête. Si le jeton d'accès est valide, la requête est autorisée à poursuivre. S'il n'est pas valide, l'ensemble du traitement s'arrête et une erreur est renvoyée dans la réponse.

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

Remarque: Seuls les jetons de support OAuth 2.0 sont acceptés. Les jetons de code d'authentification de message (MAC, Message Authentication Code) ne sont pas acceptés.

Exemple :

$ curl -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

Par défaut, Edge accepte les jetons d'accès dans l'en-tête Authorization avec le préfixe Bearer. Vous pouvez modifier cette valeur par défaut avec l'élément <AccessToken>.

GenerateAccessToken

Générer les jetons d'accès

Pour obtenir des exemples montrant comment demander des jetons d'accès pour chacun des types d'autorisations compatibles, consultez la section Demander des jetons d'accès et des codes d'autorisation. Cet article inclut des exemples de ces opérations :

GenerateAuthorizationCode

Générer un code d'autorisation

Pour obtenir des exemples montrant comment demander des codes d'autorisation, consultez la section Demander un code d'autorisation.

RefreshAccessToken

Actualiser un jeton d'accès

Pour obtenir des exemples montrant comment demander des jetons d'accès à l'aide d'un jeton d'actualisation, consultez la section Actualiser un jeton d'accès.

Jeton de flux de réponse

Générer un jeton d'accès sur le flux de réponse

Il se peut que vous deviez parfois générer un jeton d'accès dans le flux de réponse. Par exemple, vous pouvez le faire en réponse à une validation personnalisée effectuée dans un service de backend. Dans cet exemple, le cas d'utilisation nécessite à la fois un jeton d'accès et un jeton d'actualisation, qui déterminent le type d'attribution implicite. Dans ce cas, nous utilisons le type d'attribution du mot de passe pour générer le jeton. Comme vous le verrez, la solution consiste à transmettre un en-tête de requête d'autorisation avec une règle JavaScript.

Examinons tout d'abord l'exemple de règle suivant :

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

Si vous appliquez cette règle au flux de réponse, elle échouera avec une erreur 401 "Unauthorized", même si les paramètres de connexion corrects sont spécifiés dans la règle. Pour résoudre ce problème, vous devez définir un en-tête de demande d'autorisation.

L'en-tête "Authorization" doit contenir un schéma d'accès de base avec "client_id:client_secret" encodé en base64.

Vous pouvez ajouter cet en-tête avec une règle JavaScript placée juste avant la règle OAuthV2, comme ceci. Les variables "local_clientid" et "local_secret" doivent être définies au préalable et disponibles dans le flux :

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)));

Consultez également la section Encoder les identifiants d'authentification de base.

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

La référence de la règle décrit les éléments et les attributs de la règle OAuthV2.

L'exemple de règle présenté ci-dessous est l'une des nombreuses configurations possibles. Cet exemple montre une règle OAuthV2 configurée pour l'opération GenerateAccessToken. Il comprend les éléments obligatoires et facultatifs. Reportez-vous aux descriptions des éléments de cette section pour plus de détails.

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

Attributs <OAuthV2>

<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">

Le tableau suivant décrit les attributs communs à tous les éléments parents des règles :

Attribut Description Par défaut Présence
name

Nom interne de la règle. La valeur de l'attribut name peut contenir des lettres, des chiffres, des espaces, des tirets, des traits de soulignement et des points. Cette valeur ne peut pas dépasser 255 caractères.

Vous pouvez également utiliser l'élément <DisplayName> pour ajouter un libellé à la règle dans l'éditeur de proxy de l'interface utilisateur de gestion, en utilisant un nom différent, en langage naturel.

N/A Obligatoire
continueOnError

Définissez sur false pour afficher une erreur en cas d'échec d'une règle. Il s'agit du comportement attendu pour la plupart des règles.

Définissez sur true pour que l'exécution du flux se poursuive même après l'échec d'une règle.

false Facultatif
enabled

Définissez sur true pour appliquer la règle.

Définissez sur false pour désactiver la règle. La stratégie ne sera pas appliquée, même si elle reste associée à un flux.

true Facultatif
async

Cet attribut est obsolète.

false Obsolète

Élément <DisplayName>

Utilisez-le, en plus de l'attribut name, pour appliquer un libellé à la règle dans l'éditeur de proxys de l'interface de gestion en utilisant un nom différent, en langage naturel.

<DisplayName>Policy Display Name</DisplayName>
Par défaut

N/A

Si vous omettez cet élément, la valeur de l'attribut name de la règle est utilisée.

Présence Facultatif
Type Chaîne

Élément <AccessToken>

<AccessToken>request.header.access_token</AccessToken>

Par défaut, "VerifyAccessToken" attend que le jeton d'accès soit envoyé dans l'en-tête Authorization. Vous pouvez modifier cette valeur par défaut à l'aide de cet élément. Par exemple, request.queryparam.access_token indique que le jeton d'accès doit être présent en tant que paramètre de requête nommé access_token.

Exemple où <AccessToken>request.header.access_token</AccessToken> est spécifié :

curl https://myorg-myenv.apigee.net/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"
Exemple où <AccessToken>request.queryparam.access_token</AccessToken> est spécifié:

curl "https://myorg-myenv.apigee.net/oauth2/validate?access_token:Rft3dqrs56Blirls56a"

Valeur par défaut :

N/A

Présence :

Facultatif

Type : Chaîne
Utilisé avec des opérations :
  • VerifyAccessToken

Élément <AccessTokenPrefix>

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

Par défaut, "CheckAccessToken" attend que le jeton d'accès soit envoyé dans un en-tête "Authorization" en tant que jeton de support. Exemple :

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

Actuellement, le Bearer est le seul préfixe accepté.

Valeur par défaut :

Support

Présence :

Facultatif

Type : Chaîne
Valeurs correctes :

Support

Utilisé avec des opérations :
  • VerifyAccessToken

Élément <AppEndUser>

<AppEndUser>request.queryparam.app_enduser</AppEndUser>

Dans les cas où l'ID de l'utilisateur final de l'application doit être envoyé au serveur d'autorisation, cet élément vous permet de spécifier l'emplacement où Edge doit rechercher cet ID. Par exemple, vous pouvez l'envoyer en tant que paramètre de requête ou dans un en-tête HTTP.

Par exemple, request.queryparam.app_enduser indique que l'utilisateur AppEndUser doit être présent en tant que paramètre de requête, comme par exemple ?app_enduser=ntesla@theramin.com. Pour exiger AppEndUser dans un en-tête HTTP, par exemple, définissez cette valeur sur request.header.app_enduser.

Fournir ce paramètre vous permet d'inclure un ID d'utilisateur final de l'application dans le jeton d'accès. Cette fonctionnalité est utile si vous souhaitez récupérer ou révoquer les jetons d'accès OAuth 2.0 par ID d'utilisateur final. Pour plus d'informations, consultez la section Activer la récupération et la révocation des jetons d'accès OAuth 2.0 par ID d'utilisateur final, ID d'application ou les deux.

Valeur par défaut :

N/A

Présence :

Facultatif

Type : Chaîne
Valeurs correctes :

Toute variable de flux accessible à la règle au moment de l'exécution.

Utilisé avec des types d'attribution :
  • authorization_code
  • implicite
  • mot de passe
  • client_credentials

<Attributes/Attribute>

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

Utilisez cet élément pour ajouter des attributs personnalisés à un jeton d'accès ou à un code d'autorisation. Par exemple, vous souhaitez peut-être intégrer un ID utilisateur ou un identifiant de session dans un jeton d'accès qui peut être extrait et vérifié au moment de l'exécution.

Cet élément vous permet de spécifier une valeur dans une variable de flux ou à partir d'une chaîne littérale. Si vous spécifiez à la fois une variable et une chaîne, la valeur spécifiée dans la variable de flux est utilisée. Si la variable ne peut pas être résolue, la chaîne est la valeur par défaut.

Pour en savoir plus sur l'utilisation de cet élément, consultez la section Personnaliser les jetons et les codes d'autorisation.

Afficher ou masquer des attributs personnalisés dans la réponse

N'oubliez pas que si vous définissez l'élément GenerateResponse de cette règle sur true, la représentation JSON complète du jeton est renvoyée dans la réponse, y compris les attributs personnalisés que vous définissez. Dans certains cas, vous pouvez vouloir masquer l'intégralité ou une partie de vos attributs personnalisés dans la réponse afin qu'ils ne soient pas visibles par les applications clientes.

Par défaut, les attributs personnalisés apparaissent dans la réponse. Si vous souhaitez les masquer, vous pouvez définir le paramètre display sur false. Exemple :

<Attributes>
    <Attribute name="employee_id" ref="employee.id" display="false"/>
    <Attribute name="employee_name" ref="employee.name" display="false"/>
</Attributes>

La valeur de l'attribut display n'est pas conservée. Supposons que vous générez un jeton d'accès avec des attributs personnalisés que vous souhaitez masquer dans la réponse générée. Le paramètre display=false permet de réaliser cet objectif. Toutefois, si un nouveau jeton d'accès est généré ultérieurement à l'aide d'un jeton d'actualisation, les attributs personnalisés d'origine du jeton d'accès apparaîtront dans la réponse du jeton d'actualisation. En effet, Edge ne se souvient pas que l'attribut display a été initialement défini sur false dans la stratégie de génération de jetons d'accès. L'attribut personnalisé fait simplement partie des métadonnées du jeton d'accès.

Vous obtiendrez le même comportement si vous ajoutez des attributs personnalisés à un code d'autorisation. Lorsqu'un jeton d'accès est généré à l'aide de ce code, ces attributs personnalisés apparaissent dans la réponse du jeton d'accès. Encore une fois, ce comportement peut être contraire à vos attentes.

Pour masquer les attributs personnalisés dans ce type de cas, vous disposez des options suivantes :

  • Réinitialisez explicitement les attributs personnalisés de la règle de jeton d'actualisation et définissez leur affichage sur "false". Dans ce cas, vous devrez peut-être récupérer les valeurs personnalisées d'origine du jeton d'accès d'origine à l'aide de la règle GetOAuthV2Info.
  • Utilisez une règle JavaScript de post-traitement pour extraire manuellement les attributs personnalisés que vous ne souhaitez pas voir dans la réponse.

Consultez également la section Personnaliser les jetons et les codes d'autorisation.

Valeur par défaut :

N/A

Présence :

Facultatif

Valeurs correctes :
  • name - Nom de l'attribut
  • ref - Valeur de l'attribut. Peut provenir d'une variable de flux.
  • display - (facultatif) : permet de spécifier si les attributs personnalisés apparaissent ou non dans la réponse. Si la valeur est true, les attributs personnalisés apparaissent dans la réponse (si GenerateResponse est également activé). Si la valeur est false, les attributs personnalisés ne sont pas inclus dans la réponse. La valeur par défaut est true. Consultez la section Afficher ou masquer des attributs personnalisés dans la réponse.
Utilisé avec des types d'attribution :
  • authorization_code
  • implicite
  • mot de passe
  • client_credentials
  • refresh_token
  • Peut également être utilisé avec l'opération GenerateAuthorizationCode.

Élément <ClientId>

<ClientId>request.formparam.client_id</ClientId>

Dans certains cas, l'application cliente doit envoyer l'ID client au serveur d'autorisation. Cet élément vous permet de spécifier l'emplacement où Edge doit rechercher l'ID client. Le seul emplacement valide que vous pouvez définir est l'emplacement par défaut, la variable de flux request.formparam.client_id. La définition de ClientId sur une autre variable n'est pas prise en charge. Consultez également la section Demander des jetons d'accès et des codes d'autorisation.

Valeur par défaut :

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

Présence :

Facultatif

Type : Chaîne
Valeurs correctes : Variable de flux : request.formparam.client_id
Utilisé avec des types d'attribution :
  • authorization_code
  • mot de passe
  • implicite
  • client_credentials

Peut également être utilisé avec l'opération GenerateAuthorizationCode.

Élément <Code>

<Code>request.queryparam.code</Code>

Dans le flux du type d'attribution d'autorisation, le client doit soumettre un code d'autorisation au serveur d'autorisation (Apigee Edge). Cet élément vous permet de spécifier l'emplacement où Edge doit rechercher le code d'autorisation. Par exemple, il peut être envoyé en tant que paramètre de requête, en-tête HTTP ou paramètre de formulaire (par défaut).

La variable request.queryparam.auth_code indique que le code d'autorisation doit être présent en tant que paramètre de requête, par exemple ?auth_code=AfGlvs9. Pour exiger le code d'autorisation dans un en-tête HTTP, définissez cette valeur sur request.header.auth_code. Consultez également la section Demander des jetons d'accès et des codes d'autorisation.

Valeur par défaut :

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

Présence :

facultatif

Type : Chaîne
Valeurs correctes : Toute variable de flux accessible à la règle au moment de l'exécution
Utilisé avec des types d'attribution : authorization_code

Élément <ExpiresIn>

<ExpiresIn>10000</ExpiresIn> 

Applique le délai d'expiration des jetons d'accès et des codes d'autorisation en millisecondes. (Pour les jetons d'actualisation, utilisez <RefreshTokenExpiresIn>.) La valeur du délai d'expiration est une valeur générée par le système plus la valeur <ExpiresIn>. Si <ExpiresIn> est défini sur -1, le jeton ou le code expire conformément à la expiration maximale du jeton d'accès OAuth. Si <ExpiresIn> n'est pas spécifié, le système applique une valeur par défaut configurée au niveau du système.

Le délai d'expiration peut également être défini au moment de l'exécution à l'aide d'une valeur par défaut codée en dur ou d'une référence à une variable de flux. Par exemple, vous pouvez stocker une valeur d'expiration de jeton dans un mappage clé-valeur, la récupérer, l'attribuer à une variable et la référencer dans la règle. Par exemple, kvm.oauth.expires_in.

Avec Apigee Edge pour Cloud public, Edge conserve les entités suivantes en cache pendant au moins 180 secondes après leur accès.

  • Jetons d'accès OAuth. Cela signifie qu'un jeton révoqué peut réussir pendant trois minutes au maximum, jusqu'à ce que la limite du cache expire.
  • Entités du service de gestion des clés (KMS) (Applications, développeurs, produits d'API).
  • Attributs personnalisés sur les jetons OAuth et les entités KMS.

Le stanza suivant spécifie une variable de flux et une valeur par défaut. Notez que la valeur de la variable de flux est prioritaire par rapport à la valeur par défaut spécifiée.

<ExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</ExpiresIn>

Edge ne permet pas de forcer l'expiration d'un jeton après sa création. Si vous devez forcer l'expiration du jeton (par exemple, en fonction d'une condition), une solution possible est décrite dans cet article de la Communauté Apigee.

Par défaut, les jetons d'accès expirés sont automatiquement supprimés du système Apigee Edge automatiquement trois jours après leur expiration. Consultez également la section Supprimer définitivement les jetons d'accès.

Cloud privé: pour une installation Edge pour Private Cloud, la valeur par défaut est définie par la propriété conf_keymanagement_oauth_auth_code_expiry_time_in_millis. Pour définir cette propriété:

  1. Ouvrez le fichier message-processor.properties dans un éditeur. Si le fichier n'existe pas, créez-le :
    vi /opt/apigee/customer/application/message-processor.properties
  2. Définissez la propriété comme vous le souhaitez :
    conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000
  3. Assurez-vous que le fichier de propriétés appartient à l'utilisateur "apigee" :
    chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
  4. Redémarrez le processeur de messages.
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Valeur par défaut :

Si elle n'est pas spécifiée, le système applique une valeur par défaut configurée au niveau du système.

Présence :

Facultatif

Type : Entier
Valeurs correctes :
Utilisé avec des types d'attribution :
  • authorization_code
  • implicite
  • mot de passe
  • client_credentials
  • refresh_token

Utilisé également avec l'opération GenerateAuthorizationCode.

Élément <ExternalAccessToken>

<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>

Indique à Apigee Edge où trouver un jeton d'accès externe (un jeton d'accès non généré par Apigee Edge).

La variable request.queryparam.external_access_token indique que le jeton d'accès externe doit être présent en tant que paramètre de requête, par exemple, ?external_access_token=12345678. Pour exiger le jeton d'accès externe dans un en-tête HTTP, par exemple, définissez cette valeur sur request.header.external_access_token. Consultez également la section Utiliser des jetons OAuth tiers.

Élément <ExternalAuthorization>

<ExternalAuthorization>true</ExternalAuthorization>

Si cet élément est faux ou absent, Edge valide normalement les clients_id et client_secret par rapport au magasin d'autorisations Apigee Edge. Utilisez cet élément lorsque vous souhaitez travailler avec des jetons OAuth tiers. Pour plus d'informations sur l'utilisation de cet élément, consultez la section Utiliser des jetons OAuth tiers.

Valeur par défaut :

false

Présence :

Facultatif

Type : Booléen
Valeurs correctes : True ou False
Utilisé avec des types d'attribution :
  • authorization_code
  • mot de passe
  • client_credentials

Élément <ExternalAuthorizationCode>

<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>

Indique à Apigee Edge où trouver un code d'autorisation externe (un code d'autorisation non généré par Apigee Edge).

La variable request.queryparam.external_auth_code indique que le code d'authentification externe doit être présent en tant que paramètre de requête, par exemple, ?external_auth_code=12345678. Pour exiger le code d'authentification externe dans un en-tête HTTP, par exemple, définissez cette valeur sur request.header.external_auth_code. Consultez également la section Utiliser des jetons OAuth tiers.

Élément <ExternalRefreshToken>

<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>

Indique à Apigee Edge où trouver un jeton d'actualisation externe (un jeton d'actualisation non généré par Apigee Edge).

La variable request.queryparam.external_refresh_token indique que le jeton d'actualisation externe doit être présent en tant que paramètre de requête, par exemple ?external_refresh_token=12345678. Pour exiger le jeton d'actualisation externe dans un en-tête HTTP, par exemple, définissez cette valeur sur request.header.external_refresh_token. Consultez également la section Utiliser des jetons OAuth tiers.

Élément <GenerateResponse>

<GenerateResponse enabled='true'/>

S'il est défini sur true, la règle génère et renvoie une réponse. Par exemple, pour GenerateAccessToken, la réponse peut se présenter comme suit :

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

Si la valeur est false, aucune réponse n'est envoyée. À la place, un ensemble de variables de flux est renseigné avec des valeurs liées à la fonction de la règle. Par exemple, une variable de flux appelée oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code est renseignée avec le nouveau code d'authentification attribué. Notez que expires_in est exprimé en secondes dans la réponse.

Valeur par défaut :

false

Présence :

Facultatif

Type : chaîne
Valeurs correctes : True ou False
Utilisé avec des types d'attribution :
  • implicite
  • mot de passe
  • client_credentials
  • refresh_token
  • Peut également être utilisé avec l'opération GenerateAuthorizationCode.

Élément <GenerateErrorResponse>

<GenerateErrorResponse enabled='true'/>

S'il est défini surtrue, la règle génère et renvoie une réponse si l'attribut ContinueOnError est défini sur "true". Si la valeur est false (par défaut), aucune réponse n'est envoyée. À la place, un ensemble de variables de flux est renseigné avec des valeurs liées à la fonction de la règle.

Valeur par défaut :

false

Présence :

Facultatif

Type : chaîne
Valeurs correctes : True ou False
Utilisé avec des types d'attribution :
  • implicite
  • mot de passe
  • client_credentials
  • refresh_token
  • Peut également être utilisé avec l'opération GenerateAuthorizationCode.

<GrantType>

<GrantType>request.queryparam.grant_type</GrantType>

Indique la règle où trouver le paramètre de type d'attribution transmis dans une requête. Conformément à la spécification OAuth 2.0, le type d'attribution doit être fourni avec des demandes de jetons d'accès et de codes d'autorisation. La variable peut être un en-tête, un paramètre de requête ou un paramètre de formulaire (par défaut).

Par exemple, request.queryparam.grant_type indique que le mot de passe doit être présent en tant que paramètre de requête, comme par exemple ?grant_type=password. Pour exiger le type d'attribution dans un en-tête HTTP, par exemple, définissez cette valeur sur request.header.grant_type. Consultez également la section Demander des jetons d'accès et des codes d'autorisation.

Valeur par défaut :

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

Présence :

Facultatif

Type : chaîne
Valeurs correctes : Une variable, comme expliqué ci-dessus.
Utilisé avec des types d'attribution :
  • authorization_code
  • mot de passe
  • implicite
  • client_credentials
  • refresh_token

Élément <Operation>

<Operation>GenerateAuthorizationCode</Operation>

Opération OAuth 2.0 exécutée par la règle.

Valeur par défaut :

Si <Operation> n'est pas spécifié, Edge examine la liste de <SupportedGrantTypes>. Seules les opérations portant sur ces types d'attribution seront réussies. En d'autres termes, vous pouvez omettre <Operation> lorsque vous spécifiez <GrantType> dans la liste <SupportedGrantTypes>. Si aucune des valeurs <Operation> et <SupportedGrantTypes> ne sont spécifiées, le type d'attribution par défaut est authorization_code. Autrement dit, les requêtes de type d'attribution authorization_code aboutissent, mais toutes les autres échouent.

Présence :

Facultatif

Type : Chaîne
Valeurs correctes :

Élément <PassWord>

<PassWord>request.queryparam.password</PassWord>

Cet élément est utilisé avec le type d'attribution de mot de passe uniquement. Avec le type d'attribution de mot de passe, les identifiants utilisateur (mot de passe et nom d'utilisateur) doivent être disponibles pour la règle OAuthV2. Les éléments <PassWord> et <UserName> permettent de spécifier les variables dans lesquelles Edge peut trouver ces valeurs. Si ces éléments ne sont pas spécifiés, la règle s'attend à trouver les valeurs (par défaut) dans les paramètres de formulaire nommés username et password. Si les valeurs sont introuvables, la règle génère une erreur. Vous pouvez utiliser les éléments <PassWord> et <UserName> pour référencer une variable de flux contenant les identifiants.

Par exemple, vous pouvez transmettre le mot de passe dans une requête de jeton à l'aide d'un paramètre de requête et définir l'élément comme suit : <PassWord>request.queryparam.password</PassWord>. Pour exiger le mot de passe dans un en-tête HTTP, définissez cette valeur sur request.header.password.

La stratégie OAuthV2 ne fait rien d'autre avec ces valeurs d'identification ; Edge vérifie simplement qu'elles sont présentes. Il appartient au développeur de l'API de récupérer la requête de valeurs et de les envoyer à un fournisseur d'identité avant l'exécution de la règle de génération de jetons.

Consultez également la section Demander des jetons d'accès et des codes d'autorisation.

Valeur par défaut :

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

Présence :

Facultatif

Type : Chaîne
Valeurs correctes : Toute variable de flux disponible pour la règle au moment de l'exécution.
Utilisé avec des types d'attribution : mot de passe

Élément <RedirectUri>

<RedirectUri>request.queryparam.redirect_uri</RedirectUri>

Spécifie l'emplacement où Edge doit rechercher le paramètre redirect_uri dans la requête.

À propos des URI de redirection

Les URI de redirection sont utilisés avec le code d'autorisation et les types d'attribution implicites. L'URI de redirection indique au serveur d'autorisation (Edge) où envoyer un code d'autorisation (pour le type d'attribution de code d'autorisation) ou un jeton d'accès (pour le type d'attribution implicite). Il est important de comprendre à quel moment ce paramètre est obligatoire ou facultatif et comment il est utilisé :

  • (Obligatoire) Si une URL de rappel est enregistrée avec l'application de développeur associée aux clés clientes de la requête et si le champ redirect_uri est présent dans la requête, les deux doivent correspondre exactement. S'ils ne correspondent pas, une erreur est renvoyée. Pour plus d'informations sur l'enregistrement d'applications de développement sur Edge et la spécification d'une URL de rappel, consultez Enregistrer des applications et gérer les clés API.

  • (facultatif) Si une URL de rappel est enregistrée et que le redirect_uri est manquant dans la requête, Edge redirige vers l'URL de rappel enregistrée.
  • (Obligatoire) Si une URL de rappel n'est pas enregistrée, la valeur redirect_uri est requise. Notez que dans ce cas, Edge accepte TOUTES les URL. Ce cas peut présenter un problème de sécurité et ne doit donc être utilisé qu'avec des applications clientes de confiance. Si les applications clientes ne sont pas approuvées, il est recommandé de toujours exiger l'enregistrement d'une URL de rappel.

Vous pouvez envoyer ce paramètre dans un paramètre de requête ou dans un en-tête. La variable request.queryparam.redirect_uri indique que l'URI de redirection doit être présent en tant que paramètre de requête, par exemple ?redirect_uri=login.myapp.com. Pour exiger la valeur RedirectUri dans un en-tête HTTP, par exemple, définissez cette valeur sur request.header.redirect_uri. Consultez également la section Demander des jetons d'accès et des codes d'autorisation.

Valeur par défaut :

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

Présence :

Facultatif

Type : Chaîne
Valeurs correctes : Toute variable de flux accessible dans la règle au moment de l'exécution
Utilisé avec des types d'attribution :
  • authorization_code
  • implicite

Utilisé également avec l'opération GenerateAuthorizationCode.

Élément <RefreshToken>

<RefreshToken>request.queryparam.refreshtoken</RefreshToken>

Lorsque vous demandez un jeton d'accès à l'aide d'un jeton d'actualisation, vous devez fournir le jeton d'actualisation dans la requête. Cet élément vous permet de spécifier l'emplacement où Edge doit rechercher le jeton d'actualisation. Par exemple, il peut être envoyé en tant que paramètre de requête, en-tête HTTP ou paramètre de formulaire (par défaut).

La variable request.queryparam.refreshtoken indique que le jeton d'actualisation doit être présent en tant que paramètre de requête, par exemple ?refresh_token=login.myapp.com. Pour exiger la valeur RefreshToken dans un en-tête HTTP, par exemple, définissez cette valeur sur request.header.refresh_token. Consultez également la section Demander des jetons d'accès et des codes d'autorisation.

Valeur par défaut :

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

Présence :

Facultatif

Type : Chaîne
Valeurs correctes : Toute variable de flux accessible dans la règle au moment de l'exécution
Utilisé avec des types d'attribution :
  • refresh_token

Élément <RefreshTokenExpiresIn>

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

Applique le délai d'expiration des jetons d'actualisation en millisecondes. La valeur de délai d'expiration est une valeur générée par le système, plus la valeur <RefreshTokenExpiresIn>. Si <RefreshTokenExpiresIn> est défini sur -1, le jeton d'actualisation expire conformément à l'expiration du jeton d'actualisation OAuth maximale. Si <RefreshTokenExpiresIn> n'est pas spécifié, le délai d'expiration est illimité par défaut.

Le délai d'expiration peut également être défini au moment de l'exécution à l'aide d'une valeur par défaut codée en dur ou d'une référence à une variable de flux. Par exemple, vous pouvez stocker une valeur d'expiration de jeton dans un mappage clé-valeur, la récupérer, l'attribuer à une variable et la référencer dans la règle. Par exemple, kvm.oauth.expires_in.

Le stanza suivant spécifie une variable de flux et une valeur par défaut. Notez que la valeur de la variable de flux est prioritaire par rapport à la valeur par défaut spécifiée.

<RefreshTokenExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</RefreshTokenExpiresIn>

Cloud privé: pour une installation Edge pour Private Cloud, la valeur par défaut est définie par la propriété conf_keymanagement_oauth_refresh_token_expiry_time_in_millis. Pour définir cette propriété:

  1. Ouvrez le fichier message-processor.properties dans un éditeur. Si le fichier n'existe pas, créez-le :
    vi /opt/apigee/customer/application/message-processor.properties
  2. Définissez la propriété comme vous le souhaitez :
    conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000
  3. Assurez-vous que le fichier de propriétés appartient à l'utilisateur "apigee" :
    chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
  4. Redémarrez le processeur de messages.
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Valeur par défaut :

Si elle n'est pas spécifiée, le système applique une valeur par défaut configurée au niveau du système.

Présence :

Facultatif

Type : Entier
Valeurs correctes :
Utilisé avec des types d'attribution :
  • authorization_code
  • mot de passe
  • refresh_token

Élément <ResponseType>

<ResponseType>request.queryparam.response_type</ResponseType>

Cet élément indique à Edge quel type d'attribution l'application cliente demande. Il est utilisé uniquement avec le code d'autorisation et les flux de type d'attribution implicite.

Par défaut, Edge recherche la valeur du type de réponse dans un paramètre de requête response_type. Si vous souhaitez ignorer ce comportement par défaut, utilisez l'élément <ResponseType> pour configurer une variable de flux contenant la valeur du type de réponse. Par exemple, si vous définissez cet élément sur request.header.response_type, Edge recherche le type de réponse à transmettre dans l'en-tête de requête. Consultez également la section Demander des jetons d'accès et des codes d'autorisation.

Valeur par défaut :

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

Présence :

Facultatif. Utilisez cet élément si vous souhaitez remplacer le comportement par défaut.

Type : Chaîne
Valeurs correctes : Soit code (pour le type d'attribution du code d'autorisation), soit token (pour le type d'attribution implicite)
Utilisé avec des types d'attribution :
  • implicite
  • Utilisé également avec l'opération GenerateAuthorizationCode.

Élément <ReuseRefreshToken>

<ReuseRefreshToken>true</ReuseRefreshToken>

Lorsqu'il est défini sur true, le jeton d'actualisation existant est réutilisé jusqu'à son expiration. Si la valeur est false, un nouveau jeton d'actualisation est émis par Apigee Edge lorsqu'un jeton d'actualisation valide est présenté.

Valeur par défaut :

false

Présence :

facultatif

Type : boolean
Valeurs correctes :

true ou false

Utilisé avec le type d'attribution :
  • refresh_token

Élément <Scope>

<Scope>request.queryparam.scope</Scope>

Si cet élément est présent dans l'une des règles GenerateAccessToken ou GenerateAuthorizationCode, il est utilisé pour spécifier quels champs d'application accorder au jeton ou au code. Ces valeurs sont généralement transmises à la règle dans la requête d'une application cliente. Vous pouvez configurer l'élément pour utiliser une variable de flux, ce qui vous permet de choisir la manière dont les champs d'application sont transmis dans une requête. Dans l'exemple suivant, request.queryparam.scope indique que le champ d'application doit être présent en tant que paramètre de requête, par exemple, ?scope=READ. Pour exiger le champ d'application dans un en-tête HTTP, par exemple, définissez cette valeur sur request.header.scope.

Si cet élément apparaît dans une règle "VerifyAccessToken", il est utilisé pour spécifier les champs d'application à appliquer par la règle. Dans ce type de règle, la valeur doit être un nom de champ d'application "encodé en dur". Vous ne pouvez pas utiliser de variables. Exemple :

<Scope>A B</Scope>

Consultez également les pages Utiliser les champs d'application OAuth2 et Demander des jetons d'accès et des codes d'autorisation.

Valeur par défaut :

Aucun champ d'application

Présence :

Facultatif

Type : Chaîne
Valeurs correctes :

Variable de flux utilisée avec les règles Generate*

Si utilisé avec VerifyAccessToken, une liste de noms de champs d'application (chaînes) séparés par des espaces.

Utilisé avec des types d'attribution :
  • authorization_code
  • implicite
  • mot de passe
  • client_credentials
  • Peut également être utilisé avec les opérations GenerateAuthorizationCode et VerifyAccessToken.

Élément <State>

<State>request.queryparam.state</State>

Dans les cas où l'application cliente doit envoyer les informations d'état au serveur d'autorisation, cet élément vous permet de spécifier où Edge doit rechercher les valeurs d'état. Par exemple, elles peuvent être envoyées en tant que paramètre de requête ou dans un en-tête HTTP. La valeur d'état est généralement utilisée comme mesure de sécurité pour empêcher les attaques CSRF.

Par exemple, request.queryparam.state indique que l'état doit être présent en tant que paramètre de requête, comme par exemple ?state=HjoiuKJH32. Pour exiger l'état d'un en-tête HTTP, définissez cette valeur sur request.header.state. Consultez également la section Demander des jetons d'accès et des codes d'autorisation.

Valeur par défaut :

Aucun état

Présence :

Facultatif

Type : Chaîne
Valeurs correctes : Toute variable de flux accessible à la règle au moment de l'exécution
Utilisé avec des types d'attribution :
  • Toutes
  • Peut également être utilisé avec l'opération GenerateAuthorizationCode

Élément <StoreToken>

 <StoreToken>true</StoreToken> 

Définissez cet élément sur true lorsque l'élément <ExternalAuthorization> est true. L'élément <StoreToken> indique à Apigee Edge de stocker le jeton d'accès externe. Autrement, il ne sera pas conservé.

Valeur par défaut :

false

Présence :

Facultatif

Type : Booléen
Valeurs correctes : True ou False
Utilisé avec des types d'attribution :
  • authorization_code
  • mot de passe
  • client_credentials

Élément <SupportedGrantTypes>/<GrantType>

<SupportedGrantTypes>
    <GrantType>authorization_code</GrantType>
    <GrantType>client_credentials</GrantType>
    <GrantType>implicit</GrantType>
    <GrantType>password</GrantType>
</SupportedGrantTypes>

Spécifie les types d'attribution acceptés par un point de terminaison de jeton OAuth sur Apigee Edge. Un point de terminaison peut accepter plusieurs types d'attribution (autrement dit, un seul point de terminaison peut être configuré pour répartir les jetons d'accès pour plusieurs types d'attribution). Pour en savoir plus sur les points de terminaison, consultez la section Comprendre les points de terminaison OAuth. Le type d'attribution est transmis dans les requêtes de jeton dans un paramètre grant_type.

Si aucun type d'attribution n'est spécifié, les seuls types d'attribution autorisés sont authorization_code et implicit. Consultez également l'élément <GrantType> (qui est un élément de niveau supérieur utilisé pour spécifier où Apigee Edge doit rechercher le paramètre grant_type transmis dans une requête client). Edge s'assurera que la valeur du paramètre grant_type correspond à l'un des types d'autorisations pris en charge).

Valeur par défaut :

authorization_code et implicite

Présence :

Obligatoire

Type : Chaîne
Valeurs correctes :
  • client_credentials
  • authorization_code
  • mot de passe
  • implicite

Élément <Tokens>/<Token>

Utilisé avec les opérations ValidateToken et InvalidateToken. Consultez également la section Approuver et révoquer des jetons d'accès. L'élément <Token> identifie la variable de flux qui définit la source du jeton à révoquer. Si les développeurs doivent soumettre des jetons d'accès en tant que paramètres de requête nommés access_token, par exemple, utilisez request.queryparam.access_token.

Élément <UserName>

<UserName>request.queryparam.user_name</UserName>

Cet élément est utilisé avec le type d'attribution de mot de passe uniquement. Avec le type d'attribution de mot de passe, les identifiants utilisateur (mot de passe et nom d'utilisateur) doivent être disponibles pour la règle OAuthV2. Les éléments <PassWord> et <UserName> permettent de spécifier les variables dans lesquelles Edge peut trouver ces valeurs. Si ces éléments ne sont pas spécifiés, la règle s'attend à trouver les valeurs (par défaut) dans les paramètres de formulaire nommés username et password. Si les valeurs sont introuvables, la règle génère une erreur. Vous pouvez utiliser les éléments <PassWord> et <UserName> pour référencer une variable de flux contenant les identifiants.

Par exemple, vous pouvez transmettre le nom d'utilisateur dans un paramètre de requête et définir l'élément <UserName> comme suit : <UserName>request.queryparam.username</UserName>.Pour exiger le nom d'utilisateur dans un en-tête HTTP, définissez cette valeur sur request.header.username.

La stratégie OAuthV2 ne fait rien d'autre avec ces valeurs d'identification ; Edge vérifie simplement qu'elles sont présentes. Il appartient au développeur de l'API de récupérer la requête de valeurs et de les envoyer à un fournisseur d'identité avant l'exécution de la règle de génération de jetons.

Consultez également la section Demander des jetons d'accès et des codes d'autorisation.

Valeur par défaut :

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

Présence :

Facultatif

Type : Chaîne
Valeurs correctes : Tout paramètre de variable.
Utilisé avec des types d'attribution : mot de passe

Vérifier les jetons d'accès

Une fois qu'un point de terminaison de jeton est configuré pour un proxy d'API, une règle OAuthV2 correspondante qui spécifie l'opération VerifyAccessToken est associée au flux qui expose la ressource protégée.

Par exemple, pour garantir que toutes les requêtes adressées à une API sont autorisées, la règle suivante applique une vérification du jeton d'accès :

<OAuthV2 name="VerifyOAuthAccessToken">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

La règle est associée à la ressource d'API à protéger. Pour vous assurer que toutes les requêtes adressées à une API sont vérifiées, associez la règle au PreFlow de la requête ProxyEndpoint, comme suit :

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthAccessToken</Name></Step>
  </Request>
</PreFlow>

Les éléments facultatifs suivants peuvent être utilisés pour remplacer les paramètres par défaut de l'opération VerifyAccessToken.

Nom Description
Définition du champ d'application

Liste de champs d'application délimités par des espaces. La vérification aboutira si au moins un des champs d'application répertoriés est présent dans le jeton d'accès. Par exemple, la règle suivante va vérifier le jeton d'accès pour s'assurer qu'il contient au moins l'un des champs d'application répertoriés. Si READ ou WRITE est présent, la vérification aboutira.

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>
AccessToken Variable dans laquelle le jeton d'accès doit être situé. Par exemple, request.queryparam.accesstoken. Par défaut, le jeton d'accès doit être présenté par l'application dans l'en-tête HTTP d'autorisation, conformément à la spécification OAuth 2.0. Utilisez ce paramètre si le jeton d'accès doit être présenté dans un emplacement non standard, comme un paramètre de requête, ou un en-tête HTTP avec un nom différent de "Authorization".

Consultez également les sections Vérifier les jetons d'accès et Demander des jetons d'accès et des codes d'autorisation.

Spécifier des emplacements de variables de requête

Pour chaque type d'attribution, la règle émet des hypothèses sur l'emplacement ou les informations requises dans les messages de requête. Ces hypothèses sont basées sur la spécification OAuth 2.0. Si vos applications doivent contourner la spécification OAuth 2.0, vous pouvez spécifier les emplacements attendus pour chaque paramètre. Par exemple, lors de la gestion d'un code d'autorisation, vous pouvez spécifier l'emplacement du code d'autorisation, de l'ID client, de l'URI de redirection et du champ d'application. Ceux-ci peuvent être spécifiés en tant qu'en-têtes HTTP, paramètres de requête ou paramètres de formulaire.

L'exemple ci-dessous montre comment spécifier l'emplacement des paramètres de code d'autorisation requis en tant qu'en-têtes 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>
  ...

Ou, si besoin de prendre en charge votre base d'applications clientes, vous pouvez combiner les en-têtes et les paramètres de requête :

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

Un seul emplacement peut être configuré par paramètre.

Variables de flux

Les variables de flux définies dans ce tableau sont renseignées lorsque les règles OAuth respectives sont exécutées. Elles sont donc disponibles pour d'autres règles ou applications exécutées dans le flux de proxy d'API.

Opération VerifyAccessToken

L'opération VerifyAccessToken est exécutée et un grand nombre de variables de flux sont renseignées dans le contexte d'exécution du proxy. Ces variables vous donnent des propriétés liées au jeton d'accès, à l'application de développeur, au développeur et à l'entreprise. Vous pouvez utiliser une règle AssignMessage ou JavaScript, par exemple, pour lire l'une de ces variables et les utiliser si nécessaire plus tard dans le flux. Ces variables peuvent également être utiles à des fins de débogage.

Variables spécifiques au jeton

Variables Description
organization_name Nom de l'organisation où le proxy est en cours d'exécution.
developer.id ID du développeur associé à l'application cliente enregistrée.
developer.app.name Nom du développeur associé à l'application cliente enregistrée.
client_id ID client de l'application cliente enregistrée.
grant_type Type d'attribution associé à la requête.
token_type Type de jeton associé à la requête.
access_token Jeton d'accès en cours de vérification.
accesstoken.{custom_attribute} Attribut personnalisé nommé dans le jeton d'accès.
issued_at Date à laquelle le jeton d'accès a été émis, exprimée en époque Unix, en millisecondes.
expires_in Délai d'expiration du jeton d'accès. Exprimé en secondes. Même si l'élément ExpiresIn définit le délai d'expiration en millisecondes, la valeur est exprimée en secondes dans la réponse du jeton et les variables de flux.
status État du jeton d'accès (par exemple, approuvé ou révoqué).
scope Champ d'application (le cas échéant) associé au jeton d'accès.
apiproduct.<custom_attribute_name> Attribut personnalisé nommé du produit d'API associé à l'application cliente enregistrée.
apiproduct.name Nom du produit d'API associé à l'application cliente enregistrée.
revoke_reason

(Apigee hybrid uniquement) Indique la raison pour laquelle le jeton d'accès a été révoqué.

La valeur peut être REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER ou TOKEN_REVOKED.

Variables spécifiques à l'application

Ces variables sont liées à l'application de développeur associée au jeton.

Variables Description
app.name
app.id
app.accessType
app.callbackUrl
app.status approuvé ou révoqué
app.scopes
app.appFamily
app.apiproducts
app.appParentStatus
app.appType Par exemple : Développeur
app.appParentId
app.created_by
app.created_at
app.last_modified_at
app.last_modified_by
app.{custom_attributes} Attribut personnalisé nommé de l'application cliente enregistrée.

Variables spécifiques au développeur

Si l'élément "app.appType" est "Entreprise", les attributs de l'entreprise sont renseignés et si "app.appType" est défini sur "Développeur", les attributs de développeur sont renseignés.

Variables Description
Variables spécifiques au développeur
developer.id
developer.userName
developer.firstName
developer.lastName
developer.email
developer.status actif ou inactif
developer.apps
developer.created_by
developer.created_at
developer.last_modified_at
developer.last_modified_by
developer.{custom_attributes} Attribut personnalisé nommé du développeur.

Variables spécifiques à l'entreprise

Si l'élément "app.appType" est "Entreprise", les attributs de l'entreprise sont renseignés et si "app.appType" est défini sur "Développeur", les attributs de développeur sont renseignés.

Variables Description
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} Attribut personnalisé nommé de l'entreprise.

Opération GenerateAuthorizationCode

Ces variables sont définies lorsque l'opération GenerateAuthorizationCode s'exécute correctement :

Préfixe : oauthv2authcode.{policy_name}.{variable_name}

Exemple : oauthv2authcode.GenerateCodePolicy.code

Variable Description
code Code d'autorisation généré lors de l'exécution de la règle.
redirect_uri URI de redirection associé à l'application cliente enregistrée.
scope Champ d'application OAuth facultatif transmis dans la requête du client.
client_id ID client transmis dans la requête du client.

Opérations GenerateAccessToken et RefreshAccessToken

Ces variables sont définies lorsque les opérations GenerateAccessToken et RefreshAccessToken s'exécutent correctement. Notez que les variables de jeton d'actualisation ne s'appliquent pas aux flux de type d'attribution des identifiants client.

Préfixe : oauthv2accesstoken.{policy_name}.{variable_name}

Exemple : oauthv2accesstoken.GenerateTokenPolicy.access_token

Nom de la variable Description
access_token Jeton d'accès qui a été généré.
client_id ID client de l'application de développeur associée à ce jeton.
expires_in Valeur d'expiration du jeton. Reportez-vous à l'élément <ExpiresIn> pour plus de détails. Notez que dans la réponse, expires_in est exprimé en secondes.
scope Liste des champs d'application disponibles configurés pour le jeton. Consultez la section Utiliser des champs d'application OAuth2.
status approved ou revoked.
token_type Défini sur BearerToken.
developer.email Adresse e-mail du développeur enregistré propriétaire de l'application de développeur associée au jeton.
organization_name Organisation dans laquelle le proxy s'exécute.
api_product_list Liste des produits associés à l'application de développeur correspondante du jeton.
refresh_count
refresh_token Jeton d'actualisation qui a été généré. Notez que les jetons d'actualisation ne sont pas générés pour le type d'attribution des identifiants client.
refresh_token_expires_in Durée de vie du jeton d'actualisation, en secondes.
refresh_token_issued_at Cette valeur temporelle est la représentation sous forme de chaîne de la quantité d'horodatage 32 bits correspondante. Par exemple, "mer, 21 août 2013 19:16:47 UTC" correspond à la valeur d'horodatage 1377112607413.
refresh_token_status approved ou revoked.

GenerateAccessTokenImplicitGrant

Ces variables sont définies lorsque l'opération GenerateAccessTokenImplicit s'exécute correctement pour le flux de type d'attribution implicite.

Préfixe : oauthv2accesstoken.{policy_name}.{variable_name}

Exemple : oauthv2accesstoken.RefreshTokenPolicy.access_token

Variable Description
oauthv2accesstoken.access_token Jeton d'accès généré lors de l'exécution de la règle.
oauthv2accesstoken.{policy_name}.expires_in Valeur d'expiration du jeton, en secondes. Reportez-vous à l'élément <ExpiresIn> pour plus de détails.

Informations de référence sur les erreurs

Cette section décrit les codes d'erreur et les messages d'erreur renvoyés, ainsi que les variables d'erreur définies par Edge lorsque cette stratégie déclenche une erreur. Ces informations sont importantes si vous développez des règles de défaillance afin de gérer les pannes. Pour en savoir plus, consultez les pages Ce que vous devez savoir à propos des erreurs liées aux règles et Gérer les pannes.

Erreurs d'exécution

Ces erreurs peuvent se produire lors de l'exécution de la règle.

Code d'erreur État HTTP Cause Généré par des opérations
steps.oauth.v2.access_token_expired 401 Le jeton d'accès est arrivé à expiration.

VerifyAccessToken
InvalidateToken

steps.oauth.v2.access_token_not_approved 401 Le jeton d'accès a été révoqué. VerifyAccessToken
steps.oauth.v2.apiresource_doesnot_exist 401 La ressource demandée n'existe dans aucun des produits d'API associés au jeton d'accès. VerifyAccessToken
steps.oauth.v2.FailedToResolveAccessToken 500 La règle était censée trouver un jeton d'accès dans une variable spécifiée dans l'élément <AccessToken>, mais la variable n'a pas pu être résolue. GenerateAccessToken
steps.oauth.v2.FailedToResolveAuthorizationCode 500 La règle était censée trouver un code d'autorisation dans une variable spécifiée dans l'élément <Code>, mais la variable n'a pas pu être résolue. GenerateAuthorizationCode
steps.oauth.v2.FailedToResolveClientId 500 La règle était censée trouver l'ID client dans une variable spécifiée dans l'élément <ClientId>, mais la variable n'a pas pu être résolue. GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken
steps.oauth.v2.FailedToResolveRefreshToken 500 La règle était censée trouver un jeton d'actualisation dans une variable spécifiée dans l'élément <RefreshToken>, mais la variable n'a pas pu être résolue. RefreshAccessToken
steps.oauth.v2.FailedToResolveToken 500 La règle était censée trouver un jeton dans une variable spécifiée dans l'élément <Tokens>, mais la variable n'a pas pu être résolue.

ValidateToken
InvalidateToken

steps.oauth.v2.InsufficientScope 403 Le champ d'application du jeton d'accès présenté dans la requête ne correspond pas à celui spécifié dans la règle VerifyAccessToken. Pour en savoir plus sur le champ d'application, consultez la page Utiliser des champs d'application OAuth2. VerifyAccessToken
steps.oauth.v2.invalid_access_token 401 Le jeton d'accès envoyé à partir du client n'est pas valide. VerifyAccessToken
steps.oauth.v2.invalid_client 401

Ce nom d'erreur est renvoyé lorsque la propriété <GenerateResponse> de la règle est définie sur true et que l'ID client envoyé dans la requête n'est pas valide. Vérifiez que vous utilisez les valeurs correctes de clé et de code secret du client pour l'application de développeur associée à votre proxy. En règle générale, ces valeurs sont envoyées sous la forme d'un en-tête d'autorisation de base encodé en base64.

Remarque : Nous vous recommandons de modifier les conditions de règle d'erreur existantes pour identifier les noms invalid_client et InvalidClientIdentifier. Consultez les notes de version 16.09.21 pour obtenir plus d'informations et un exemple.

GenerateAccessToken
RefreshAccessToken
steps.oauth.v2.invalid_request 400 Ce nom d'erreur est utilisé pour plusieurs types d'erreurs, généralement pour des paramètres manquants ou incorrects envoyés dans la requête. Si <GenerateResponse> est défini sur false, utilisez des variables d'erreur (décrites ci-dessous) pour récupérer des informations sur l'erreur, telles que son nom et sa cause. GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken
steps.oauth.v2.InvalidAccessToken 401 L'en-tête d'autorisation ne comporte pas le mot "Bearer", qui est obligatoire. Exemple : Authorization: Bearer your_access_token VerifyAccessToken
steps.oauth.v2.InvalidAPICallAsNo\
steps.oauth.v2.ApiProductMatchFound
401

Le proxy d'API ne se trouve pas dans le produit associé au jeton d'accès.

Conseil : Assurez-vous que le produit associé au jeton d'accès est correctement configuré. Par exemple, si vous utilisez des caractères génériques dans les chemins d'accès aux ressources, veillez à les utiliser correctement. Pour plus d'informations, consultez la page Créer des produits d'API.

Consultez également ce post de la communauté Apigee pour obtenir des conseils sur les causes de cette erreur.

VerifyAccessToken
steps.oauth.v2.InvalidClientIdentifier 500

Ce nom d'erreur est renvoyé lorsque la propriété <GenerateResponse> de la règle est définie sur false et que l'ID client envoyé dans la requête n'est pas valide. Vérifiez que vous utilisez les valeurs correctes de clé et de code secret du client pour l'application de développeur associée à votre proxy. En règle générale, ces valeurs sont envoyées sous la forme d'un en-tête d'autorisation de base encodé en base64.

Remarque : Dans ce cas, cette erreur était auparavant appelée invalid_client. Nous vous recommandons de modifier les conditions de règle d'erreur existantes pour identifier les noms invalid_client et InvalidClientIdentifier. Consultez les notes de version 16.09.21 pour obtenir plus d'informations et un exemple.

GenerateAccessToken
RefreshAccessToken

steps.oauth.v2.InvalidParameter 500 La règle doit spécifier un jeton d'accès ou un code d'autorisation, mais pas les deux. GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
steps.oauth.v2.InvalidTokenType 500 L'élément <Tokens>/<Token> nécessite de spécifier le type de jeton (par exemple, refreshtoken). Si le client transmet le mauvais type, cette erreur est générée. ValidateToken
InvalidateToken
steps.oauth.v2.MissingParameter 500 Le type de réponse est token, mais aucun type d'attribution n'est spécifié. GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
steps.oauth.v2.UnSupportedGrantType 500

Le client a spécifié un type d'attribution non compatible avec la règle (non répertorié dans l'élément <SupportedGrantTypes>).

Remarque : Il existe actuellement un bug dans lequel les erreurs liées à un type d'attribution non compatible ne sont pas générées correctement. Si une erreur de ce genre se produit, le proxy ne passe pas par le flux d'erreurs, comme prévu.

GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken

Erreurs de déploiement

Ces erreurs peuvent se produire lorsque vous déployez un proxy contenant cette règle.

Nom de l'erreur Cause
InvalidValueForExpiresIn

Pour l'élément <ExpiresIn>, les valeurs valides sont des entiers positifs et -1.

InvalidValueForRefreshTokenExpiresIn Pour l'élément <RefreshTokenExpiresIn>, les valeurs valides sont des entiers positifs et -1.
InvalidGrantType Un type d'attribution non valide est spécifié dans l'élément <SupportedGrantTypes>. Pour obtenir la liste des types valides, consultez la documentation de référence sur les règles.
ExpiresInNotApplicableForOperation Assurez-vous que les opérations spécifiées dans l'élément <Operations> sont compatibles avec l'expiration. Par exemple, ce n'est pas le cas de l'opération VerifyToken.
RefreshTokenExpiresInNotApplicableForOperation Assurez-vous que les opérations spécifiées dans l'élément <Operations> sont compatibles avec l'expiration du jeton d'actualisation. Par exemple, ce n'est pas le cas de l'opération VerifyToken.
GrantTypesNotApplicableForOperation Assurez-vous que les types d'attribution spécifiés dans <SupportedGrantTypes> sont compatibles pour l'opération spécifiée.
OperationRequired

Vous devez spécifier une opération dans cette règle à l'aide de l'élément <Operation>.

Remarque : Si l'élément <Operation> est manquant, l'UI génère une erreur de validation du schéma.

InvalidOperation

Vous devez spécifier une opération valide dans cette règle à l'aide de l'élément <Operation>.

Remarque : Si l'élément <Operation> n'est pas valide, l'UI génère une erreur de validation du schéma.

TokenValueRequired Vous devez spécifier une valeur de jeton <Token> dans l'élément <Tokens>.

Variables de panne

Ces variables sont définies lorsque cette règle déclenche une erreur au moment de l'exécution.

Variables Où : Exemple
fault.name="fault_name" fault_name est le nom de l'erreur, tel qu'indiqué dans le tableau Erreurs d'exécution ci-dessus. Le nom d'erreur est la dernière partie du code d'erreur. fault.name = "invalid_request"
oauthV2.policy_name.failed policy_name est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur. oauthV2.GenerateAccesstoken.failed = true
oauthV2.policy_name.fault.name policy_name est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur. oauthV2.GenerateAccesstoken.fault.name = invalid_request

Remarque : Pour l'opération VerifyAccessToken, le nom d'erreur inclut le suffixe suivant : keymanagement.service
Par exemple : keymanagement.service.invalid_access_token

oauthV2.policy_name.fault.cause policy_name est le nom spécifié par l'utilisateur de la règle qui a provoqué l'erreur. oauthV2.GenerateAccesstoken.cause = Required param : grant_type

Exemple de réponse d'erreur

Ces réponses sont renvoyées au client si l'élément <GenerateResponse> est défini sur true.

Si <GenerateResponse> est défini sur true, la règle renvoie des erreurs dans ce format pour les opérations générant des jetons et des codes. Pour obtenir la liste complète, consultez la documentation de référence sur les réponses aux erreurs HTTP OAuth.

{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}

Si <GenerateResponse> est défini sur true, la règle renvoie des erreurs dans ce format pour les opérations de vérification et de validation. Pour obtenir la liste complète, consultez la documentation de référence sur les réponses aux erreurs HTTP OAuth.

{  
   {  
      "fault":{  
         "faultstring":"Invalid Access Token",
         "detail":{  
            "errorcode":"keymanagement.service.invalid_access_token"
         }
      }
   }

Exemple de règle de défaillance

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

Schéma de la règle

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.

Utiliser la configuration OAuth par défaut

Chaque organisation (y compris une organisation bénéficiant d'un essai sans frais) sur Apigee Edge est provisionnée avec un point de terminaison de jeton OAuth. Le point de terminaison est préconfiguré avec des règles dans le proxy d'API appelée oauth. Vous pouvez commencer à utiliser le point de terminaison du jeton dès que vous créez un compte sur Apigee Edge. Pour plus de détails, consultez la section Comprendre les points de terminaison OAuth.

Supprimer définitivement des jetons d'accès

Par défaut, les jetons OAuth2 sont supprimés définitivement du système Apigee Edge trois jours (259 200 secondes) après l'expiration du jeton d'accès et du jeton d'actualisation (le cas échéant). Dans certains cas, vous pouvez modifier cette valeur par défaut. Par exemple, vous pouvez réduire le temps de suppression pour économiser de l'espace disque si un grand nombre de jetons sont générés.

Si vous utilisez Edge pour Private Cloud, vous pouvez modifier cette valeur par défaut en définissant les propriétés d'organisation comme expliqué dans cette section. (La suppression définitive des jetons expirés au cours des trois jours s'applique à Edge for Private Cloud version 4.19.01 et ultérieures. Pour les versions antérieures, l'intervalle de suppression définitive par défaut est de 180 jours.)

Mise à jour des paramètres de suppression définitive pour Edge Private Cloud 4.16.01 et versions ultérieures

Remarque:Seuls les jetons générés après l'application de ces paramètres sont affectés. Les paramètres ne s'appliquent pas aux jetons générés précédemment.

Mise à jour des paramètres de suppression définitive pour Edge Private Cloud 4.15.07

Remarque:Seuls les jetons générés après l'application de ces paramètres sont affectés. Les paramètres ne s'appliquent pas aux jetons générés précédemment.

Comportement non conforme à la documentation RFC

La règle OAuthV2 renvoie une réponse de jeton contenant certaines propriétés non conformes à la norme RFC. Le tableau suivant présente les propriétés non conformes renvoyées par la règle OAuthV2 et les propriétés conformes correspondantes.

OAuthV2 renvoie : La propriété conforme à la norme RFC est la suivante :
"token_type":"BearerToken" "token_type":"Bearer"
"expires_in":"3600" "expires_in":3600

(La valeur conforme est un nombre et non une chaîne.)

En outre, la réponse d'erreur pour un jeton d'actualisation arrivé à expiration dans le cas grant_type = refresh_token est :

{"ErrorCode" : "invalid_request", "Error" :"Refresh Token expired"}

Cependant, la réponse conforme à la RFC est la suivante:

{"error" : "invalid_grant", "error_description" :"refresh token expired"}

Articles associés