S'authentifier avec des identités de service

Dans Google Distributed Cloud (GDC) air-gapped, une identité de service fournit une identité dédiée aux charges de travail ou aux services pour accéder de manière programmatique aux ressources et aux microservices de manière sécurisée. Il s'agit d'identités spéciales utilisées par des applications ou des charges de travail, et non par une personne. Elles ne peuvent pas être utilisées pour la connexion humaine. Comme pour les comptes utilisateur, vous accordez des autorisations et des rôles à une identité de service pour définir ce à quoi elle est autorisée à accéder.

Vous remarquerez peut-être que deux termes sont utilisés pour ce concept. La console GDC utilise principalement le terme "identité de service", tandis que les commandes gdcloud et les interactions avec l'API utilisent souvent le terme "compte de service". Ce dernier reflète le nom de la ressource personnalisée Kubernetes sous-jacente, ProjectServiceAccount. Les deux termes désignent la même chose : l'identité non humaine de vos charges de travail. Ce document utilise l'identité de service comme terme principal.

Les identités de service sont utiles pour gérer l'infrastructure GDC, par exemple :

• Services et charges de travail Distributed Cloud internes pour accéder de manière sécurisée à l'interface de programmation d'application (API) du plan de contrôle Distributed Cloud. Par exemple, les services de base de données interagissent avec les API Kubernetes pour créer et supprimer des bases de données.
• Les charges de travail des clients dans Distributed Cloud pour accéder aux services Distributed Cloud et effectuer des appels d'interface de programmation d'application (API) autorisés. Par exemple, les identités de service peuvent gérer un client à l'aide d'un notebook Vertex AI Workbench pour transcrire des fichiers audio à l'aide de l'API Speech-to-Text.
• Charges de travail externes à fédérer avec Distributed Cloud. Par exemple, les identités de service peuvent gérer une application externe à Distributed Cloud qui numérise des documents, mais qui souhaite utiliser l'API Optical Character Recognition (OCR) pour remplacer son moteur OCR actuel.
• Services Distributed Cloud ou contrôleurs système pour accéder de manière sécurisée aux ressources client ou aux clusters d'utilisateur. Par exemple, les identités de service peuvent gérer les workflows d'authentification et d'autorisation lorsque les contrôleurs de service exécutés dans les clusters d'administrateur doivent exécuter des charges de travail dans les clusters d'utilisateur gérés par les clients.

Vous pouvez gérer les comptes pour les identités de service à l'aide de la console GDC, de la CLI gdcloud ou de l'API. Avec la gcloud CLI, la fonctionnalité d'identité de service est basée sur l'API ProjectServiceAccount globale. Étant donné que les ressources ProjectServiceAccount sont configurées globalement, elles fonctionnent dans toutes les zones de votre univers gdcloud.

Avant de commencer

Vous ne pouvez créer une identité de service que dans un projet. Pour savoir comment créer un projet, consultez Créer un projet.

La gestion des identités de service implique à la fois l'identité de service (représentée par une ressource ProjectServiceAccount) et ses identifiants associés (paires de clés publiques et privées). Pour obtenir les autorisations nécessaires pour gérer les identités de service et leurs identifiants, demandez à votre administrateur IAM de l'organisation ou du projet de vous accorder le rôle Administrateur IAM du projet (project-iam-admin) dans ce projet.

Remarque : Les utilisateurs disposant du rôle Administrateur IAM du projet peuvent accéder à toutes les identités de service du projet. Cela inclut la gestion des ressources ProjectServiceAccount et de leurs clés publiques associées.

Créer une identité de service

La création d'une identité de service inclut la création d'un compte et de ses identifiants associés.

Créer un compte

Pour créer un compte pour une identité de service, utilisez la console GDC, la CLI gdcloud ou l'API pour créer une ressource ProjectServiceAccount dans un projet.

Console

