Configura la federazione delle identità per la forza lavoro (BYOID)

Questa guida spiega come configurare Bring Your Own Identity (BYOID) per l'API Multi-party Compute utilizzando la federazione delle identità per la forza lavoro e la federazione delle identità per i workload. Con la federazione delle identità, gli utenti umani e i workload di firma automatizzati possono autenticarsi nel calcolo multipartitico utilizzando il provider di identità (IdP) esterno della tua organizzazione, ad esempio Okta, Microsoft Entra ID o Ping Identity. Non è necessario creare Account Google o gestire chiavi dei account di servizio di lunga durata.

Panoramica

La federazione delle identità si integra con il modello di sicurezza di difesa in profondità del calcolo multipartitico nei seguenti livelli:

  1. Autorizzazione Edge Identity and Access Management (IAM): i chiamanti scambiano le credenziali di un provider di identità OpenID Connect (OIDC) o SAML 2.0 esterno con Google Cloud Security Token Service (Security Token Service) per un token di accesso federato di breve durata. Il gateway API Google Cloud valuta le associazioni dei ruoli IAM rispetto all'URI del principal federato prima di inoltrare le richieste all'istanza di calcolo multipartitico e propaga l'identità federata (principalSubject) per Cloud Audit Logs.
  2. Separazione dei compiti e approvazione crittografica: i ruoli IAM separano il provisioning amministrativo (roles/mpc.admin), la partecipazione operativa (roles/mpc.editor) e la supervisione di sola lettura (roles/mpc.viewer). All'interno dell'istanza, gli amministratori, gli autori delle policy e i firmatari hanno bisogno anche di un utente il cui ruolo (ADMIN, POLICY_AUTHOR o SIGNER) viene controllato dall'istanza per i metodi che agiscono per conto di un utente e le approvazioni devono essere firmate con la chiave di autorizzazione registrata su quell'utente. Per saperne di più, consulta Come viene autorizzata una richiesta.

A seconda del tipo di chiamante, puoi utilizzare due meccanismi di federazione delle identità:

  • Federazione delle identità per la forza lavoro (locations/global/workforcePools/...): autentica gli utenti umani (amministratori, autori di policy, firmatari e conformità) utilizzando pool di forza lavoro a livello di organizzazione mappati all'IdP aziendale. Questa guida illustra la configurazione end-to-end della federazione delle identità per la forza lavoro.
  • Federazione delle identità per i workload (projects/.../locations/global/workloadIdentityPools/...): autentica i workload automatizzati (come i daemon di co-firmatari headless in esecuzione in AWS, Azure o Kubernetes) utilizzando i pool di identità dei workload a livello di progetto.

Per saperne di più su come i ruoli IAM vengono mappati ai personaggi di calcolo multipartitico, consulta Sicurezza e autorizzazione.

Prima di iniziare

Prima di iniziare, assicurati di avere quanto segue:

  1. Un'organizzazione Google Cloud e un progetto consumer di cui è stato eseguito l'onboarding nel calcolo multipartitico.
  2. gcloud CLI e jq installati e gcloud autenticato con un account amministratore che dispone dei seguenti ruoli:
    • Amministratore pool di forza lavoro (roles/iam.workforcePoolAdmin) sulla tua organizzazione Google Cloud (se crei un nuovo pool di forza lavoro nel passaggio 1).
    • Project IAM Admin (roles/resourcemanager.projectIamAdmin) e Service Usage Admin (roles/serviceusage.serviceUsageAdmin) sul progetto consumer.

  3. Le API richieste abilitate nel tuo progetto consumer:

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

  4. Un'applicazione OIDC o SAML 2.0 esterna configurata nell'IdP aziendale. Se prevedi di utilizzare l'accesso interattivo al browser con l'interfaccia a riga di comando gcloud, configura l'URI di reindirizzamento Google Cloud nell'applicazione IdP (consulta le guide alla configurazione per Okta e Microsoft Entra ID).

