Workforce Identity-Föderation (BYOID) konfigurieren

In diesem Leitfaden wird beschrieben, wie Sie Bring Your Own Identity (BYOID) für die Multi-Party Compute API mithilfe der Mitarbeiteridentitätsföderation und der Workload Identity-Föderation konfigurieren. Mit der Identitätsföderation können sich menschliche Nutzer und automatisierte Signierer-Arbeitslasten über den externen Identitätsanbieter (IdP) Ihrer Organisation, z. B. Okta, Microsoft Entra ID oder Ping Identity, bei Multi-Party Compute authentifizieren. Sie müssen keine Google-Konten erstellen oder langlebige Dienstkontoschlüssel verwalten.

Übersicht

Die Identitätsföderation lässt sich auf den folgenden Ebenen in das Defense-in-Depth-Sicherheitsmodell für Multi-Party Computation einbinden:

  1. Edge Identity and Access Management (IAM)-Autorisierung: Aufrufer tauschen Anmeldedaten von einem externen OpenID Connect (OIDC)- oder SAML 2.0-IdP mit dem Security Token Service (Security Token Service) von Google Cloud gegen ein kurzlebiges föderiertes Zugriffstoken aus. Das Google Cloud API-Gateway wertet IAM-Rollenbindungen anhand des föderierten Hauptkonto-URI aus, bevor Anfragen an Ihre Multi-Party-Compute-Instanz weitergeleitet werden, und gibt die föderierte Identität (principalSubject) für Cloud-Audit-Logs weiter.
  2. Aufgabentrennung und kryptografische Genehmigung: IAM-Rollen trennen die administrative Bereitstellung (roles/mpc.admin), die operative Teilnahme (roles/mpc.editor) und den Lesezugriff (roles/mpc.viewer). Innerhalb Ihrer Instanz benötigen Administratoren, Richtlinienautoren und Signierer auch einen Nutzer, dessen Rolle (ADMIN, POLICY_AUTHOR oder SIGNER) von der Instanz auf Methoden geprüft wird, die im Namen eines Nutzers agieren. Genehmigungen müssen mit dem Autorisierungsschlüssel signiert werden, der für diesen Nutzer registriert ist. Weitere Informationen finden Sie unter Anfrage autorisieren.

Je nach Aufrufertyp können Sie zwei Mechanismen für die Identitätsföderation verwenden:

  • Mitarbeiteridentitätsföderation (locations/global/workforcePools/...): Authentifiziert menschliche Nutzer (Administratoren, Richtlinienautoren, Signierer und Compliance-Beauftragte) mithilfe von Mitarbeiterpools auf Organisationsebene, die Ihrem Unternehmens-IdP zugeordnet sind. In diesem Leitfaden wird die Konfiguration der Workforce Identity-Föderation von Anfang bis Ende beschrieben.
  • Workload Identity-Föderation (projects/.../locations/global/workloadIdentityPools/...): Authentifiziert automatisierte Arbeitslasten (z. B. Headless-Co-Signer-Daemons, die in AWS, Azure oder Kubernetes ausgeführt werden) mithilfe von Workload Identity-Pools auf Projektebene.

Weitere Informationen dazu, wie IAM-Rollen Multi-Party-Computation-Personas zugeordnet werden, finden Sie unter Sicherheit und Autorisierung.

Hinweis

Folgendes wird benötigt:

  1. Eine Google Cloud -Organisation und ein Nutzerprojekt, die für Multi-Party Computation registriert sind.
  2. Die gcloud-Befehlszeile und jq sind installiert und gcloud ist mit einem Administratorkonto authentifiziert, das die folgenden Rollen hat:
    • Workforce Pool Admin (roles/iam.workforcePoolAdmin) für Ihre Organisation in Google Cloud (wenn Sie in Schritt 1 einen neuen Personalpool erstellen).
    • Projekt-IAM-Administrator (roles/resourcemanager.projectIamAdmin) und Service Usage-Administrator (roles/serviceusage.serviceUsageAdmin) für Ihr Nutzerprojekt.

  3. Die erforderlichen APIs, die in Ihrem Nutzerprojekt aktiviert sind:

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

  4. Eine externe OIDC- oder SAML 2.0-Anwendung, die in Ihrem Unternehmens-IdP konfiguriert ist. Wenn Sie die interaktive Browseranmeldung mit der gcloud-Befehlszeile verwenden möchten, konfigurieren Sie den Weiterleitungs-URI Google Cloud in Ihrer IdP-Anwendung. Weitere Informationen finden Sie in den Einrichtungsanleitungen für Okta und Microsoft Entra ID.

Einrichtung

Aktualisieren Sie die folgenden Variablen, um die Befehle in diesem Leitfaden zu füllen.