1. Connectez-vous à la console GDC.
2. Dans le menu de navigation, sélectionnez Identité et accès > Identités de service.
3. Cliquez sur Créer une identité de service. La page Informations sur l'identité du service s'ouvre.
4. Dans le champ Nom de l'identité du service, saisissez le nom de l'identité de votre service. Exemple : testserviceidentity.
5. Cliquez sur Créer.

gdcloud

Créez un compte :

gdcloud iam service-accounts create NAME \
    --project=PROJECT

Remplacez les valeurs suivantes :

• NAME : nom du ProjectServiceAccount. Le nom doit être unique dans l'espace de noms du projet.
• PROJECT : projet dans lequel créer l'identité de service. Si gdcloud init est déjà défini, omettez l'option --project.

Cette commande crée un ProjectServiceAccount dans l'espace de noms du projet sur le serveur de l'API Management.

API

1. Créez un fichier YAML de ressource personnalisée ProjectServiceAccount, tel que my-project-sa.yaml :

   apiVersion: resourcemanager.global.gdc.goog/v1
   kind: ProjectServiceAccount
   metadata:
     name: NAME
     namespace: PROJECT
   spec:
     keys:
     - algorithm: ALGORITHM
     id: KEY_ID
     key: BASE64_ENCODED_KEY
     validAfter: "START_TIME"
     validBefore: "EXPIRATION_TIME"
   

   Remplacez les variables suivantes :

   • NAME : nom de la ressource ProjectServiceAccount. Le nom doit être unique dans l'espace de noms du projet.
   • PROJECT : projet dans lequel créer l'identité de service.
   • ALGORITHM : algorithme de la clé. Seules les clés ES256 sont acceptées.
   • KEY_ID : identifiant unique de la clé. L'ID permet de déterminer la clé à valider.
   • BASE64_ENCODED_KEY : clé publique encodée en base64 au format PEM à vérifier. La clé privée utilisée pour générer cette clé publique est attendue au format PEM ECDSA P256.
   • START_TIME : heure de début à laquelle la clé devient valide, par exemple 2025-02-07T00:59:34Z.
   • EXPIRATION_TIME : délai d'expiration de la clé, par exemple 2026-02-07T00:59:34Z.

2. Appliquez la ressource personnalisée ProjectServiceAccount au serveur d'API global :

   kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f my-project-sa.yaml
   

   Remplacez la variable GLOBAL_API_SERVER_KUBECONFIG par le chemin d'accès au fichier kubeconfig du serveur d'API mondial.

Créer des identifiants

Pour permettre à une charge de travail ou à une application de s'authentifier en tant qu'identité de service (représentée par le compte que vous avez créé), vous devez générer des identifiants. Pour créer des identifiants, vous devez générer une paire de clés cryptographiques privée et publique, puis associer la clé publique à l'identité du service.

Pour créer des identifiants pour une identité de service, utilisez la console GDC, la gdcloud CLI ou l'API.

Console

1. Connectez-vous à la console GDC.
2. Dans le menu de navigation, sélectionnez Identité et accès > Identités de service.
3. Cliquez sur le nom de l'identité de service que vous souhaitez ajouter à la clé.
4. Cliquez sur  Créer une clé.
5. La nouvelle clé apparaît dans la liste Clés. Une boîte de dialogue confirme que vous avez bien créé la clé.

gdcloud

La commande gdcloud crée un fichier JSON d'identifiants par défaut de l'application ainsi qu'une paire de clés publique et privée :

gdcloud iam service-accounts keys create APPLICATION_DEFAULT_CREDENTIALS_FILENAME \
    --project=PROJECT \
    --iam-account=NAME \
    --ca-cert-path=CA_CERTIFICATE_PATH

Remplacez les valeurs suivantes :

• APPLICATION_DEFAULT_CREDENTIALS_FILENAME : nom du fichier JSON.
• PROJECT : sélectionne le projet pour lequel créer la clé. Si gdcloud init est déjà défini, vous pouvez omettre l'option --project.
• NAME : nom de l'identité de service pour laquelle ajouter la clé.
• CA_CERTIFICATE_PATH : (facultatif) chemin d'accès au certificat de l'autorité de certification (CA) pour valider le point de terminaison d'authentification. Si vous ne spécifiez pas ce chemin, les certificats CA du système sont utilisés. Vous devez installer l'autorité de certification dans les certificats CA du système.

