Présentation de l'authentification des API basée sur IAM

Cette page s'applique à Apigee, mais pas à Apigee hybrid.

Apigee est compatible avec l'authentification et l'autorisation basées sur IAM pour les proxys d'API. Avec cette solution, l'accès permettant d'appeler une API repose sur plusieurs facteurs, y compris si le flux de requêtes inclut la règle VerifyIAM et si le consommateur de l'API dispose du rôle ou des autorisations Google Cloud IAM nécessaires pour appeler les API Apigee. L'autorisation peut être accordée à n'importe quel compte principal Google Cloud et n'est pas limitée aux utilisateurs individuels.

Utiliser le contrôle des accès basé sur IAM

Cette section décrit le processus de bout en bout pour configurer l'authentification et l'autorisation basées sur IAM, comment les requêtes sont évaluées une fois l'accès configuré et comment révoquer l'accès pour les consommateurs d'API qui y avaient déjà accès.

Ajouter la gestion des accès

Pour configurer la gestion des accès pour un proxy d'API :

  1. Ajoutez la règle VerifyIAM au proxy d'API Apigee ou aux proxys dans le cadre du flux de requêtes.
  2. L'administrateur Cloud du projet Apigee :
    1. Attribue le rôle IAM deploymentInvoker (ou un rôle personnalisé avec l'autorisation IAM apigee.deployments.invoke) au compte principal Google Cloud du consommateur d'API au niveau du projet. Le consommateur d'API peut ainsi appeler toutes les API hébergées dans l'organisation Apigee associée.

      ou

    2. Utilise l'action SetIamPolicy pour accorder le rôle ou l'autorisation au compte principal Google Cloud du consommateur d'API pour un déploiement particulier ou de manière itérative pour plusieurs déploiements. Utilisez l'opération de liste sur la ressource de déploiement pour afficher tous les déploiements d'un environnement, y compris les proxys d'API et les flux partagés. Le nom du déploiement correspond au nom du proxy d'API ou du flux partagé.
  3. Demandez au consommateur de l'API de générer un jeton d'accès, qu'il transmettra dans la requête de l'API Apigee pour la vérification des autorisations. Le jeton généré doit avoir le niveau d'accès https://www.googleapis.com/auth/cloud-platform.

Opérations d'administration

Cette section présente les actions que les administrateurs d'API (producteurs d'API) effectuent pour gérer les autorisations basées sur IAM.

La documentation sur les opérations basées sur l'API utilisées pour gérer l'accès basé sur IAM se trouve dans la documentation de référence des API organizations.environments et organizations.environments.deployments. Elle inclut les opérations SetIamPolicy, GetIamPolicy, TestIamPermissions et GetDeployment.

Ce tableau met en correspondance les opérations avec les autorisations requises :

Opération admin : Action Autorisation IAM requise Ressource IAM pour laquelle l'autorisation est requise*
GetDeployment Récupérer des informations sur un déploiement dans un environnement Apigee apigee.deployments.get Projet Google Cloud ou environnement Apigee
ListDeployments Lister les déploiements dans un environnement Apigee apigee.deployments.list Projet ou environnement Apigee
SetIamPolicy Définir l'accès à l'appel pour un ou plusieurs consommateurs d'API dans un déploiement d'API spécifique apigee.deployments.setIamPolicy Projet Google Cloud ou environnement Apigee
GetIamPolicy Récupérer l'ensemble des paramètres d'accès à l'appel pour un déploiement d'API apigee.deployments.getIamPolicy Projet Google Cloud ou environnement Apigee
TestIamPermissions Vérifier si l'utilisateur qui appelle cette API dispose de l'autorisation mentionnée dans la charge utile Aucune autorisation IAM requise N/A
* Le projet Google Cloud est le projet utilisé pour provisionner Apigee. Les autorisations au niveau de l'environnement Apigee sont définies sur l'environnement à l'aide de setIAMPolicy.

Vérification de l'accès à l'environnement d'exécution

Lorsque le consommateur d'API tente d'accéder à une API avec un contrôle des accès basé sur IAM, une vérification est effectuée pour déterminer s'il dispose du jeton d'accès nécessaire et du rôle ou de l'autorisation appropriés au niveau du projet ou du déploiement. Si tel est le cas, il peut continuer à accéder au proxy. Dans le cas contraire, ils sont bloqués.

Supprimer l'accès

Pour supprimer l'accès au niveau du projet : pour supprimer l'accès d'un consommateur d'API géré au niveau du projet, l'administrateur Cloud du projet Apigee révoque le rôle IAM deploymentInvoker (ou le rôle personnalisé avec l'autorisation IAM apigee.deployments.invoke) du compte principal Google Cloud du consommateur d'API pour le projet Google Cloud.

Si l'accès a été accordé pour des déploiements individuels à l'aide de setIamPolicy, supprimez le rôle ou l'autorisation du ou des déploiements à l'aide d'une autre opération setIamPolicy.

Caractéristiques et limites du contrôle des accès basé sur IAM

