Configurer la fédération des identités des employés (BYOID)

Ce guide explique comment configurer Bring Your Own Identity (BYOID) pour l'API Multi-party Compute à l'aide de la fédération des identités des employés et de la fédération d'identité de charge de travail. Grâce à la fédération d'identité, les utilisateurs humains et les charges de travail de signataire automatisées peuvent s'authentifier auprès du calcul multipartite à l'aide du fournisseur d'identité (IdP) externe de votre organisation, tel qu'Okta, Microsoft Entra ID ou Ping Identity. Vous n'avez pas besoin de créer de comptes Google ni de gérer des clés de compte de service à longue durée de vie.

Présentation

La fédération d'identité s'intègre au modèle de sécurité de défense en profondeur du calcul multipartite sur les couches suivantes :

  1. Autorisation IAM (Identity and Access Management) Edge : les appelants échangent des identifiants d'un IdP OpenID Connect (OIDC) ou SAML 2.0 externe avec le Google Cloud Security Token Service (Security Token Service) pour un jeton d'accès fédéré de courte durée. La passerelle d'API Google Cloud évalue les liaisons de rôles IAM par rapport à l'URI du compte principal fédéré avant de transférer les requêtes à votre instance de calcul multipartite, et propage l'identité fédérée (principalSubject) pour Cloud Audit Logs.
  2. Séparation des tâches et approbation cryptographique : les rôles IAM séparent le provisionnement administratif (roles/mpc.admin), la participation opérationnelle (roles/mpc.editor) et la surveillance en lecture seule (roles/mpc.viewer). Dans votre instance, les administrateurs, les auteurs de règles et les signataires ont également besoin d'un utilisateur dont le rôle (ADMIN, POLICY_AUTHOR ou SIGNER) est vérifié par l'instance pour les méthodes qui agissent au nom d'un utilisateur. Les approbations doivent être signées avec la clé d'autorisation enregistrée sur cet utilisateur. Pour en savoir plus, consultez Autorisation d'une requête.

Selon le type d'appelant, vous pouvez utiliser deux mécanismes de fédération d'identité :

  • Fédération des identités des employés (locations/global/workforcePools/...) : authentifie les utilisateurs humains (administrateurs, auteurs de règles, signataires et responsables de la conformité) à l'aide de pools d'employés au niveau de l'organisation mappés à votre IdP d'entreprise. Ce guide explique comment configurer la fédération des identités des employés de bout en bout.
  • Fédération d'identité de charge de travail (projects/.../locations/global/workloadIdentityPools/...) : authentifie les charges de travail automatisées (telles que les daemons de cosignataire sans interface graphique exécutés dans AWS, Azure ou Kubernetes) à l'aide de pools d'identités de charge de travail au niveau du projet.

Pour en savoir plus sur la mise en correspondance des rôles IAM avec les personas de calcul multipartite, consultez Sécurité et autorisation.

Avant de commencer

Avant de commencer, assurez-vous de disposer des éléments suivants :

  1. Une organisation Google Cloud et un projet client intégrés au calcul multipartite.
  2. La CLI gcloud et jq installés, et gcloud authentifié avec un compte administrateur disposant des rôles suivants :
    • Administrateur de pool d'employés (roles/iam.workforcePoolAdmin) sur votre organisation Google Cloud (si vous créez un pool d'employés à l'étape 1).
    • Administrateur IAM de projet (roles/resourcemanager.projectIamAdmin) et Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin) sur votre projet client.

  3. Les API requises activées sur votre projet client :

    gcloud services enable mpc.googleapis.com iam.googleapis.com sts.googleapis.com \
  --project="my-project"

  4. Une application OIDC ou SAML 2.0 externe configurée dans votre IdP d'entreprise. Si vous prévoyez d'utiliser la connexion interactive au navigateur avec la CLI gcloud, configurez l'URI de redirection Google Cloud dans votre application IdP (consultez les guides de configuration pour Okta et Microsoft Entra ID).

Configuration

Mettez à jour les variables suivantes pour renseigner les commandes de ce guide.