Distributed Cloud ajoute la clé publique aux clés ProjectServiceAccount que vous utilisez pour valider les jetons Web JSON (JWT) signés par la clé privée. La clé privée est écrite dans le fichier JSON des identifiants par défaut de l'application.

L'exemple suivant montre le fichier JSON des identifiants par défaut de l'application :

{
"type": "gdch_service_account",
"format_version": "1",
"project": "project_name",
"private_key_id": "abcdef1234567890",
"private_key": "-----BEGIN PRIVATE KEY-----\nETC\n-----END PRIVATE KEY-----\n",
"name": "service_identity_name",
"ca_cert_path": "/path/to/ca.crt",
"token_uri": "https://service-identity.<Domain>/authenticate"
}

Cet exemple utilise les valeurs suivantes :

• project : espace de noms du projet dans l'organisation.
• private_key_id : ID attribué à la clé.
• private_key : clé privée ECDSA P256 au format PEM générée par CLI.
• name : nom de l'identité de service.
• ca_cert_path : chemin d'accès au certificat de l'autorité de certification utilisé pour valider le point de terminaison d'authentification.
• token_uri : adresse du point de terminaison d'authentification.

API

1. Générez la paire de clés publique et privée. Les commandes suivantes utilisent openssl comme exemple, car il s'agit d'un outil courant à cet effet.

   openssl ecparam -name prime256v1 -genkey -noout -out "key.pem"
   openssl ec -in "key.pem" -pubout > "pub.pem"
   

2. Encodez la clé publique en base64 et récupérez son ID de clé :

   KEY_ID=$(openssl pkey -in key.pem -pubout -outform der | openssl dgst -sha256 | sed 's/^.* //')
   BASE64_ENCODED_KEY=$(cat pub.pem | base64)
   

3. Créez ou mettez à jour le fichier YAML de la ressource personnalisée ProjectServiceAccount, y compris les informations de clé générées à l'étape précédente :

   apiVersion: resourcemanager.global.gdc.goog/v1
   kind: ProjectServiceAccount
   metadata:
     name: NAME
     namespace: PROJECT
   spec:
     keys:
     - algorithm: ALGORITHM
     id: KEY_ID
     key: BASE64_ENCODED_KEY
     validAfter: "START_TIME"
     validBefore: "EXPIRATION_TIME"
   

   Remplacez les variables suivantes :

   • NAME : nom de la ressource ProjectServiceAccount. Le nom doit être unique dans l'espace de noms du projet.
   • PROJECT : projet dans lequel vous créez la clé.
   • ALGORITHM : algorithme de la clé. Seules les clés ES256 sont acceptées.
   • KEY_ID : identifiant unique de la clé. L'ID permet de déterminer la clé à valider.
   • BASE64_ENCODED_KEY : clé publique encodée en base64 au format PEM à vérifier. La clé privée utilisée pour générer cette clé publique est attendue au format PEM ECDSA P256.
   • START_TIME : heure de début à laquelle la clé devient valide, par exemple 2025-02-07T00:59:34Z.
   • EXPIRATION_TIME : délai d'expiration de la clé, par exemple 2026-02-07T00:59:34Z.

4. Appliquez la ressource personnalisée ProjectServiceAccount au serveur d'API global :

   kubectl --kubeconfig GLOBAL_API_SERVER_KUBECONFIG apply -f my-project-sa.yaml
   

   Remplacez la variable GLOBAL_API_SERVER_KUBECONFIG par le chemin d'accès au fichier kubeconfig du serveur d'API mondial.

