Activer la récupération et la révocation des jetons d'accès OAuth 2.0 par ID utilisateur final, par identifiant d'application ou les deux

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

Cette section explique comment activer la récupération et la révocation des jetons d'accès OAuth 2.0 par ID d'utilisateur final, par ID d'application ou les deux. La fonctionnalité ID de l'utilisateur final nécessite une configuration spéciale, comme décrit dans cet article. Par "utilisateur final", nous entendons l'utilisateur de l'application qui appelle l'API.

Quand activer l'accès à l'ID d'utilisateur final

Il est parfois utile de stocker l'ID utilisateur dans un jeton d'accès. N'activez la fonctionnalité d'accès à l'ID utilisateur final que si elle est adaptée à votre cas d'utilisation. Exemple :

  • Une fonctionnalité de votre site Web ou de votre application permettant aux utilisateurs de voir les applications tierces autorisées et de leur offrir la possibilité de révoquer l'accès à ces applications.
  • Une fonctionnalité permettant à un utilisateur autorisé de révoquer tous les jetons d'accès associés à une application de développeur spécifique.

À propos des jetons d'accès OAuth

Les ID d'application sont automatiquement ajoutés à un jeton d'accès OAuth. Par conséquent, après avoir activé l'accès par jeton pour une organisation comme décrit ci-dessous, vous pouvez révoquer les jetons d'accès par ID d'application.

Pour pouvoir récupérer et révoquer des jetons d'accès OAuth 2.0 par ID d'utilisateur final, celui-ci doit être présent dans les jetons d'accès. La procédure ci-dessous explique comment ajouter un ID d'utilisateur final à un jeton existant.

Par défaut, lorsque Edge génère un jeton d'accès OAuth 2.0, le jeton a le format indiqué ci-dessous:

{
 "issued_at" : "1421847736581",
 "application_name" : "a68d01f8-b15c-4be3-b800-ceae8c456f5a",
 "scope" : "READ",
 "status" : "approved",
 "api_product_list" : "[PremiumWeatherAPI]",
 "expires_in" : "3599", //--in seconds
 "developer.email" : "tesla@weathersample.com",
 "organization_id" : "0",
 "token_type" : "BearerToken",
 "client_id" : "k3nJyFJIA3p62DWOkLO6OJNi87GYXFmP",
 "access_token" : "7S22UqXGJDTuUADGzJzjXzXSaGJL",
 "organization_name" : "myorg",
 "refresh_token_expires_in" : "0", //--in seconds
 "refresh_count" : "0"
}

Veuillez noter les points suivants :

  • Le champ application_name contient l'UUID de l'application associée au jeton. Si vous activez la récupération et la révocation des jetons d'accès OAuth 2.0 par ID d'application, il s'agit de l'ID d'application que vous utilisez.
  • Le champ access_token contient la valeur du jeton d'accès OAuth 2.0.

Il n'y a pas de champ d'ID d'utilisateur final dans le jeton d'accès OAuth par défaut. Pour activer la récupération et la révocation des jetons d'accès OAuth 2.0 par ID d'utilisateur final, vous devez configurer la règle OAuth 2.0 de manière à inclure l'ID utilisateur dans le jeton, comme décrit dans la procédure ci-dessous. Notez que si vous souhaitez uniquement récupérer et révoquer les jetons d'accès OAuth 2.0 par ID d'application, il n'est pas nécessaire d'activer l'accès par ID d'utilisateur final.

Vous transmettez l'ID utilisateur final au point de terminaison de création du jeton. Vous pouvez transmettre l'ID de l'utilisateur final en tant que paramètre de requête, de formulaire ou dans un en-tête (comme expliqué plus loin dans cet article). Une fois que vous avez configuré Edge pour inclure l'ID d'utilisateur final dans le jeton, celui-ci est inclus en tant que champ app_enduser, comme indiqué ci-dessous:

{
 "issued_at" : "1421847736581",
 "application_name" : "a68d01f8-b15c-4be3-b800-ceae8c456f5a",
 "scope" : "READ",
 "app_enduser" : "6ZG094fgnjNf02EK",
 "status" : "approved",
 "api_product_list" : "[PremiumWeatherAPI]",
 "expires_in" : "3599", //--in seconds
 "developer.email" : "tesla@weathersample.com",
 "organization_id" : "0",
 "token_type" : "BearerToken",
 "client_id" : "k3nJyFJIA3p62DWOkLO6OJNi87GYXFmP",
 "access_token" : "7S22UqXGJDTuUADGzJzjXzXSaGJL",
 "organization_name" : "myorg",
 "refresh_token_expires_in" : "0", //--in seconds
 "refresh_count" : "0"
}

Pour savoir comment effectuer les appels d'API qui effectuent ces récupérations et révocations, consultez les Smart Docs suivants :

Activer l'accès aux jetons OAuth 2.0 par ID d'utilisateur et ID d'application