Paramètres de configuration requis

Personnalisez ces paramètres en fonction de votre environnement Google Cloud et de la configuration de votre IdP externe.

Paramètre Valeur Description
ID d'organisation 123456789012 L'ID numérique de votre organisation Google Cloud .
ID du projet my-project ID du projet client enregistré pour votre instance de calcul multipartite.
ID de domaine 67317436-0f29-ba9e-9146-d11c0bd8df9b ID de domaine unique attribué à votre instance de calcul multipartite.
ID du chemin d'accès de l'instance mpc-unit-bob-123 ID du chemin d'instance attribué à votre instance de calcul multipartite.
Emplacement us-central1 Emplacement du déploiement (us-central1). Pour en savoir plus, consultez Emplacements du calcul multipartite.
ID du pool d'employés mpc-workforce-pool ID du pool d'identités de personnel au niveau de l'organisation.
ID du fournisseur mpc-oidc-provider ID du fournisseur de pools d'identités d'employés.
URI de l'émetteur de l'IdP https://idp.example.com URI de l'émetteur de votre IdP OIDC externe.
ID client du fournisseur d'identité mpc-client ID client OAuth 2.0 configuré dans votre IdP externe.

Étape 1 : Configurez un pool d'identités de personnel et un fournisseur

Les pools d'identités d'employés (locations/global/workforcePools/mpc-workforce-pool) sont des ressources au niveau de l'organisation qui correspondent au locataire de votre IdP d'entreprise. Vous n'avez pas besoin de créer des pools d'employés distincts pour chaque projet ou rôle.

  1. Créez un pool d'identités de personnel dans votre organisation Google Cloud  :

    gcloud iam workforce-pools create "mpc-workforce-pool" \
  --organization="123456789012" \
  --location="global" \
  --display-name="MPC Workforce Pool"

  2. Créez un fournisseur de pools d'employés OIDC qui fait confiance à votre IdP externe et mappe les revendications de sujet et de groupe :

    gcloud iam workforce-pools providers create-oidc "mpc-oidc-provider" \
  --workforce-pool="mpc-workforce-pool" \
  --location="global" \
  --display-name="MPC Enterprise OIDC Provider" \
  --issuer-uri="https://idp.example.com" \
  --client-id="mpc-client" \
  --attribute-mapping="google.subject=assertion.sub,google.groups=assertion.groups" \
  --web-sso-response-type="id-token" \
  --web-sso-assertion-claims-behavior="only-id-token-claims"

Étape 2 : Attribuer des rôles IAM aux comptes principaux fédérés

Pour appeler l'API MPC, les comptes principaux fédérés ont besoin de deux types de liaisons de rôles IAM sur votre projet client (my-project) :

  1. Consommateur Service Usage (roles/serviceusage.serviceUsageConsumer), qui autorise l'identité fédérée à attribuer le quota d'API et la facturation à votre projet client.
  2. Un rôle de calcul multipartite (roles/mpc.admin, roles/mpc.editor ou roles/mpc.viewer), qui autorise des opérations de calcul multipartite spécifiques.

En production, associez des rôles IAM à des groupes d'IdP distincts dans votre pool d'employés :

# 1. Allow members of the workforce pool to consume APIs through the consumer project
gcloud projects add-iam-policy-binding "my-project" \
  --role="roles/serviceusage.serviceUsageConsumer" \
  --member="principalSet://iam.googleapis.com/locations/global/workforcePools/mpc-workforce-pool/*"

# 2. Grant MPC Admin to the enterprise administrators group
gcloud projects add-iam-policy-binding "my-project" \
  --role="roles/mpc.admin" \
  --member="principalSet://iam.googleapis.com/locations/global/workforcePools/mpc-workforce-pool/group/mpc-admins"

# 3. Grant MPC Editor to Policy Authors and Signers groups
gcloud projects add-iam-policy-binding "my-project" \
  --role="roles/mpc.editor" \
  --member="principalSet://iam.googleapis.com/locations/global/workforcePools/mpc-workforce-pool/group/mpc-policy-authors"