5. Créez le fichier JSON contenant les identifiants par défaut de l'application et la clé privée. Assurez-vous que la variable KEY_ID du fichier JSON est définie sur la même valeur que la variable KEY_ID que vous avez utilisée dans la spécification ProjectServiceAccount.

   cat <<EOF > "key_file.json"
   {
     "format_version": "1",
     "name": "NAME",
     "private_key": "$(tr '\n' '\t' < "key.pem" | sed 's/\t/\\n/g')",
     "private_key_id": "KEY_ID",
     "project": "PROJECT",
     "token_uri": "AUTH_URL",
     "type": "gdch_service_account"
   }
   EOF
   

   Remplacez les variables suivantes :

   • NAME : nom de l'identité de service.
   • KEY_ID : identifiant unique de la clé. L'ID permet de déterminer la clé à vérifier. Il doit correspondre à la valeur KEY_ID utilisée dans la spécification ProjectServiceAccount.
   • PROJECT : espace de noms du projet dans l'organisation.
   • AUTH_URL : adresse du point de terminaison d'authentification.

Pour savoir comment utiliser le fichier de clé généré pour authentifier la gcloud CLI en tant qu'identité de service, consultez la section Autoriser une identité de service à l'aide d'une clé.

Afficher les identités de service

Cette section explique comment afficher vos identités de service et les clés publiques associées.

Afficher la liste des identités de service

Pour afficher la liste des identités de service dans un projet, utilisez la console GDC ou la CLI gdcloud.

Console

1. Connectez-vous à la console GDC.
2. Sélectionnez un projet.
3. Dans le menu de navigation, cliquez sur Identité et accès > Identités de service pour afficher la liste des identités de service du projet.

gdcloud

Listez les comptes d'identité de service dans un projet :

gdcloud iam service-accounts list \
    --project=PROJECT

Remplacez PROJECT par l'ID du projet.

Afficher la liste des clés publiques pour une identité de service

Répertoriez les clés publiques enregistrées avec un compte d'identité de service dans le projet :

gdcloud iam service-accounts keys list \
    --project=PROJECT \
    --iam-account=NAME

Remplacez les éléments suivants :

• PROJECT : ID du projet.
• NAME : nom du compte d'identité de service à utiliser.

Accorder des autorisations pour les identités de service

Pour accorder des autorisations à une identité de service, attribuez-lui un ou plusieurs rôles en créant des liaisons de rôle à l'aide de la console GDC ou de la CLI gdcloud.

Console

1. Connectez-vous à la console GDC.
2. Sélectionnez un projet.
3. Dans le menu de navigation, sélectionnez Identité et accès > Accès.
4. Dans la liste Membres, cliquez sur  Ajouter un membre. La page Utilisateurs et rôles s'affiche.
5. Dans la liste Type de membre, sélectionnez Identité de service.
6. Dans la liste Identité de service, sélectionnez l'identité de service à laquelle vous souhaitez attribuer une liaison de rôle.
7. Dans la liste Rôle, sélectionnez le rôle que vous souhaitez attribuer à l'identité de service, par exemple Créateur de sauvegardes.
8. Facultatif : Pour ajouter un autre rôle, cliquez sur Ajouter un autre rôle. Sélectionnez le rôle supplémentaire.
9. Cliquez sur Ajouter.

gdcloud

Vous pouvez associer le compte d'identité de service à des rôles dans l'espace de noms du projet ou à des rôles dans un autre espace de noms.

Remarque : Les indicateurs --project et --role-namespace s'excluent mutuellement. Vous ne pouvez donc utiliser que l'un ou l'autre dans une même commande, et non les deux.

• Associez le compte à un rôle dans l'espace de noms du projet :

  gdcloud iam service-accounts add-iam-policy-binding \
      --project=PROJECT \
      --role=ROLE \
      --iam-account=NAME
  

  Remplacez les éléments suivants :

  • PROJECT : projet dans lequel vous souhaitez créer l'association de rôle. Si gdcloud init est déjà défini, vous pouvez omettre l'option --project.
  • ROLE : rôle prédéfini à attribuer au compte. Spécifiez les rôles au format Role/name, où Role correspond au type Kubernetes IAMRole et name au nom du rôle prédéfini. Par exemple, pour attribuer le rôle de lecteur de projet, définissez le rôle sur IAMRole/project-viewer.
  • NAME : nom du compte d'identité de service à utiliser.