Configurazione

Aggiorna le seguenti variabili per compilare i comandi in questa guida.

Parametri di configurazione obbligatori

Personalizza questi parametri in base al tuo ambiente Google Cloud e alla configurazione dell'IdP esterno.

Parametro Valore Descrizione
ID organizzazione 123456789012 L'ID organizzazione Google Cloud numerico.
ID progetto my-project L'ID progetto consumer registrato per l'istanza di computing multipartitico.
ID dominio 67317436-0f29-ba9e-9146-d11c0bd8df9b L'ID dominio univoco assegnato alla tua istanza di computing multipartitico.
ID percorso istanza mpc-unit-bob-123 L'ID percorso dell'istanza assegnato alla tua istanza di computing multipartitico.
Località us-central1 Località di deployment (us-central1). Per saperne di più, consulta Località di calcolo multipartitico.
ID pool di forza lavoro mpc-workforce-pool L'ID del pool di identità della forza lavoro a livello di organizzazione.
ID provider mpc-oidc-provider L'ID provider del pool di identità della forza lavoro.
URI emittente IdP https://idp.example.com L'URI dell'emittente IdP OIDC esterno.
ID client IdP mpc-client L'ID client OAuth 2.0 configurato nell'IdP esterno.

Passaggio 1: configura un pool di identità della forza lavoro e un provider

I pool di identità della forza lavoro (locations/global/workforcePools/mpc-workforce-pool) sono risorse a livello di organizzazione che vengono mappate al tenant IdP aziendale. Non è necessario creare pool di forza lavoro separati per ogni progetto o ruolo.

  1. Crea un pool di identità per la forza lavoro nella tua organizzazione Google Cloud :

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

  2. Crea un provider di pool di forza lavoro OIDC che consideri attendibile il tuo IdP esterno e mappi le rivendicazioni di soggetto e gruppo:

    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"

Passaggio 2: concedi i ruoli IAM alle entità federate

Per chiamare l'API MPC, le entità federate richiedono due tipi di associazioni di ruoli IAM nel progetto consumer (my-project):

  1. Service Usage Consumer (roles/serviceusage.serviceUsageConsumer), che autorizza l'identità federata ad attribuire la quota e la fatturazione dell'API al tuo progetto consumer.
  2. Un ruolo Multi-party Compute (roles/mpc.admin, roles/mpc.editor o roles/mpc.viewer), che autorizza operazioni di calcolo multipartitico specifiche.

In produzione, associa i ruoli IAM a gruppi IdP distinti all'interno del pool di forza lavoro:

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

Workload di firmatari automatizzati (federazione delle identità per i workload)

Se esegui daemon di co-firmatari automatici al di fuori di Google Cloud (ad esempio in AWS, Azure o Kubernetes), configura un pool di identità del workload e un provider con ambito di progetto. Concedi roles/serviceusage.serviceUsageConsumer e roles/mpc.editor all'entità workload (principal://iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/subject/<var>SIGNER_NODE_SUBJECT</var>, sostituendo <var>PROJECT_NUMBER</var>, <var>WORKLOAD_POOL_ID</var> e <var>SIGNER_NODE_SUBJECT</var> con il numero di progetto, l'ID pool di workload e l'attestazione sub del workload) e genera un file Credenziali predefinite dell'applicazione dell'applicazione utilizzando gcloud iam workload-identity-pools create-cred-config.

Aggiungi identità federate come utenti v1beta

Nell'API v1beta, i ruoli IAM di questo passaggio consentono a un'identità federata di chiamare la tua istanza. Per agire all'interno dell'istanza, come amministratore, autore di policy o firmatario, l'identità deve avere anche un utente. L'istanza identifica il chiamante confrontando l'entità del chiamante con il campo principal di ogni utente.

Per un'identità federata per la forza lavoro, imposta principal sull'identificatore dell'entità soggetto dell'identità:

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

