Règle OAuthV2

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

Consultez la documentation d'Apigee Edge.

Événement

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.

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

Pour en savoir plus sur OAuth sur Apigee, consultez la page d'accueil OAuth. Elle fournit des liens vers des ressources, des exemples, des vidéos, etc.

Exemples

<OAuthV2 name="OAuthV2-Verify-Access-Token">
    <Operation>VerifyAccessToken</Operation>
</OAuthV2>

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

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

É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, lorsque Operation est défini sur VerifyAccessToken, la règle s'attend à ce que le jeton d'accès soit envoyé dans l'en-tête Authorization en tant que jeton de support, autrement dit avec le préfixe "Bearer", suivi d'un espace. Vous pouvez modifier cette valeur par défaut à l'aide de cet élément, en spécifiant le nom d'une variable contenant le jeton d'accès à vérifier. Lorsque vous utilisez cet élément, par défaut, la règle ne recherche pas de préfixe dans le contenu de la variable. Si vous souhaitez spécifier que la règle doit rechercher un préfixe, utilisez également l'élément AccessTokenPrefix.

Exemples :

• Lorsque la configuration de la règle est la suivante :

    <OAuthV2 name="OAuthV2-Verify-Access-Token-in-Header">
        <Operation>VerifyAccessToken</Operation>
        <AccessToken>request.header.access_token</AccessToken>
    </OAuthV2>

  Pour transmettre le jeton à l'aide de curl, vous pouvez utiliser :

    curl https://API_ENDPOINT/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

• Lorsque la configuration de la règle est la suivante :

    <OAuthV2 name="OAuthV2-Verify-Access-Token-in-QueryParam">
        <Operation>VerifyAccessToken</Operation>
        <AccessToken>request.queryparam.token</AccessToken>
    </OAuthV2>

  Pour transmettre le jeton à l'aide de curl, vous pouvez utiliser :

    curl "https://API_ENDPOINT/oauth2/validate?token=Rft3dqrs56Blirls56a"

Où API_ENDPOINT est le domaine utilisé pour accéder à vos API, tel que configuré dans votre système Apigee.

Élément <AccessTokenPrefix>

<AccessTokenPrefix>Prefix</AccessTokenPrefix>

Par défaut, lorsque Operation est défini sur VerifyAccessToken, la règle s'attend à ce que le jeton d'accès soit envoyé dans l'en-tête Authorization en tant que jeton de support, autrement dit avec le préfixe "Bearer", suivi d'un espace. Si vous utilisez l'élément AccessToken pour spécifier un emplacement différent pour le jeton d'accès entrant, vous pouvez également utiliser cet élément, AccessTokenPrefix, pour spécifier un préfixe différent non standard.

Par exemple, si vous spécifiez ce qui suit :

<OAuthV2 name="OAuthV2-Verify-Access-Token-Alternative-Header">
    <Operation>VerifyAccessToken</Operation>
    <AccessToken>request.header.token</AccessToken>
    <AccessTokenPrefix>KEY</AccessTokenPrefix>
</OAuthV2>

La règle extrait alors le jeton d'accès entrant de l'en-tête de requête token de la façon suivante : si l'en-tête commence par le mot "KEY" suivi d'un espace, la règle supprime ce préfixe et interprète la valeur restante comme étant le jeton d'accès. Si le préfixe spécifié n'est pas présent dans l'en-tête, la règle génère une erreur.

Si vous spécifiez l'élément AccessToken sans spécifier l'élément AccessTokenPrefix, la règle interprète la valeur entière de la variable spécifiée dans l'élément AccessToken comme étant le jeton d'accès.

Cet élément n'entre en vigueur que lorsque l'élément AccessToken est également utilisé.

<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ète, tandis que les algorithmes HMAC (HS*) utilisent un secret partagé. Cet élément est requis pour les opérations GenerateJWTAccessToken, VerifyJWTAccessToken et RefreshJWTAccessToken.

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

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

Élément <CacheExpiryInSeconds>