La manière dont vous activez l'accès aux jetons OAuth 2.0 par ID utilisateur et par ID d'application dépend de la manière dont vous avez déployé Edge:

  • Déploiement dans le cloud

    Le déploiement d'Edge dans le cloud signifie que la majeure partie de la configuration est gérée par Apigee. Vous êtes seulement responsable de la configuration de la règle OAuth 2.0 pour ajouter l'ID utilisateur au jeton d'accès. Pour en savoir plus, consultez la procédure ci-dessous.

  • Edge pour le déploiement de cloud privé

    Dans Apigee Edge pour Private Cloud (sur site), vous êtes entièrement responsable de la configuration. Pour en savoir plus, consultez la section Opérations et configuration.

  • Apigee hybrid

    L'accès aux jetons OAuth 2.0 par ID utilisateur est activé par défaut. Vous êtes seulement responsable de la configuration de la règle OAuth 2.0 pour ajouter l'ID utilisateur au jeton d'accès. Pour en savoir plus, consultez l'étape 5 de la procédure ci-dessous.

Permettre l'accès dans le cloud

Étape 1 : Activez une organisation pour permettre la compatibilité avec cette fonctionnalité

Cette fonctionnalité doit être activée pour chaque organisation pour laquelle vous souhaitez l'utiliser.

Contactez l'assistance Apigee Edge pour lui demander de mettre à jour votre organisation.

Étape 2 : Accordez les autorisations de ressource oauth2 aux rôles opsadmin et orgadmin

Seuls vos rôles orgadmin et opsadmin rôles doivent être autorisés à effectuer ces appels de récupération (get) et de révocation (put) à la ressource oauth2 basée sur l'ID de l'utilisateur final ou sur l'ID de l'application.

Vous pouvez utiliser l'appel d'API Obtenir l'autorisation pour une ressource pour voir quels rôles disposent des autorisations get et put pour la ressource oauth2.

Si vous devez ajouter ou supprimer des autorisations, contactez l'assistance Apigee Edge pour qu'elle effectue les mises à jour.

Étape 3 : Copiez des jetons d'accès OAuth 2.0 existants sur vos nœuds Cassandra

Géré par l'assistance Apigee : dans cette tâche, les copies de jetons d'accès OAuth 2.0 existants dans des organisations concernées seront copiées et stockées dans vos nœuds Cassandra. Cette procédure sera effectuée sur les nœuds Cassandra de chacun de vos pods Apigee Edge. Cela permettra aux requêtes d'API de récupérer et de révoquer les appels d'API sur tous vos jetons d'accès OAuth 2.0, existants et nouvellement générés.

Étape 4: Ajoutez la propriété oauth_max_search_limit à votre serveur de gestion et à votre processeur de messages

Dans cette tâche, les fichiers keymanagement.properties de votre serveur de gestion et de votre outil de traitement des messages seront mis à jour pour inclure cette propriété: oauth_max_search_limit = 100. 100 est la valeur recommandée pour Apigee, mais vous pouvez la définir comme vous le souhaitez.

Contactez l'assistance Apigee Edge pour lui demander d'effectuer cet ajout.

Étape 5: Configurez une règle OAuth 2.0 pour générer des jetons d'accès incluant les ID d'utilisateurs finaux

Configurez la règle OAuth 2.0 utilisée pour générer des jetons d'accès afin d'inclure l'ID utilisateur final dans le jeton. En incluant les ID utilisateur finaux dans les jetons d'accès, vous pouvez effectuer des récupérations et des révocations par ID d'utilisateur.

Pour configurer la règle de manière à inclure un ID utilisateur final dans un jeton d'accès, vous devez spécifier la variable d'entrée qui contient l'ID utilisateur final. Utilisez la balise <AppEndUser> pour spécifier la variable.

La stratégie OAuth 2.0 ci-dessous, nommée GenerateAccessTokenClient, génère un jeton d'accès OAuth 2.0. Notez l'ajout de la balise <AppEndUser> en gras :

<OAuthV2 async="false" continueOnError="false" enabled="true" name="GenerateAccessTokenClient">
  <DisplayName>OAuth 2.0.0 1</DisplayName>
  <ExternalAuthorization>false</ExternalAuthorization>
  <Operation>GenerateAccessToken</Operation>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
  <GrantType>request.queryparam.grant_type</GrantType>
  <AppEndUser>request.header.appuserID</AppEndUser>
  <ExpiresIn>960000</ExpiresIn>
</OAuthV2>

Vous pouvez ensuite utiliser la commande cURL suivante pour générer le jeton d'accès OAuth 2.0, en transmettant l'ID utilisateur en tant qu'en-tête appuserID :

curl -H "appuserID:6ZG094fgnjNf02EK" /
  https://myorg-test.apigee.net/oauth/client_credential/accesstoken?grant_type=client_credentials /
  -X POST /
  -d 'client_id=k3nJyFJIA3p62TKIkLO6OJNi87GYXFmP&client_secret=gk58jK5lIp943AY4'

Dans cet exemple, le appuserID est transmis en tant qu'en-tête de requête. Vous pouvez transmettre des informations dans une requête de différentes manières. Par exemple, vous pouvez également :

  • Utiliser une variable de paramètre de formulaire : request.formparam.appuserID.
  • Utiliser une variable de flux fournissant l'ID d'utilisateur final