Sostituisci SUBJECT_ID con il valore che il tuo provider mappa a google.subject. Con la mappatura degli attributi nel passaggio 1, si tratta della rivendicazione sub del token ID dell'utente.

Quando imposti principal, tieni presente quanto segue:

  • Utilizza un identificatore principal://, non un identificatore principalSet://. Un utente è una persona. Gli identificatori di gruppi e pool come principalSet://.../group/mpc-signers funzionano nelle associazioni dei ruoli IAM, ma non corrispondono mai a un chiamante, quindi un utente creato con uno di questi identificatori non può agire nell'istanza.
  • Corrispondenza esatta dell'oggetto. L'istanza confronta i soggetti della forza lavoro e del workload facendo distinzione tra maiuscole e minuscole, quindi copia il soggetto così come viene emesso dall'IdP. Le email degli Account Google, ad esempio alice@example.com, vengono confrontate senza distinzione tra maiuscole e minuscole.
  • Non puoi modificare principal in un secondo momento. Per modificare l'identità di un utente, disattivalo e creane uno nuovo.

Passaggio 3: autenticati e ottieni un token di accesso federato

L'API MPC non accetta token OIDC o asserzioni SAML direttamente dal tuo IdP. Scambia la credenziale dell'IdP con Security Token Service per ottenere un token di accesso Google Cloud federato prima di chiamare l'endpoint dell'istanza di computing multipartitico (*.mpc.goog).

Puoi ottenere e gestire i token di accesso federato automaticamente utilizzando le Credenziali predefinite dell'applicazione (ADC) e l'interfaccia a riga di comando gcloud oppure in modo programmatico utilizzando l'API Security Token Service.

Credenziali predefinite dell'applicazione e gcloud CLI

Nelle applicazioni client di produzione e nelle sessioni CLI interattive, utilizza un file di configurazione in modo che Google Cloud SDK e le librerie client di Cloud gestiscano automaticamente lo scambio, la memorizzazione nella cache e gli aggiornamenti dei token di Security Token Service in background.

Opzione A: accesso interattivo al browser

Genera un file di configurazione di accesso e autentica sia l'interfaccia a riga di comando gcloud sia le Credenziali predefinite dell'applicazione (ADC) con l'IdP aziendale:

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"

Opzione B: accesso non interattivo con un file di configurazione delle credenziali (ADC)

Se un processo esterno fornisce e aggiorna un token OIDC firmato in un file locale (ad esempio /var/run/secrets/tokens/oidc-token) prima della scadenza del token, genera un file di configurazione delle credenziali esterne:

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"

Esporta il token di accesso per le richieste curl:

Dopo aver completato l'Opzione A o l'Opzione B, esporta il token di accesso federato da ADC in ACCESS_TOKEN:

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

Scambio di token STS REST diretto

Se stai integrando un client personalizzato senza SDK Google Cloud , scambia un token ID OIDC firmato (<var>IDP_ID_TOKEN</var>) direttamente con Security Token Service. Includi userProject nel campo options in modo che Google Cloud attribuisca il token al tuo progetto consumer:

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

Passaggio 4: verifica l'accesso federato all'API

Verifica che le credenziali federate, l'attribuzione userProject e le associazioni dei ruoli IAM funzionino elencando gli utenti nell'istanza di computing multipartitico. Poiché mpc.googleapis.com/users.list è incluso in roles/mpc.viewer, roles/mpc.editor e roles/mpc.admin, qualsiasi persona federata autorizzata può eseguire questo controllo:

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 .

Una risposta JSON 200 OK ({} su una nuova istanza o un elenco di users) conferma che la tua identità federata è autenticata e autorizzata a chiamare l'istanza di calcolo multipartitico.

Questo controllo utilizza solo IAM. Per confermare che l'istanza riconosce anche la tua identità come utente, verifica che uno degli utenti restituiti abbia l'identificatore principal:// nel campo principal. Per saperne di più, consulta Aggiungi identità federate come utenti v1beta.