Erforderliche Einrichtungsparameter

Passen Sie diese Parameter an Ihre Google Cloud -Umgebung und die Konfiguration des externen IdP an.

Parameter Wert Beschreibung
Organisations-ID 123456789012 Die numerische Organisations-ID in Google Cloud .
Projekt-ID my-project Die Nutzerprojekt-ID, die für Ihre Multi-Party-Computation-Instanz registriert ist.
Domain-ID 67317436-0f29-ba9e-9146-d11c0bd8df9b Die eindeutige Domain-ID, die Ihrer Multi-Party-Computation-Instanz zugewiesen ist.
Instanzpfad-ID mpc-unit-bob-123 Die Instanzpfad-ID, die Ihrer Multi-Party-Compute-Instanz zugewiesen ist.
Standort us-central1 Bereitstellungsstandort (us-central1). Weitere Informationen finden Sie unter Multi-Party-Compute-Standorte.
Personalpool-ID mpc-workforce-pool Die ID des Workforce Identity-Pools auf Organisationsebene.
Anbieter-ID mpc-oidc-provider Die ID des Anbieters von Workforce Identity-Pools.
IdP-Aussteller-URI https://idp.example.com Der Aussteller-URI Ihres externen OIDC-IdP.
IdP-Client-ID mpc-client Die OAuth 2.0-Client-ID, die in Ihrem externen IdP konfiguriert ist.

Schritt 1: Workforce Identity-Pool und -Anbieter konfigurieren

Mitarbeiteridentitätspools (locations/global/workforcePools/mpc-workforce-pool) sind Ressourcen auf Organisationsebene, die Ihrem Unternehmens-IdP-Mandanten zugeordnet sind. Sie müssen nicht für jedes Projekt oder jede Rolle separate Personalpools erstellen.

  1. Erstellen Sie einen Workforce Identity-Pool in Ihrer Google Cloud -Organisation:

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

  2. Erstellen Sie einen OIDC-Workforce-Pool-Anbieter, der Ihrem externen IdP vertraut und Subjekt- und Gruppenanforderungen zuordnet:

    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"

Schritt 2: Föderierten Hauptkonten IAM-Rollen zuweisen

Um die MPC API aufzurufen, benötigen föderierte Hauptkonten zwei Arten von IAM-Rollenbindungen für Ihr Nutzerprojekt (my-project):

  1. Service Usage Consumer (roles/serviceusage.serviceUsageConsumer), die die föderierte Identität autorisiert, API-Kontingente und Abrechnung Ihrem Nutzerprojekt zuzuordnen.
  2. Eine Multi-Party Compute-Rolle (roles/mpc.admin, roles/mpc.editor oder roles/mpc.viewer), die bestimmte Multi-Party Compute-Vorgänge autorisiert.

Binden Sie in der Produktion IAM-Rollen an bestimmte IdP-Gruppen in Ihrem Mitarbeiterpool:

# 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"

Automatisierte Signaturarbeitslasten (Workload Identity-Föderation)

