Règle OAuthV2

Vous consultez la documentation d'Apigee Edge.
Accédez à la documentation sur Apigee X. info

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 comment cette stratégie est utilisée dans une application fonctionnelle.

Exemples

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

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

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

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

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

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

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

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

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

É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ù Edge 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.

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

É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 spécifie qu'Apigee doit rechercher l'ID client dans 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.

Élément <Code>

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

Dans le flux du type d'octroi d'autorisation, le client doit soumettre un code d'autorisation au serveur d'autorisation (Apigee Edge). Cet élément vous permet de spécifier 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.

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

Avec Apigee Edge pour le cloud public, Edge conserve les entités suivantes en cache pendant un minimum de 180 secondes après l'accès aux entités.

• Jetons d'accès OAuth. Cela signifie qu'un jeton révoqué peut toujours fonctionner jusqu'à trois minutes, jusqu'à ce que sa limite de 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 prend pas en charge un moyen 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 Edge 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 le cloud privé, 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

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

Élément <ExternalAuthorizationCode>

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

Indique à Apigee Edge où trouver un code d'authentification externe (un code d'authentification 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.

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

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

Élément <Operation>

<Operation>GenerateAuthorizationCode</Operation>

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

É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 règle OAuthV2 n'effectue aucune autre action avec ces valeurs d'identifiants. Edge 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.

Élément <RedirectUri>

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

Spécifie 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) 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é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 redirect_uri n'apparaît pas 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.

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

É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 en savoir plus sur les paramètres système par défaut, contactez l'assistance Apigee Edge.

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 le cloud privé, 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

Élément <ResponseType>

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

Cet élément indique à Edge 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, 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 la requête. Consultez également la section Demander des jetons d'accès et des codes d'autorisation.

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

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

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

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

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

É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 règle OAuthV2 n'effectue aucune autre action avec ces valeurs d'identifiants. Edge 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.

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.

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>

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, 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 spécifiques à l'application

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

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

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

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

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

Informations de référence sur les erreurs

Cette section décrit les codes d'erreur et les messages d'erreur qui sont 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.

Erreurs de déploiement

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

Variables de panne

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

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 (même une organisation en 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 des jetons dès que vous avez créé 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 le cloud privé, vous pouvez modifier cette valeur par défaut en définissant les propriétés de l'organisation, comme expliqué dans cette section. (La purge de trois jours des jetons expirés s'applique à Edge pour Private Cloud version 4.19.01 et ultérieure. Pour les versions antérieures, l'intervalle de purge par défaut est de 180 jours.)

Modifier les paramètres de purge 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 concernés. Ils ne s'appliquent pas aux jetons générés précédemment.

Modifier les paramètres de purge pour Edge Private Cloud 4.15.07

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

Comportement non conforme à la norme 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.

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

• Présentation d'OAuth 2.0