• Associez le compte à un rôle dans un autre espace de noms :

  gdcloud iam service-accounts add-iam-policy-binding \
      --role=ROLE \
      --role-namespace=ROLE_NAMESPACE \
      --iam-account=NAME
  

  Remplacez les éléments suivants :

  • ROLE : rôle prédéfini à attribuer au compte. Spécifiez les rôles au format Role/name, où Role correspond au type Kubernetes IAMRole et name au nom du rôle prédéfini. Par exemple, pour attribuer le rôle de lecteur de projet, définissez le rôle sur IAMRole/project-viewer.
  • ROLE_NAMESPACE : espace de noms du rôle à associer au compte autre que l'espace de noms du projet.
  • NAME : nom du compte d'identité de service à utiliser.

S'authentifier et utiliser une identité de service

Pour configurer gdcloud et d'autres outils afin qu'ils fonctionnent en tant qu'identité de service, vous devez d'abord vous authentifier auprès de gdcloud à l'aide du fichier de clé de l'identité de service. Une fois authentifié, vous pouvez utiliser les identifiants de l'identité du service pour générer des jetons ou des fichiers kubeconfig.

Autoriser une identité de service à l'aide d'une clé

Remarque : Les clés d'identité de service peuvent présenter un risque pour la sécurité si elles ne sont pas gérées avec soin. Pour en savoir plus sur les bonnes pratiques de gestion, d'utilisation et de sécurisation des clés d'identité de service, consultez Sécuriser les clés de compte de service.

La commande gdcloud auth activate-service-account authentifie la CLI gdcloud avec une identité de service. Cela vous permet d'effectuer des actions sur les ressources Distributed Cloud à l'aide des autorisations du compte d'identité de service au lieu d'un compte utilisateur.

Autorisez une identité de service à l'aide d'une clé :

1. Créez un fichier de clé d'identifiants si vous n'en avez pas encore.

2. Activez l'identité de service en exécutant la commande suivante :

   gdcloud auth activate-service-account --key-file=KEY_FILE
   

   Remplacez KEY_FILE par le chemin d'accès au fichier de clé d'identifiant, généralement au format JSON.

   Une fois l'activation réussie, gdcloud utilise les identifiants de l'identité du service au lieu de vos identifiants utilisateur.

Imprimer un jeton d'identité pour l'identité du service

Après avoir autorisé une identité de service, vous pouvez imprimer un jeton d'identité pour celle-ci. Vous pouvez utiliser ce jeton en tant que jeton de support pour authentifier les requêtes HTTP. Cela signifie que le jeton accorde à toute partie en sa possession l'accès aux services définis dans le paramètre AUDIENCES.

Imprimez un jeton d'identité pour le compte d'identité de service spécifié :

gdcloud auth print-identity-token --audiences=AUDIENCES

Remplacez AUDIENCES par le destinataire ou le service auquel le jeton est destiné. Vous ne pouvez spécifier qu'une seule audience.

Générer le fichier kubeconfig

Après avoir autorisé une identité de service, vous pouvez générer un fichier kubeconfig pour vous authentifier auprès des clusters.

1. Définissez la propriété gdcloud core/organization_console_url :

   gdcloud config set core/organization_console_url
   https://GDC_URL
   

   Remplacez GDC_URL par l'URL de votre organisation.

2. Générez le fichier kubeconfig pour accéder à un cluster à l'aide de l'identité de service active :

   • Pour un cluster zonal :

     export KUBECONFIG=KUBECONFIG_PATH
     gdcloud clusters get-credentials CLUSTER_NAME --zone ZONE
     

     Remplacez les éléments suivants :

     • KUBECONFIG_PATH : chemin d'accès où vous souhaitez enregistrer le fichier kubeconfig généré.

     • CLUSTER_NAME : nom du cluster zonal.

       Remarque : La liste des noms de cluster est disponible dans l'URL de configuration de la connexion :
       https://GDC_URL/.well-known/login-config.

     • ZONE : nom de la zone dans laquelle se trouve le cluster.

   • Pour le serveur d'API mondial :

     export KUBECONFIG=KUBECONFIG_PATH
     gdcloud clusters get-credentials global-api
     

     Remplacez KUBECONFIG_PATH par le chemin d'accès où vous souhaitez enregistrer le fichier kubeconfig généré.