Wenn Sie automatisierte Co-Signer-Daemons außerhalb von Google Cloud ausführen (z. B. in AWS, Azure oder Kubernetes), konfigurieren Sie einen Workload Identity-Pool und -Anbieter auf Projektebene. Gewähren Sie dem Workload-Hauptkonto (principal://iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/subject/<var>SIGNER_NODE_SUBJECT</var>, wobei <var>PROJECT_NUMBER</var>, <var>WORKLOAD_POOL_ID</var> und <var>SIGNER_NODE_SUBJECT</var> durch Ihre Projektnummer, Workload-Pool-ID und Workload-sub-Anforderung ersetzt werden) die Berechtigungen roles/serviceusage.serviceUsageConsumer und roles/mpc.editor und generieren Sie mit gcloud iam workload-identity-pools create-cred-config eine Datei mit Standardanmeldedaten für Anwendungen.

Föderierte Identitäten als v1beta-Nutzer hinzufügen

In der v1beta API ermöglichen die IAM-Rollen aus diesem Schritt einer föderierten Identität, Ihre Instanz aufzurufen. Um innerhalb der Instanz als Administrator, Richtlinienautor oder Signierer zu agieren, benötigt die Identität auch einen Nutzer. Die Instanz identifiziert den Aufrufer, indem sie das Hauptkonto des Aufrufers mit dem Feld principal jedes Nutzers abgleicht.

Legen Sie für eine Identität der Mitarbeiteridentitätsföderation principal auf die Hauptkonto-ID des Subjekts der Identität fest:

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

Ersetzen Sie SUBJECT_ID durch den Wert, den Ihr Anbieter google.subject zuordnet. Bei der Attributzuordnung in Schritt 1 ist es die sub-Anforderung des ID-Tokens des Nutzers.

Beachten Sie beim Festlegen von principal Folgendes:

  • Verwenden Sie eine principal://-ID, keine principalSet://-ID. Ein Nutzer ist eine Person. Gruppen- und Poolkennungen wie principalSet://.../group/mpc-signers funktionieren in IAM-Rollenbindungen, stimmen aber nie mit einem Aufrufer überein. Daher kann ein mit einer solchen Kennung erstellter Nutzer nicht in der Instanz agieren.
  • Genaue Übereinstimmung mit dem Betreff Die Instanz vergleicht Workforce- und Arbeitslastsubjekte unter Berücksichtigung der Groß-/Kleinschreibung. Kopieren Sie das Subjekt daher so, wie es von Ihrem IdP ausgegeben wird. Bei E‑Mail-Adressen von Google-Konten wie alice@example.com wird die Groß- und Kleinschreibung nicht berücksichtigt.
  • Sie können principal später nicht mehr ändern. Wenn Sie die Identität eines Nutzers ändern möchten, deaktivieren Sie den Nutzer und erstellen Sie einen neuen.

Schritt 3: Authentifizieren und ein föderiertes Zugriffstoken abrufen

Die MPC API akzeptiert keine OIDC-Tokens oder SAML-Assertions direkt von Ihrem IdP. Tauschen Sie die IdP-Anmeldedaten mit dem Security Token Service gegen ein föderiertes Google Cloud -Zugriffstoken aus, bevor Sie den Endpunkt Ihrer Multi-Party-Computation-Instanz (*.mpc.goog) aufrufen.

Sie können föderierte Zugriffstokens automatisch mit Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) und der gcloud-CLI oder programmatisch mit der Security Token Service API abrufen und verwalten.

Standardanmeldedaten für Anwendungen und gcloud CLI

Verwenden Sie in Produktions-Clientanwendungen und interaktiven CLI-Sitzungen eine Konfigurationsdatei, damit das Google Cloud SDK und die Cloud-Clientbibliotheken den Austausch, das Caching und die Aktualisierung von Security Token Service-Tokens im Hintergrund automatisch verarbeiten.

Option A: Interaktive Anmeldung im Browser

Generieren Sie eine Konfigurationsdatei für die Anmeldung und authentifizieren Sie sowohl die gcloud-Befehlszeile als auch die Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) bei Ihrem Unternehmens-IdP:

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: Nicht interaktive Anmeldung mit einer Konfigurationsdatei für Anmeldedaten (ADC)

Wenn ein externer Prozess ein signiertes OIDC-Token in einer lokalen Datei (z. B. /var/run/secrets/tokens/oidc-token) bereitstellt und aktualisiert, bevor das Token abläuft, generieren Sie eine Konfigurationsdatei für externe Anmeldedaten:

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"

Exportieren Sie das Zugriffstoken für curl-Anfragen:

Nachdem Sie Option A oder Option B abgeschlossen haben, exportieren Sie das föderierte Zugriffstoken aus den Standardanmeldedaten für Anwendungen in ACCESS_TOKEN:

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

Direkter REST-STS-Tokenaustausch

Wenn Sie einen benutzerdefinierten Client ohne Google Cloud SDKs einbinden, tauschen Sie ein signiertes OIDC-ID-Token (<var>IDP_ID_TOKEN</var>) direkt mit dem Security Token Service aus. Fügen Sie userProject in das Feld options ein, damit Google Cloud das Token Ihrem Nutzerprojekt zuordnet:

# 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 .

Schritt 4: Föderierten API-Zugriff prüfen

Prüfen Sie, ob Ihre föderierten Anmeldedaten, die userProject-Attribution und die IAM-Rollenbindungen funktionieren, indem Sie die Nutzer in Ihrer Multi-Party-Computation-Instanz auflisten. Da mpc.googleapis.com/users.list in roles/mpc.viewer, roles/mpc.editor und roles/mpc.admin enthalten ist, kann jede autorisierte föderierte Persona diese Prüfung ausführen:

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 .

Eine 200 OK-JSON-Antwort (entweder {} bei einer neuen Instanz oder eine Liste von users) bestätigt, dass Ihre föderierte Identität authentifiziert und autorisiert ist, Ihre Multi-Party-Compute-Instanz aufzurufen.

Bei dieser Prüfung wird nur IAM verwendet. Prüfen Sie, ob einer der zurückgegebenen Nutzer Ihre principal://-ID im Feld principal hat, um zu bestätigen, dass die Instanz Ihre Identität auch als Nutzer erkennt. Weitere Informationen finden Sie unter Föderierte Identitäten als v1beta-Nutzer hinzufügen.

