Règle OAuthV2

Vous consultez la documentation d'Apigee X.
Consultez la documentation d'Apigee Edge.

icône de la règle

Objet

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.

Conseil : Si vous souhaitez en savoir plus au sujet d'OAuth sur Apigee, consultez la page d'accueil OAuth. Elle fournit des liens vers des ressources, des exemples, des vidéos, etc.

Exemples

VerifyAccessToken

VerifyAccessToken

Cette configuration de règle OAuthV2 (avec l'opération VerifyAccessToken) vérifie qu'un jeton d'accès envoyé à Apigee est valide. Lorsque cette opération de règle est déclenchée, Apigee 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 disponibles. Les jetons de code d'authentification de message (MAC, Message Authentication Code) ne sont pas acceptés.

Exemple :

$ curl https://your_host_alias/weather/forecastrss?w=12797282 \
  -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z"

your_host_alias est un domaine public utilisé pour accéder à vos API, tel que configuré dans la propriété virtualhosts.hostAliases de votre fichier de remplacement. Consultez la section Spécifier des remplacements de configuration.

Par défaut, Apigee 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.

Jetons d'accès JWT

Jetons d'accès JWT

Pour obtenir des exemples montrant comment générer, valider et actualiser des jetons d'accès JWT, consultez la page Utiliser des jetons d'accès JWT.

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 de contexte "local_clientid" et "local_secret" doivent être définies au préalable et disponibles dans le flux :

var clientId = context.getVariable("local_clientid");
var clientSecret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+ CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(clientId + ':' + clientSecret)));

Consultez également la section Encoder des 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.

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

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

vrai Facultatif
async

Cet attribut est obsolète.

faux 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

ND

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://your_host_alias/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

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

curl "https://your_host_alias/oauth2/validate?access_token:Rft3dqrs56Blirls56a"

your_host_alias est un domaine public utilisé pour accéder à vos API, tel que configuré dans la propriété virtualhosts.hostAliases de votre fichier de remplacement. Consultez la section Spécifier des remplacements de configuration.

Valeur par défaut :

ND

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

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Spécifie l'algorithme de chiffrement utilisé pour signer un jeton d'accès JWT. Les algorithmes RSA (RS*) utilisent une paire de clés publique/secrètes, tandis que les algorithmes HMAC (HS*) utilisent une clé secrète partagée. Cet élément est requis pour les opérations GenerateJWTAccessToken, VerifyJWTAccessToken et RefreshJWTAccessToken.

Default N/A
Présence Obligatoire lors de l'utilisation des opérations GenerateJWTAccessToken, VerifyJWTAccessToken et RefreshJWTAccessToken.
Type Chaîne
Valeurs valides HS256, HS384, HS512, RS256, RS384, RS512

Élément <AppEndUser>

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

Dans les cas où l'ID d'utilisateur final de l'application doit être envoyé au serveur d'autorisation, cet élément vous permet de spécifier où Apigee doit rechercher l'ID d'utilisateur final. 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 :

ND

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, Apigee ne se souvient pas que l'attribut display était initialement défini sur false dans la règle de génération de jeton 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 tous les attributs personnalisés que vous ne souhaitez pas afficher 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 où Apigee 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 de type d'attribution, le client doit soumettre un code d'autorisation au serveur d'autorisation (Apigee). Cet élément vous permet de spécifier où Apigee 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 de 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 à l'expiration du jeton d'accès OAuth maximale. 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.

Apigee conserve les entités suivantes en cache pendant au moins 180 secondes après l'accès aux entités.

  • Jetons d'accès OAuth. Cela signifie que l'élément ExpiresIn de la règle OAuth v2 ne pourra pas faire expirer un jeton d'accès en moins de 180 secondes.
  • 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>

Apigee 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 arrivés à expiration sont automatiquement et définitivement supprimés du système Apigee trois jours après leur expiration. Consultez également la section Supprimer définitivement les jetons d'accès.

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 :
  • Tout entier positif non nul. Spécifie le délai d'expiration en millisecondes. Bien que la valeur de cet élément soit exprimée en millisecondes, la valeur définie dans la propriété expires_in du jeton et celle de la variable de flux expires_in sont exprimées en secondes.
  • -1 expirera selon l'expiration du jeton d'accès OAuth maximale.

    Remarque : La spécification d'un autre entier négatif ou égal à zéro entraîne une erreur de déploiement.
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 où trouver un jeton d'accès externe (un jeton d'accès non généré par Apigee).

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 "false" ou manquant, Apigee valide le client_id et le client_secret de façon normale par rapport au magasin d'autorisation Apigee. 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 :

