Personnaliser des jetons et des codes d'autorisation

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

À propos des métadonnées de jeton

Apigee Edge génère des jetons d'accès OAuth, des jetons d'actualisation et des codes d'autorisation, et les distribue aux applications authentifiées. Au moment de la génération, Edge stocke ces jetons et ces codes. Plus tard, lorsque Edge recevra des requêtes API entrantes contenant ces jetons ou codes, Edge utilisera les informations stockées pour autoriser les requêtes.

Lorsque Edge génère ces artefacts OAuth, il associe également des métadonnées au jeton ou au code. Par exemple, un jeton d'accès est associé à des paires nom/valeur qui définissent le délai d'expiration, l'application et le développeur associés, ainsi que d'autres informations.

La représentation JSON d'un jeton d'accès Edge se présente comme suit :

{
  "issued_at" : "1372170159093",
  "application_name" : "ccd1803b-b557-4520-bd62-ddd3abf8e501",
  "scope" : "READ",
  "status" : "approved",
  "api_product_list" : "[Product1,Product2]",
  "api_product_list_json" : ["Product1", "Product2"],
  "expires_in" : "3599", //--in seconds
  "developer.email" : "joe@weathersample.com",
  "organization_id" : "0",
  "refresh_token" : "82XMXgDyHTpFyXOaApj8C2AGIPnN2IZe",
  "client_id" : "deAVedE0W9Z9U35PAMaAJYphBJCGdrND",
  "access_token" : "shTUmeI1geSKin0TODcGLXBNe9vp",
  "organization_name" : "apifactory",
  "refresh_count" : "0"
}

Ajouter des attributs personnalisés aux jetons OAuth

Il est parfois utile d'associer des métadonnées personnalisées à un jeton d'accès. Par exemple, il est possible que vous souhaitiez ajouter un nom d'utilisateur, des appartenances à des groupes ou des rôles pour un utilisateur, un ID client, un identifiant de session ou d'autres informations quelconques à un jeton. Dans Apigee Edge, ces données sont appelées "attributs personnalisés". Par la suite, lorsque le jeton est vérifié dans le champ d'application d'une requête API, ces données sont mises à la disposition du proxy d'API via des variables de contexte. Un proxy d'API peut prendre des décisions précises concernant les autorisations ou le routage en fonction des données personnalisées associées au jeton.

Pour associer des données arbitraires à un jeton, utilisez l'élément <Attributes> dans la règle OAuthV2. Vous pouvez spécifier le nom de l'attribut personnalisé et la valeur que cet attribut doit avoir. Par exemple, voici une configuration de règle qui génère un jeton et associe un attribut personnalisé appelé "tenant_list" au jeton :

<OAuthV2 name="GenerateAccessToken">
  <Operation>GenerateAccessToken</Operation>
  <ExpiresIn>600000</ExpiresIn>
  <GenerateResponse />
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <Attributes> 
    <Attribute name="tenant_list" ref="tenant_list_retrieved_from_external_service" display="false"/>
  </Attributes>
</OAuthV2>

Vous pouvez spécifier plusieurs attributs personnalisés et les associer implicitement à un code d'autorisation (<Operation>GenerateAuthorizationCode</Operation>) ou à un jeton (<Operation>GenerateAccessToken</Operation>) au moment de la génération.

Lorsque display est défini sur true (valeur par défaut), les attributs personnalisés sont renvoyés dans la réponse, où ils peuvent être visibles par l'application ou transmis à l'utilisateur final. Lorsque display est défini sur false, les attributs personnalisés sont stockés dans le datastore, mais ne sont pas renvoyés dans le message de réponse. Dans les deux cas, les données personnalisées sont disponibles pour les règles dans le proxy d'API, une fois le jeton validé.

Pour plus d'informations sur l'option display, consultez la section Afficher ou masquer des attributs personnalisés dans la réponse.

Obtenir des attributs personnalisés lors de l'exécution

Lorsqu'il existe un appel à OAuthV2/VerifyAccessToken, Apigee Edge vérifie le jeton en le recherchant dans le magasin de jetons. Apigee Edge insère alors un ensemble de variables de contexte contenant des informations sur le jeton. y compris :

  • organization_name
  • developer.id
  • developer.app.name
  • client_id
  • grant_type
  • token_type
  • access_token
  • issued_at
  • expires_in //--in seconds
  • état
  • champ d'application
  • apiproduct.name*

Si le jeton contient des attributs personnalisés, ceux-ci sont mis à disposition dans une variable de contexte nommée accesstoken.{custom_attribute}. Par exemple, supposons qu'un jeton soit émis à partir de la règle présentée ci-dessus. Après vérification de ce type de jeton, une variable de contexte supplémentaire nommée accesstoken.tenant_list devrait apparaître, contenant la valeur qui a été stockée lors de la génération du jeton.

Les règles ou les conditions peuvent ensuite faire référence à ces variables et modifier le comportement en fonction des valeurs qu'elles contiennent.

Définir et mettre à jour des attributs personnalisés lors de l'exécution

Dans certains cas, vous voudrez que votre proxy d'API mette à jour les métadonnées associées à un jeton d'accès au moment de l'exécution pendant le traitement d'un appel d'API sur Apigee Edge. Pour vous aider, Apigee fournit des règles permettant d'obtenir et de définir des attributs de jeton. Pour en savoir plus, consultez les pages Obtenir la règle d'information OAuth V2 et Définir la règle d'informations OAuth V2.

Dans chacune de ces règles, l'élément AccessToken doit faire référence à une variable qui contient le jeton d'accès.

Vous pouvez également utiliser les API Edge pour mettre à jour les attributs personnalisés attachés à un jeton. Consultez la documentation de l'API pour découvrir la méthode permettant de mettre à jour le jeton d'accès OAuth 2.0.