Fehlerbehebung

Wenn beim Aufrufen von Multi-Party Computation mit föderierten Anmeldedaten Authentifizierungs- oder Berechtigungsfehler auftreten, prüfen Sie die folgenden Anforderungen:

Nutzerprojektzuordnung (401 UNAUTHENTICATED: Unable to determine client project number)

  • Ursache: Anmeldedaten für Personalpools auf Organisationsebene sind nicht inhärent an ein einzelnes Google Cloud -Projekt gebunden, es sei denn, beim Tokenaustausch oder in der Anfrage wird ein Nutzerprojekt angegeben.
  • Lösung: Fügen Sie options: {"userProject": "<var>PROJECT_ID</var>"} in den Text der Tokenaustauschanfrage des Security Token Service ein (oder --workforce-pool-user-project in gcloud iam workforce-pools create-cred-config) und fügen Sie den Header X-Goog-User-Project: <var>PROJECT_ID</var> in Ihre MPC API-Aufrufe ein.

Fehlende Berechtigung für die Dienstnutzung (403 PERMISSION_DENIED)

  • Ursache: Dem föderierten Hauptkonto oder der föderierten Gruppe fehlt die Berechtigung, die API-Nutzung dem in userProject oder X-Goog-User-Project angegebenen Nutzerprojekt zuzuordnen.
  • Lösung: Gewähren Sie Ihrem principal://- oder principalSet://-Mitglied im Nutzerprojekt die Berechtigung roles/serviceusage.serviceUsageConsumer (siehe Schritt 2).

Nicht übereinstimmendes Nutzerprojekt (403 PERMISSION_DENIED: Project is not allowed to call the API through this host)

  • Ursache: Jeder dedizierte Multi-Party-Compute-Instanzendpunkt akzeptiert nur Anfragen vom Nutzerprojekt, das für diese Instanz konfiguriert ist.
  • Lösung: Prüfen Sie, ob <var>PROJECT_ID</var> sowohl im Anfrage-URL-Pfad als auch im Header userProject / X-Goog-User-Project mit dem Nutzerprojekt übereinstimmt, das für Ihre Multi-Party-Compute-Instanz bereitgestellt wurde.

Ungültige Anmeldedaten (401 UNAUTHENTICATED: Request credential is invalid)

  • Ursache: Ein OIDC-Token oder eine SAML-Assertion eines Drittanbieters wurde direkt an den Multi-Party-Compute-Endpunkt gesendet, ohne es vorher über den Security Token Service auszutauschen.
  • Lösung: Tauschen Sie Ihre IdP-Anmeldedaten über https://sts.googleapis.com/v1/token aus (oder verwenden Sie Standardanmeldedaten für Anwendungen) und übergeben Sie das resultierende Zugriffstoken von Google Cloud im Header Authorization: Bearer.

Richtlinie für die Domainbeschränkung blockiert Rollenbindungen (400 FAILED_PRECONDITION)

  • Ursache: Ihre Google Cloud Organisation erzwingt die Organisationsrichtlinie constraints/iam.allowedPolicyMemberDomains, die einschränkt, welchen Hauptkontodomains IAM-Rollen für Projekte zugewiesen werden können.
  • Lösung: Bitten Sie Ihren Administrator für Organisationsrichtlinien, die Hauptkontogruppe Ihres Personalpools den zulässigen Richtlinienmitgliedsdomains in Ihrem Nutzerprojekt oder Ihrer Organisation hinzuzufügen, oder testen Sie in einem Projekt, in dem constraints/iam.allowedPolicyMemberDomains Ihren Personalpool zulässt.

Nächste Schritte

  • Folgen Sie dem Nutzerhandbuch für Multi-Party Computation, um Nutzer, Teams, Transaktionsrichtlinien und Schlüssel zu erstellen und Transaktionen mit Ihrer föderierten Identität zu signieren. Legen Sie für das Hauptkonto jedes Nutzers die Kennung principal:// fest, die unter Föderierte Identitäten als v1beta-Nutzer hinzufügen beschrieben wird.
  • Im Nutzerhandbuch wird das Zugriffstoken jeder Persona mit gcloud auth print-access-token abgerufen. Dabei werden gcloud-CLI-Anmeldedaten verwendet, nicht die Standardanmeldedaten für Anwendungen. Melden Sie jeden föderierten Nutzer mit gcloud auth login --login-config an, wie in Option A von Schritt 3 gezeigt.
  • Weitere Informationen zu Nutzerrollen, IAM-Berechtigungen und Bedingungen auf Ressourcenebene finden Sie unter Sicherheit und Autorisierung.