faux

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 où trouver un code d'authentification externe (un code d'authentification non généré par Apigee).

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 où trouver un jeton d'actualisation externe (un jeton d'actualisation non généré par Apigee).

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 :

faux

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 :

faux

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é, Apigee 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 :

Opérations supplémentaires liées aux jetons d'accès JWT

Si vous préférez utiliser des jetons d'accès JWT au lieu de jetons de chaîne opaques, les opérations suivantes sont également disponibles pour générer et valider des jetons JWT. Pour plus d'informations, consultez la section Utiliser des opérations de jeton OAuth JWT:

É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 Apigee 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 règle OAuthV2 n'effectue aucune autre action avec ces valeurs d'identifiants. Apigee vérifie simplement qu'ils sont présents. 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

<PrivateKey>/<Valeur>

<PrivateKey>
  <Value ref="variable-name-here"/>
</PrivateKey>

Fournit la clé privée utilisée pour vérifier ou signer les jetons d'accès au format JWT avec un algorithme RSA. Utilisez l'attribut ref pour transmettre la clé dans une variable de flux. À n'utiliser que lorsque la valeur de l'élément Algorithm est RS256, RS384 ou RS512. Pour en savoir plus, consultez la page Utiliser des opérations de jetons OAuth JWT.

Default N/A
Présence Obligatoire lorsque la valeur de l'élément Algorithm est HS256, HS384 ou HS512.
Type Chaîne
Valeurs valides Variable de flux contenant une chaîne représentant une valeur de clé privée RSA encodée au format PEM.

<PublicKey>/<Value>

<PublicKey>
   <Value ref="variable-name-here"/>
</PublicKey>

Spécifie la clé publique ou le certificat public utilisé pour vérifier la signature sur un jeton d'accès au format JWT signé avec un algorithme RSA. Utilisez l'attribut ref pour transmettre la clé/le certificat dans une variable de flux. À n'utiliser que lorsque la valeur de l'élément Algorithm est RS256, RS384 ou RS512.

Default N/A
Présence Pour valider un jeton JWT signé avec un algorithme RSA, vous devez utiliser les éléments "Certificate", "JWKS" ou "Value".
Type Chaîne
Valeurs valides Une variable de flux ou une chaîne

Élément <RedirectUri>

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

Spécifie où Apigee 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 (Apigee) l'adresse à laquelle envoyer un code d'autorisation (pour le type d'attribution de code d'authentification) 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éveloppeur sur Apigee et la spécification d'URL de rappel, consultez la section Enregistrer des applications et gérer les clés API.

  • (Facultatif) Si une URL de rappel est enregistrée et que redirect_uri ne figure pas dans la requête, Apigee 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, Apigee 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 où Apigee 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 système applique une valeur par défaut configurée au niveau du système. Pour plus d'informations sur les paramètres système par défaut, contactez l'Assistance Apigee.

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>

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 :
  • Tout entier positif non nul. Spécifie le délai d'expiration, en millisecondes.
  • -1 expirera selon l'expiration du jeton d'actualisation OAuth maximale.

    Remarque : La spécification d'un autre entier négatif ou égal à zéro entraîne une erreur de déploiement.
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 à Apigee le type d'attribution demandé par l'application cliente. Il est utilisé uniquement avec le code d'autorisation et les flux de type d'attribution implicite.

Par défaut, Apigee 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, Apigee recherche le type de réponse à transmettre dans l'en-tête de la 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. S'il est défini sur false, un nouveau jeton d'actualisation est émis par Apigee lorsqu'un jeton d'actualisation valide est présenté.

Valeur par défaut :

false

Présence :

facultatif

Type : booléen
Valeurs correctes :

true ou false

Utilisé avec le type d'attribution :
  • refresh_token

Élément <RFCCompliantRequestResponse>

<RFCCompliantRequestResponse>[true | false]</RFCCompliantRequestResponse>

