Personnaliser des jetons et des codes d'autorisation

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

Consultez la documentation d'Apigee Edge.

À propos des métadonnées de jeton et de code d'autorisation

Apigee 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. Apigee stocke ces jetons et codes lors de la génération. Ensuite, lorsque Apigee reçoit des requêtes API entrantes comportant ces jetons ou codes, Apigee utilise les informations stockées pour autoriser les requêtes.

Lorsqu'Apigee génère ces artefacts OAuth, il joint é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 Apigee 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 et aux codes d'autorisation

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, 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 et la valeur de l'attribut personnalisé. 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 de jeton d'accès personnalisés lors de l'exécution

Lorsqu'il existe un appel à OAuthV2/VerifyAccessToken, Apigee vérifie le jeton en le recherchant dans le magasin de jetons. Apigee 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 Dans # secondes
status
scope
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. 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.