gcloud projects add-iam-policy-binding "my-project" \
  --role="roles/mpc.editor" \
  --member="principalSet://iam.googleapis.com/locations/global/workforcePools/mpc-workforce-pool/group/mpc-signers"

# 4. Grant MPC Viewer to the Compliance group
gcloud projects add-iam-policy-binding "my-project" \
  --role="roles/mpc.viewer" \
  --member="principalSet://iam.googleapis.com/locations/global/workforcePools/mpc-workforce-pool/group/mpc-auditors"

Charges de travail de signataire automatisées (fédération d'identité de charge de travail)

Si vous exécutez des daemons de cosignataire automatisés en dehors de Google Cloud (par exemple, dans AWS, Azure ou Kubernetes), configurez un pool d'identités de charge de travail et un fournisseur au niveau du projet. Accordez roles/serviceusage.serviceUsageConsumer et roles/mpc.editor au compte principal de la charge de travail (principal://iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/subject/<var>SIGNER_NODE_SUBJECT</var>, en remplaçant <var>PROJECT_NUMBER</var>, <var>WORKLOAD_POOL_ID</var> et <var>SIGNER_NODE_SUBJECT</var> par votre numéro de projet, l'ID du pool de charges de travail et la revendication sub de la charge de travail), puis générez un fichier d'Identifiants par défaut de l'application de l'application à l'aide de gcloud iam workload-identity-pools create-cred-config.

Ajouter des identités fédérées en tant qu'utilisateurs v1beta

Dans l'API v1beta, les rôles IAM de cette étape permettent à une identité fédérée d'appeler votre instance. Pour agir au sein de l'instance en tant qu'administrateur, auteur de règles ou signataire, l'identité doit également disposer d'un utilisateur. L'instance identifie l'appelant en comparant son compte principal au champ principal de chaque utilisateur.

Pour une identité fédérée de fédération des identités des employés, définissez principal sur l'identifiant du principal de l'identité :

principal://iam.googleapis.com/locations/global/workforcePools/mpc-workforce-pool/subject/SUBJECT_ID

Remplacez SUBJECT_ID par la valeur que votre fournisseur mappe à google.subject. Avec le mappage d'attributs de l'étape 1, il s'agit de la revendication sub du jeton d'ID de l'utilisateur.

Lorsque vous définissez principal, tenez compte des points suivants :

  • Utilisez un identifiant principal://, et non un identifiant principalSet://. Un utilisateur est une personne. Les identifiants de groupe et de pool tels que principalSet://.../group/mpc-signers fonctionnent dans les liaisons de rôles IAM, mais ils ne correspondent jamais à un appelant. Par conséquent, un utilisateur créé avec l'un d'eux ne peut pas agir dans l'instance.
  • Correspondance exacte avec l'objet L'instance compare les sujets de personnel et de charge de travail en tenant compte de la casse. Copiez donc le sujet tel qu'il est émis par votre IdP. Les adresses e-mail des comptes Google, telles que alice@example.com, sont comparées sans tenir compte de la casse.
  • Vous ne pourrez pas modifier principal par la suite. Pour modifier l'identité d'un utilisateur, désactivez-le et créez-en un autre.

Étape 3 : S'authentifier et obtenir un jeton d'accès fédéré

L'API MPC n'accepte pas les jetons OIDC ni les assertions SAML directement depuis votre IdP. Échangez l'identifiant du fournisseur d'identité avec le service de jetons de sécurité contre un jeton d'accès fédéré Google Cloud avant d'appeler le point de terminaison de votre instance de calcul multipartite (*.mpc.goog).

Vous pouvez obtenir et gérer des jetons d'accès fédérés automatiquement à l'aide des Identifiants par défaut de l'application (ADC) et de la CLI gcloud, ou de manière programmatique à l'aide de l'API Security Token Service.

Identifiants par défaut de l'application et gcloud CLI