Lorsqu'il est défini sur true, la règle respecte les normes RFC6749 et active les comportements conformes suivants :

  • Les réponses d'erreur et sans erreur incluent le champ d'en-tête de réponse HTTP Cache-Control pour être conforme à la norme RFC2616 (Hypertext Transfer Protocol -- HTTP/1.1), avec la valeur no-store dans toute réponse contenant des jetons, des identifiants ou d'autres informations sensibles, ainsi que le champ d'en-tête de réponse Pragma avec la valeur no-cache.
  • La propriété expires_in est au format numérique. Par souci de cohérence, refresh_token_expires_in est également alphanumérique.
  • Les réponses OAuthV2 pour la génération de jetons comprennent le champ d'en-tête Bearer conforme à la norme RFC au lieu de BearerToken.
  • Les messages d'erreur dans les charges utiles de réponse sont au format suivant : {"error" : "xxx", "error_description" :"yyy"} pour les erreurs de jeton d'actualisation.

Valeur par défaut :

false : par défaut, la règle autorise certains comportements non conformes à la documentation RFC. Pour en savoir plus, consultez la section Comportement non conforme à la norme RFC. Définissez cet élément sur true pour activer la conformité RFC.

Présence :

Facultatif

Type : Booléen
Valeurs correctes : true ou false
Utilisé avec des types d'attribution : Tous

<SecretKey>/<Value>

<SecretKey>
  <Value ref="your-variable-name"/>
</SecretKey>

Fournit la clé secrète utilisée pour vérifier ou signer les jetons d'accès au format JWT avec un algorithme HMAC. Utilisez ce paramètre uniquement lorsque l'algorithme est HS256, HS384 ou HS512. Utilisez l'attribut ref pour transmettre la clé dans une variable de flux. Pour en savoir plus, consultez la page Utiliser des opérations de jetons OAuth JWT.

Apigee applique un niveau de sécurité de clé minimal pour les algorithmes HS256/HS384/HS512. La longueur de clé minimale pour HS256 est de 32 octets, pour HS384 de 48 octets, et pour HS512 de 64 octets. L'utilisation d'une clé d'un niveau de sécurité inférieur entraîne une erreur d'exécution.

Default N/A
Présence Obligatoire pour les algorithmes HMAC.
Type Chaîne
Valeurs valides Une variable de flux

É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 sections 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 :

Si utilisé avec les règles "Générer"*, une variable de flux.

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ù Apigee 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 :
  • Tous
  • 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 qu'il doit stocker le jeton d'accès externe. Autrement, il ne sera pas conservé.

Valeur par défaut :