Un fichier kubeconfig est généré et configuré pour l'authentification en tant qu'identité de service. Voici un exemple de fichier YAML :

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: <REDACTED>
    server: <REDACTED>
  name: cluster-name
contexts:
- context:
    cluster: cluster-name
    user: gdch_console-<REDACTED>_cluster-name
  name: cluster-name-gdch_console-<REDACTED>_cluster-name
current-context: cluster-name-gdch_console-gdc1-staging-gpcdemolabs-com_cluster-name
kind: Config
preferences: {}
users:
- name: gdch_console-<REDACTED>_cluster-name
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1
      args:
      - --audience=<REDACTED>
      command: gdcloud-k8s-auth-plugin
      env: null
      installHint: Run 'gdcloud components install gdcloud-k8s-auth-plugin' to use
        plugin
      interactiveMode: Never
      provideClusterInfo: false

Supprimer une identité de service

Important : Lorsque vous supprimez une identité de service, les liaisons de rôle associées ne sont pas supprimées automatiquement. Si vous créez une identité de service portant le même nom, elle hérite automatiquement des autorisations de l'identité de service précédemment supprimée. Pour éviter les autorisations orphelines qui peuvent subsister après la suppression d'une identité de service, supprimez d'abord toutes les liaisons de rôle existantes associées à l'identité de service avant de supprimer l'identité de service elle-même.

Lorsque vous supprimez une identité de service, le ProjectServiceAccount et ses clés publiques associées sont supprimés, les clés privées existantes deviennent non valides et les applications n'ont plus accès aux ressources du projet via cette identité de service.

Pour supprimer une identité de service, utilisez la console GDC ou gdcloud CLI.

Console

1. Connectez-vous à la console GDC.
2. Dans le menu de navigation, sélectionnez Identité et accès > Identités de service.
3. Cochez la case correspondant à l'identité de service que vous souhaitez supprimer.
4. Cliquez sur Supprimer.
5. La boîte de dialogue de confirmation s'affiche. Dans le champ Confirmez en saisissant ce qui suit, saisissez remove.
6. Cliquez sur Supprimer.

gdcloud

Exécutez la commande suivante pour supprimer une identité de service :

gdcloud iam service-accounts delete NAME \
    --project=PROJECT

Remplacez les éléments suivants :

• NAME : nom du compte d'identité de service à supprimer.
• PROJECT : ID du projet.

Supprimer les identifiants

Si vous souhaitez désactiver une paire de clés spécifique sans supprimer l'intégralité du compte d'identité de service, vous pouvez supprimer sa clé publique du compte d'identité de service. Cette action invalide la clé privée correspondante.

Remarque : La suppression de la clé publique ne révoque pas les identifiants éphémères émis à l'aide de la clé privée correspondante.

Pour supprimer la clé publique, utilisez la console GDC ou gdcloud CLI.

Console

1. Connectez-vous à la console GDC.
2. Dans le menu de navigation, sélectionnez Identité et accès > Identités de service.
3. Cliquez sur le nom de l'identité de service associée à la clé que vous souhaitez supprimer.
4. Cliquez sur Supprimer.
5. Dans la boîte de dialogue de confirmation, cliquez sur Supprimer.

gdcloud

Supprimez la clé publique avec l'ID de clé d'un compte d'identité de service dans le projet :

gdcloud iam service-accounts keys delete KEY_ID \
    --project=PROJECT \
    --iam-account=NAME

Remplacez les éléments suivants :

• KEY_ID : identifiant unique de la clé.
• PROJECT : ID du projet.
• NAME : nom du compte d'identité de service.