Dans les applications clientes de production et les sessions CLI interactives, utilisez un fichier de configuration pour que Google Cloud SDK et les bibliothèques clientes Cloud gèrent automatiquement l'échange, la mise en cache et l'actualisation des jetons du service de jeton de sécurité en arrière-plan.

Option A : Connexion interactive au navigateur

Générez un fichier de configuration de connexion et authentifiez la CLI gcloud et les Identifiants par défaut de l'application (ADC) auprès de votre IdP d'entreprise :

gcloud iam workforce-pools create-login-config \
  "locations/global/workforcePools/mpc-workforce-pool/providers/mpc-oidc-provider" \
  --activate \
  --output-file="login-config.json"

gcloud config set billing/quota_project "my-project"
gcloud auth login --login-config="login-config.json"
gcloud auth application-default login --login-config="login-config.json"

Option B : Connexion non interactive avec un fichier de configuration des identifiants (ADC)

Si un processus externe fournit et actualise un jeton OIDC signé dans un fichier local (par exemple, /var/run/secrets/tokens/oidc-token) avant l'expiration du jeton, générez un fichier de configuration d'identifiants externes :

gcloud iam workforce-pools create-cred-config \
  "locations/global/workforcePools/mpc-workforce-pool/providers/mpc-oidc-provider" \
  --subject-token-type="urn:ietf:params:oauth:token-type:id_token" \
  --credential-source-file="/var/run/secrets/tokens/oidc-token" \
  --workforce-pool-user-project="my-project" \
  --output-file="credential-config.json"

export GOOGLE_APPLICATION_CREDENTIALS="$(pwd)/credential-config.json"

Exportez le jeton d'accès pour les requêtes curl :

Après avoir suivi l'option A ou l'option B, exportez le jeton d'accès fédéré depuis ADC vers ACCESS_TOKEN :

export ACCESS_TOKEN="$(gcloud auth application-default print-access-token)"

Échange de jetons STS REST direct

Si vous intégrez un client personnalisé sans les SDK Google Cloud , échangez un jeton d'ID OIDC signé (<var>IDP_ID_TOKEN</var>) directement avec Security Token Service. Incluez userProject dans le champ options afin que Google Cloud attribue le jeton à votre projet client :

# Set IDP_ID_TOKEN to the signed OIDC JWT assertion from your external IdP
# export IDP_ID_TOKEN="eyJhbGciOiJSUzI1NiIs..."