Notez les caractéristiques et les limites suivantes lorsque vous utilisez l'authentification et l'autorisation basées sur IAM :

  • En règle générale, l'exécution des règles avec VerifyIAM prend environ 10 millisecondes. Toutefois, certains appels peuvent présenter des latences d'environ 50 ms. Par exemple, dans la région asia-east2, la latence moyenne peut atteindre 50 ms, et certains appels peuvent prendre environ 100 ms.

    Veuillez noter que ces chiffres de latence ne sont pas garantis.
  • L'inclusion de la règle VerifyIAM pour un proxy est une vérification "validée/non validée" uniquement. Les rôles et autorisations spécifiques du consommateur d'API ne sont pas pris en compte dans les processus ultérieurs du flux de requête ou de réponse.
  • Étant donné qu'une vérification d'autorisation n'est effectuée qu'au moment de l'exécution de la règle VerifyIAM, VerifyIAM doit être la première règle du flux de requêtes, après les règles de gestion du trafic uniquement.
  • Si la validation des autorisations aboutit ou si le producteur de l'API a marqué la règle VerifyIAM pour qu'elle continue en cas d'erreur, le flux de requête continue à exécuter les autres règles, le cas échéant, jusqu'à atteindre le serveur cible. Si la vérification des autorisations échoue et que le producteur d'API n'a pas marqué la règle pour qu'elle continue en cas d'erreur, l'utilisateur reçoit une erreur.
  • L'ajout d'un accès à l'appel (apigee.deployments.invoke) au niveau de l'environnement ne transmet pas l'accès à l'appel sur tous les déploiements d'API dans l'environnement.
  • Les conditions IAM ne sont pas compatibles avec la ressource de déploiement et ne peuvent pas être utilisées pour contrôler l'accès à l'appel. Pour en savoir plus, consultez Ajouter des conditions IAM Apigee aux stratégies.
  • Le contrôle des accès basé sur IAM accepte un maximum de 1 500 liaisons de rôle dans une même règle, et d'autres limites s'appliquent. Consultez la page Quotas et limites d'IAM.
  • Le contrôle des accès basé sur IAM est soumis à des délais de propagation IAM.
  • Toute tentative de gestion d'autres opérations apigee.deployments, telles que apigee.deployments.delete via l'élément setIAMPolicy au niveau du déploiement, ne sera pas efficace, mais ne renverra pas d'erreur. Seul apigee.deployements.invoke est efficace.
  • L'accès à un déploiement est supprimé lorsque le proxy correspondant est désinstallé de l'environnement ou supprimé. L'accès doit être ajouté à nouveau lors du redéploiement.
  • L'authentification et l'autorisation basées sur IAM ne sont pas disponibles dans le mode hybride pour le moment.

Exemples

Cette section fournit des exemples d'attribution et de révocation d'accès aux API basé sur IAM. Ces exemples supposent tous que VerifyIAM a déjà été ajouté au proxy d'API approprié.

Dans ces exemples, utilisez la console Cloud ou gcloud (affiché) pour gérer les rôles ou les autorisations du compte principal Google Cloud du consommateur d'API. Dans les exemples, $Project correspond au projet Google Cloud.

Accorder et révoquer l'accès des utilisateurs pour appeler toutes les API dans une organisation Apigee

Pour ajouter un accès, ajoutez le rôle deploymentInvoker :

gcloud projects add-iam-policy-binding {$Project} --member={$user} --role='roles/apigee.deploymentInvoker'

Pour révoquer l'accès, supprimez le rôle deploymentInvoker :

gcloud projects remove-iam-policy-binding {$Project} --member={$user} --role='roles/apigee.deploymentInvoker'

Accorder et révoquer l'accès des utilisateurs à des déploiements spécifiques dans un environnement

Pour ajouter le rôle d'appelant à un utilisateur pour un déploiement spécifique :

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:setIamPolicy' \
    --header 'Authorization: Bearer $TOKEN ' \
    --header 'Content-Type: application/json' \
    --data '{"policy":{"bindings":[{"members":["user:$user"],"role":"roles/apigee.deploymentInvoker"}]}}'

Une réponse indiquant un succès devrait se présenter comme suit :

  {
    "version": 1,
    "etag": "BwYT8i40Vwo=",
    "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:$user"
        ]
      }
    ]
  }

Pour vérifier que l'objet de règle que vous avez ajouté est conservé correctement (facultatif) :

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:getIamPolicy' \
  --header 'Authorization: Bearer $TOKEN'

Vous devriez obtenir une réponse positive semblable à celle présentée ci-dessus.

Pour que l'utilisateur puisse vérifier s'il peut accéder au déploiement spécifié (si l'autorisation apigee.deployments.invoke est définie pour l'utilisateur spécifié dans un déploiement spécifié), demandez-lui d'envoyer cette requête à l'aide du jeton d'accès qu'il a généré précédemment :

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:testIamPermissions' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"permissions":["apigee.deployments.invoke"]}'

La réponse doit inclure l'autorisation apigee.deployments.invoke pour l'utilisateur.

Pour révoquer l'accès à un déploiement spécifique, supprimez le rôle deploymentInvoker. Tout d'abord, récupérez l'objet de règle actuellement associé au déploiement : 

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:getIamPolicy' \
  --header 'Authorization: Bearer $TOKEN'

La réponse doit en principe ressembler à ceci : Notez que d'autres liaisons peuvent également s'afficher.

{
  "version": 1,
  "etag": "BwYT8i40Vwo=",
  "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:$user"
        ]
      }
    ]
  }

Pour supprimer la liaison :

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:setIamPolicy' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{}'

Notez que la fourniture d'une charge utile vide supprime l'accès pour tous les utilisateurs, mais cela est approprié dans cet exemple, car nous n'avons qu'un seul utilisateur ayant accès. Lorsque vous supprimez l'accès d'un utilisateur dans une situation où l'accès doit être conservé pour d'autres utilisateurs, spécifiez les utilisateurs qui doivent continuer à avoir accès à la ressource dans la charge utile, comme vous le feriez lorsque vous définissez l'accès initial pour ces utilisateurs.

Pour vérifier que la liaison a bien été supprimée, assurez-vous que l'autorisation apigee.deployments.invoke n'existe pas pour l'utilisateur sur le déploiement :

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:testIamPermissions' \
  --header 'Authorization: Bearer $USER_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"permissions":["apigee.deployments.invoke"]}'

Si aucun utilisateur ne dispose de cette autorisation, la sortie doit être vide.