<CacheExpiryInSeconds ref="propertyset.settings.token-ttl">60</CacheExpiryInSeconds>

Cet élément ne peut être utilisé qu'avec l'opération VerifyAccessToken. Il spécifie la valeur TTL (Time To Live) sur le cache du jeton d'accès pour l'exécution de la stratégie spécifique. La première fois qu'Apigee vérifie un jeton d'accès OAuth 2, il doit le récupérer à partir d'un magasin persistant. Il s'agit d'une opération relativement coûteuse. Apigee met donc en cache le résultat de la recherche de jeton, y compris l'état du jeton, la liste des produits pour lesquels le jeton est valide et tous les attributs personnalisés associés au jeton. Les invocations ultérieures de OAuthV2/VerifyAccessToken jusqu'à l'expiration du TTL liront le résultat mis en cache en mémoire, ce qui signifie que la validation du jeton sera beaucoup plus rapide.

La valeur TTL par défaut du cache du jeton d'accès est de 180 secondes. Cet élément vous permet de réduire ce TTL, en échange de performances plus correctes. Cela peut être utile si vous révoquez parfois des jetons et que vous souhaitez réduire la période pendant laquelle Apigee continuera de traiter les jetons révoqués comme valides.

La plage acceptée est comprise entre 1 et 180 secondes. Vous pouvez fournir une variable de flux et une valeur par défaut. Si vous fournissez une variable de flux et qu'elle contient une valeur numérique, elle est prioritaire sur la valeur par défaut spécifiée.

Attributs

Le tableau suivant décrit les attributs de l'élément <CacheExpiryInSeconds>

É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 Obtenir des jetons OAuth 2.0.

É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 Obtenir des jetons OAuth 2.0.

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

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

É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 ou si l'attribut enabled est omis, 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"
}

S'il est défini sur false ou si l'élément <GenerateResponse> est omis, 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 Obtenir des jetons OAuth 2.0.

É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 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 Obtenir des jetons OAuth 2.0.

<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 jeton OAuth JWT.

<PublicKey>/<Value>

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

Spécifie la clé publique ou le certificat public utilisé pour valider la signature d'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.

É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 Obtenir des jetons OAuth 2.0.

É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 Obtenir des jetons OAuth 2.0.

É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 la valeur par défaut.

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

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

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

É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 Obtenir des jetons OAuth 2.0.

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

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

<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. N'utilisez ce paramètre que lorsque la valeur de 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 jeton 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.

É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 Utiliser les champs d'application OAuth2 et Obtenir des jetons OAuth 2.0.

É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 Obtenir des jetons OAuth 2.0.

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

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

É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 Obtenir des jetons OAuth 2.0.

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 Vérifier les jetons d'accès et Obtenir des jetons OAuth 2.0.

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

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

Variables spécifiques à l'AppGroup

Les variables de flux suivantes contenant des informations sur le AppGroup pour le jeton sont renseignées par la règle. Ces attributs AppGroup ne sont renseignés que si verifyapikey.{policy_name}.app.appType est "AppGroup".

Variables spécifiques au développeur

Si l'élément app.appType est "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 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.

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

Les codes d'erreur et les descriptions d'exécution pour les flux de jetons d'authentification JWT dépendent du contexte du flux OAuth2 :

• Si le contexte du flux est la génération ou l'actualisation de jetons, consultez la section Codes d'erreur pour la génération et l'actualisation des jetons JWT ci-dessous.
• Pour le flux de vérification des jetons, consultez la section Codes d'erreur pour les flux de vérification des jetons ci-dessous.

Codes d'erreur pour les flux de génération et d'actualisation des jetons JWT

Pour les flux OAuth2 qui génèrent ou actualisent des jetons JWT, les réponses d'erreur se conforment aux 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 listés dans le tableau suivant ne s'appliquent qu'à l'opération VerifyAccessToken.

Erreurs de déploiement

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

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.

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>

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

Si vous utilisez Apigee hybrid ou Apigee, 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).

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.

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