faux

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 pris en charge par un point de terminaison de jeton OAuth sur Apigee. 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> (élément de niveau supérieur permettant de spécifier où Apigee doit rechercher le paramètre grant_type transmis dans une requête client. Apigee va s'assurer que la valeur du paramètre grant_type correspond à l'un des types d'attribution compatibles).

Valeur par défaut :

authorization_code et implicite

Présence :

Requis

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 Apigee 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 règle OAuthV2 n'effectue aucune autre action avec ces valeurs d'identifiants. Apigee vérifie simplement qu'ils sont présents. 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
Portée

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

Lors de l'exécution de l'opération VerifyAccessToken, 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 et au développeur. 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. Non compatible avec l'opération VerifyJWTAccessToken.
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é. Non compatible avec l'opération VerifyJWTAccessToken.

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

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 et les variables d'erreur définies par Apigee lorsque cette règle 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.

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'entête d'autorisation ne contient 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. Consultez la section Gérer les produits API pour plus de détails.

Pour en savoir plus sur les causes de cette erreur, consultez également l'article Lors de la vérification d'un jeton d'accès, l'erreur "Invalid API call as no apiproduct match found" (Appel API non valide car aucune correspondance apiproduct trouvée) apparaît.

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.

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

GenerateAccessToken
GenerateAuthorizationCode
GenerateAccessTokenImplicitGrant
RefreshAccessToken

Erreurs d'exécution spécifiques aux jetons JWT

Les codes d'erreur et les descriptions des flux d'authentification JWT dépendent du contexte du flux OAuth2:

Codes d'erreur pour la génération et l'actualisation des jetons JWT

Pour les flux OAuth2 qui génèrent ou actualisent des jetons JWT, les réponses d'erreur respectent les réponses d'erreur spécifiées dans le document RFC6749. Pour en savoir plus, consultez la Section 5.2 Réponse d'erreur.

Codes d'erreur pour le flux de vérification des jetons

Les codes d'erreur répertoriés dans le tableau suivant ne s'appliquent qu'à l'opération VerifyAccessToken.

Code d'erreur État HTTP Cause Généré par des opérations
oauth.v2.JWTSigningFailed 401 La règle n'a pas pu signer le jeton JWT.

GenerateJWTAccessToken

oauth.v2.InvalidValueForJWTAlgorithm 401 Cette erreur se produit lorsque l'algorithme n'est pas présent dans le jeton d'accès JWT ou lorsque la valeur n'est pas acceptée.

GenerateJWTAccessToken
VerifyJWTAccessToken

oauth.v2.InsufficientKeyLength 401 En génération de jeton JWT, pour une clé inférieure à la taille minimale des algorithmes HS384 ou HS512

GenerateJWTAccessToken
VerifyJWTAccessToken

oauth.v2.JWTAlgorithmMismatch 401 L'algorithme spécifié dans la règle "Générer" ne correspond pas à celui attendu dans la règle "Vérifier". Les algorithmes spécifiés doivent correspondre.

VerifyJWTAccessToken

oauth.v2.JWTDecodingFailed 401 La règle n'a pas pu décoder le jeton JWT. Le jeton JWT est peut-être corrompu.

VerifyJWTAccessToken

oauth.v2.MissingMandatoryClaimsInJWT 401 Se produit lorsque les revendications requises ne sont pas présentes dans le jeton d'accès JWT

VerifyJWTAccessToken

oauth.v2.InvalidJWTSignature 401 Cette erreur se produit lorsque la signature du jeton d'accès JWT n'a pas pu être vérifiée ou lorsque la signature n'est pas valide.

VerifyJWTAccessToken

oauth.v2.InvalidTypeInJWTHeader 401 Se produit lorsque le type de JWT n'est pas at+Jwt.

VerifyJWTAccessToken

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, l'opération VerifyToken ne l'est pas.
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'autorisation spécifiés dans <SupportedGrantTypes> sont compatibles avec 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>.

InvalidOperation

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

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

Erreurs de déploiement spécifiques aux jetons JWT

Ces erreurs de déploiement sont spécifiques aux règles qui utilisent des opérations de jeton JWT.

Nom de l'erreur Cause
InvalidValueForAlgorithm L'algorithme spécifié dans l'élément <Algorithm> ne figure pas dans la liste des algorithmes disponibles ou n'est pas présent.
MissingKeyConfiguration Les éléments <SecretKey>, <PrivateKey> ou <PublicKey> requis sont manquants, selon l'algorithme utilisé.
EmptyValueElementForKeyConfiguration L'élément enfant <Value> requis n'est pas défini dans les éléments <PrivateKey>, <PublicKey> ou <SecretKey>.
InvalidKeyConfiguration L'élément <PrivateKey> n'est pas utilisé avec les algorithmes de la famille RSA ou l'élément <SecretKey> n'est pas utilisé avec les algorithmes de la famille HS.
EmptyRefAttributeForKeyconfiguration L'attribut ref de l'élément enfant <Value> des éléments <PrivateKey>, <PublicKey> ou <SecretKey> est vide.
InvalidVariableNameForKey Le nom de la variable de flux spécifié dans l'attribut ref de l'élément enfant <Value> des éléments <PrivateKey>, <PublicKey> ou <SecretKey> ne contient pas le préfixe private.

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

Les jetons dans l'espace de stockage sont hachés

Si vous utilisez Apigee hybrid ou Apigee X, les jetons d'accès OAuthV2 et les jetons d'actualisation sont hachés par défaut lorsqu'ils sont stockés dans la base de données Cassandra associée. Le hachage empêche l'utilisation des jetons si la base de données a été compromise.

Utiliser la configuration OAuth par défaut

Chaque organisation (même une organisation en essai gratuit) sur Apigee 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 de jeton dès que vous créez un compte sur Apigee. 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 du système Apigee trois jours (259 200 secondes) après l'expiration du jeton d'accès et du jeton d'actualisation (s'il existe). 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.

Comportement non conforme à la norme RFC

Par défaut, la stratégie OAuthV2, avec l'opération GenerateAccessToken, renvoie une réponse à un 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"}

Toutefois, la réponse conforme à la norme RFC est la suivante :

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

Articles associés