STS_RESPONSE=$(curl -sS -X POST "https://sts.googleapis.com/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  --data-urlencode "audience=//iam.googleapis.com/locations/global/workforcePools/mpc-workforce-pool/providers/mpc-oidc-provider" \
  --data-urlencode "scope=https://www.googleapis.com/auth/cloud-platform" \
  --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
  --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:id_token" \
  --data-urlencode "subject_token=${IDP_ID_TOKEN}" \
  --data-urlencode 'options={"userProject":"my-project"}')

export ACCESS_TOKEN=$(echo "${STS_RESPONSE}" | jq -er '.access_token') || echo "${STS_RESPONSE}" | jq .

Étape 4 : Vérifier l'accès à l'API fédérée

Vérifiez que vos identifiants fédérés, l'attribution userProject et les liaisons de rôles IAM fonctionnent en listant les utilisateurs de votre instance de calcul multipartite. Comme mpc.googleapis.com/users.list est inclus dans roles/mpc.viewer, roles/mpc.editor et roles/mpc.admin, tout personnage fédéré autorisé peut exécuter cette vérification :

curl -sS -X GET \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "X-Goog-User-Project: my-project" \
  "https://67317436-0f29-ba9e-9146-d11c0bd8df9b.us-central1.mpc.goog/v1beta/projects/my-project/locations/us-central1/instances/mpc-unit-bob-123/users" | jq .

Une réponse JSON 200 OK (soit {} sur une nouvelle instance, soit une liste de users) confirme que votre identité fédérée est authentifiée et autorisée à appeler votre instance de calcul multipartite.

Cette vérification n'utilise qu'IAM. Pour confirmer que l'instance reconnaît également votre identité en tant qu'utilisateur, vérifiez que l'un des utilisateurs renvoyés comporte votre identifiant principal:// dans son champ principal. Pour en savoir plus, consultez Ajouter des identités fédérées en tant qu'utilisateurs v1beta.

Dépannage

Si vous rencontrez des erreurs d'authentification ou d'autorisation lorsque vous appelez le calcul multipartite avec des identifiants fédérés, vérifiez les exigences suivantes :

Attribution du projet utilisateur (401 UNAUTHENTICATED: Unable to determine client project number)

  • Cause : Les identifiants du pool d'employés au niveau de l'organisation ne sont pas intrinsèquement liés à un seul projet Google Cloud , sauf si un projet utilisateur est spécifié lors de l'échange de jetons ou dans la requête.
  • Résolution : incluez options: {"userProject": "<var>PROJECT_ID</var>"} dans le corps de votre requête d'échange de jetons Security Token Service (ou --workforce-pool-user-project dans gcloud iam workforce-pools create-cred-config), et incluez l'en-tête X-Goog-User-Project: <var>PROJECT_ID</var> dans vos appels d'API MPC.

Autorisation Service Usage manquante (403 PERMISSION_DENIED)

  • Cause : Le compte principal ou le groupe fédéré ne dispose pas de l'autorisation nécessaire pour attribuer l'utilisation de l'API au projet client spécifié dans userProject ou X-Goog-User-Project.
  • Solution : Accordez roles/serviceusage.serviceUsageConsumer à votre membre principal:// ou principalSet:// sur le projet client (voir l'étape 2).

Non-correspondance du projet client (403 PERMISSION_DENIED: Project is not allowed to call the API through this host)

  • Cause : Chaque point de terminaison d'instance de calcul multipartite dédié n'accepte que les requêtes provenant du projet client configuré pour cette instance.
  • Solution : Vérifiez que <var>PROJECT_ID</var> dans le chemin d'URL de la requête et l'en-tête userProject / X-Goog-User-Project correspond au projet client provisionné pour votre instance de calcul multipartite.

Identifiant non valide (401 UNAUTHENTICATED: Request credential is invalid)

  • Cause : un jeton OIDC ou une assertion SAML tiers ont été envoyés directement au point de terminaison de calcul multipartite sans avoir été échangés au préalable à l'aide de Security Token Service.
  • Solution : Échangez vos identifiants IdP via https://sts.googleapis.com/v1/token (ou utilisez les Identifiants par défaut de l'application) et transmettez le jeton d'accès Google Cloud obtenu dans l'en-tête Authorization: Bearer.

La règle de restriction de domaine bloque les liaisons de rôles (400 FAILED_PRECONDITION)

  • Cause : Votre organisation Google Cloud applique la règle d'administration constraints/iam.allowedPolicyMemberDomains, qui limite les domaines principaux auxquels des rôles IAM peuvent être attribués sur les projets.
  • Solution : Demandez à l'administrateur des règles d'administration d'ajouter l'ensemble de comptes principaux de votre pool d'employés aux domaines de membres autorisés par les règles sur votre projet ou organisation client, ou effectuez un test dans un projet où constraints/iam.allowedPolicyMemberDomains autorise votre pool d'employés.

Étapes suivantes

  • Pour créer des utilisateurs, des équipes, des règles de transaction et des clés, et pour signer des transactions avec votre identité fédérée, suivez le guide de l'utilisateur du calcul multipartite. Définissez le compte principal de chaque utilisateur sur l'identifiant principal:// décrit dans Ajouter des identités fédérées en tant qu'utilisateurs v1beta.
  • Le guide de l'utilisateur récupère le jeton d'accès de chaque persona avec gcloud auth print-access-token, qui utilise les identifiants de la CLI gcloud, et non les Identifiants par défaut de l'application. Connectez chaque utilisateur fédéré avec gcloud auth login --login-config, comme indiqué dans l'option A de l'étape 3.
  • Pour en savoir plus sur les rôles utilisateur, les autorisations IAM et les conditions au niveau des ressources, consultez Sécurité et autorisation.