Risoluzione dei problemi

Se si verificano errori di autenticazione o autorizzazione quando chiami il calcolo multipartitico con credenziali federate, verifica i seguenti requisiti:

Attribuzione del progetto utente (401 UNAUTHENTICATED: Unable to determine client project number)

  • Causa: le credenziali del pool di forza lavoro a livello di organizzazione non sono intrinsecamente associate a un singolo progetto Google Cloud , a meno che non venga specificato un progetto utente durante lo scambio di token o nella richiesta.
  • Risoluzione: includi options: {"userProject": "<var>PROJECT_ID</var>"} nel corpo della richiesta di scambio di token di Security Token Service (o --workforce-pool-user-project in gcloud iam workforce-pools create-cred-config) e includi l'intestazione X-Goog-User-Project: <var>PROJECT_ID</var> nelle chiamate API MPC.

Autorizzazione Service Usage mancante (403 PERMISSION_DENIED)

  • Causa: l'entità o il gruppo federato non dispone dell'autorizzazione per attribuire l'utilizzo dell'API al progetto consumer specificato in userProject o X-Goog-User-Project.
  • Risoluzione: concedi roles/serviceusage.serviceUsageConsumer al membro principal:// o principalSet:// nel progetto consumer (vedi Passaggio 2).

Mancata corrispondenza del progetto consumer (403 PERMISSION_DENIED: Project is not allowed to call the API through this host)

  • Causa: ogni endpoint dell'istanza di computing multipartitico dedicato accetta solo richieste dal progetto consumer configurato per l'istanza.
  • Risoluzione: verifica che <var>PROJECT_ID</var> sia nel percorso dell'URL della richiesta sia nell'intestazione userProject/X-Goog-User-Project corrisponda al progetto consumer di cui è stato eseguito il provisioning per l'istanza di computing multipartitico.

Credenziale non valida (401 UNAUTHENTICATED: Request credential is invalid)

  • Causa: un token OIDC di terze parti o un'asserzione SAML è stato inviato direttamente all'endpoint di calcolo multipartitico senza prima scambiarlo utilizzando Security Token Service.
  • Risoluzione: scambia la credenziale IdP tramite https://sts.googleapis.com/v1/token (o utilizza le Credenziali predefinite dell'applicazione) e passa il token di accesso Google Cloud risultante nell'intestazione Authorization: Bearer.

La policy di limitazione del dominio blocca le associazioni dei ruoli (400 FAILED_PRECONDITION)

  • Causa: la tua organizzazione Google Cloud applica la policy dell'organizzazioneconstraints/iam.allowedPolicyMemberDomains, che limita i domini delle entità a cui possono essere concessi i ruoli IAM sui progetti.
  • Risoluzione: chiedi all'amministratore delle policy dell'organizzazione di aggiungere il set di entità del pool di forza lavoro ai domini dei membri delle policy consentiti nel progetto o nell'organizzazione consumer oppure esegui il test in un progetto in cui constraints/iam.allowedPolicyMemberDomains consente il tuo pool di forza lavoro.

Passaggi successivi

  • Per creare utenti, team, policy di transazione e chiavi e per firmare le transazioni con la tua identità federata, segui la guida dell'utente di calcolo multipartitico. Imposta l'entità di ogni utente sull'identificatore principal:// descritto in Aggiungi identità federate come utenti v1beta.
  • La guida dell'utente recupera il token di accesso di ogni persona con gcloud auth print-access-token, che utilizza le credenziali gcloud gcloud CLI, non le Credenziali predefinite dell'applicazione. Esegui l'accesso di ogni utente federato con gcloud auth login --login-config, come mostrato nell'Opzione A del passaggio 3.
  • Scopri di più su ruoli utente, autorizzazioni IAM e condizioni a livello di risorsa in Sicurezza e autorizzazione.