O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Configurar a federação de identidade de colaboradores (BYOID)

Neste guia, explicamos como configurar a identidade fornecida pelo usuário (BYOID) para a API Multi-party Compute usando a federação de identidade de colaboradores e a federação de identidade da carga de trabalho. Com a federação de identidade, usuários humanos e cargas de trabalho de signatários automatizados podem se autenticar na computação multipartidária usando o provedor de identidade (IdP) externo da sua organização, como Okta, Microsoft Entra ID ou Ping Identity. Não é necessário criar Contas do Google nem gerenciar chaves de conta de serviço de longa duração.

Visão geral

A federação de identidade se integra ao modelo de segurança de defesa em profundidade da computação multipartidária nas seguintes camadas:

Autorização do Edge Identity and Access Management (IAM): os autores de chamadas trocam credenciais de um IdP externo do OpenID Connect (OIDC) ou SAML 2.0 com o Security Token Service do Google Cloud por um token de acesso federado de curta duração. O gateway de API do Google Cloud avalia as vinculações de papéis do IAM em relação ao URI do principal federado antes de encaminhar solicitações para sua instância de computação multipartidária e propaga a identidade federada (principalSubject) para os Registros de auditoria do Cloud.
Segregação de funções e aprovação criptográfica: os papéis do IAM separam o provisionamento administrativo (roles/mpc.admin), a participação operacional (roles/mpc.editor) e a supervisão somente leitura (roles/mpc.viewer). Na sua instância, os administradores, autores de políticas e signatários também precisam de um usuário com um papel (ADMIN, POLICY_AUTHOR ou SIGNER) que a instância verifica para métodos que agem em nome de um usuário, e as aprovações precisam ser assinadas com a chave de autorização registrada nesse usuário. Para mais informações, consulte Como uma solicitação é autorizada.

Dependendo do tipo de autor da chamada, é possível usar dois mecanismos de federação de identidade:

Federação de identidade de colaboradores (locations/global/workforcePools/...): autentica usuários humanos (administradores, autores de políticas, signatários e compliance) usando pools de colaboradores no nível da organização mapeados para o IdP corporativo. Neste guia, mostramos como configurar a federação de identidade de colaboradores de ponta a ponta.
Federação de identidade da carga de trabalho (projects/.../locations/global/workloadIdentityPools/...): autentica cargas de trabalho automatizadas (como daemons de coassinatura headless em execução na AWS, no Azure ou no Kubernetes) usando pools de identidade da carga de trabalho no nível do projeto.

Para mais informações sobre como os papéis do IAM são mapeados para as personas da computação multipartidária, consulte Segurança e autorização.

Antes de começar

Antes de começar, verifique se você tem:

Uma organização do Google Cloud e um projeto de consumidor integrados à computação multipartidária.
A CLI gcloud e o jq instalados, e o gcloud autenticado com uma conta de administrador que tenha os seguintes papéis:
- Administrador de pool de colaboradores (roles/iam.workforcePoolAdmin) na sua organização do Google Cloud (se você estiver criando um novo pool de colaboradores na Etapa 1).
- Administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin) e Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin) no projeto do consumidor.

As APIs necessárias ativadas no projeto do consumidor:

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

Um aplicativo externo OIDC ou SAML 2.0 configurado no IdP corporativo. Se você planeja usar o login interativo do navegador com a CLI gcloud, configure o URI de redirecionamento Google Cloud no aplicativo IdP (consulte os guias de configuração do Okta e do Microsoft Entra ID).

Configuração

Atualize as variáveis a seguir para preencher os comandos neste guia.

Parâmetros de configuração obrigatórios

Personalize esses parâmetros para que correspondam ao seu ambiente do Google Cloud e à configuração do IdP externo.

Parâmetro	Valor	Descrição
ID da organização	`123456789012`	O ID da organização numérico do Google Cloud .
ID do projeto	`my-project`	O ID do projeto do consumidor registrado para sua instância de computação multipartidária.
ID do domínio	`67317436-0f29-ba9e-9146-d11c0bd8df9b`	O ID de domínio exclusivo atribuído à sua instância de computação multipartidária.
ID do caminho da instância	`mpc-unit-bob-123`	O ID do caminho da instância atribuído à sua instância de computação multipartidária.
Local	`us-central1`	Local de implantação (`us-central1`). Para mais informações, consulte Locais de computação multipartidária.
ID do pool de colaboradores	`mpc-workforce-pool`	O ID do pool de identidade de colaboradores no nível da organização.
ID do provedor	`mpc-oidc-provider`	O ID do provedor do pool de identidade de colaboradores.
URI do emissor do IdP	`https://idp.example.com`	O URI do emissor do IdP do OIDC externo.
ID do cliente do IdP	`mpc-client`	O ID do cliente OAuth 2.0 configurado no IdP externo.

Etapa 1: configurar um pool e um provedor de identidade de colaboradores

Os pools de identidade de colaboradores (locations/global/workforcePools/mpc-workforce-pool) são recursos no nível da organização que são mapeados para o locatário do IdP corporativo. Não é necessário criar pools de colaboradores separados para cada projeto ou papel.

Crie um pool de identidades de colaboradores na sua organização do Google Cloud :

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

Crie um provedor de pool de colaboradores OIDC que confie no IdP externo e mapeie as declarações de assunto e grupo:
```
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"
```
Observação : por padrão, o Security Token Service descobre e alterna as chaves de assinatura públicas do endpoint /.well-known/openid-configuration do IdP. Se você estiver testando com um emissor OIDC off-line ou sintético que não seja acessível publicamente, transmita --jwk-json-path="<var>PATH_TO_JWK_FILE</var>", substituindo <var>PATH_TO_JWK_FILE</var> pelo caminho local para o arquivo público do conjunto de chaves da Web JSON (JWKS) do emissor. Para provedores SAML 2.0, use gcloud iam workforce-pools providers create-saml com --idp-metadata-path.

Etapa 2: conceder papéis do IAM aos principais federados

Para chamar a API MPC, os principais federados precisam de dois tipos de vinculações de papéis do IAM no projeto do consumidor (my-project):

Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer), que autoriza a identidade federada a atribuir a cota e o faturamento da API ao projeto do consumidor.
Um papel de computação multipartidária (roles/mpc.admin, roles/mpc.editor ou roles/mpc.viewer), que autoriza operações específicas de computação multipartidária.

Na produção, vincule papéis do IAM a grupos de IdP distintos no pool de colaboradores:

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

Cargas de trabalho de signatário automatizadas (federação de identidade da carga de trabalho)

Se você executar daemons de coassinatura automatizados fora do Google Cloud (por exemplo, na AWS, no Azure ou no Kubernetes), configure um pool de identidade da carga de trabalho e um provedor com escopo de projeto. Conceda roles/serviceusage.serviceUsageConsumer e roles/mpc.editor ao principal da carga de trabalho (principal://iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/subject/<var>SIGNER_NODE_SUBJECT</var>, substituindo <var>PROJECT_NUMBER</var>, <var>WORKLOAD_POOL_ID</var> e <var>SIGNER_NODE_SUBJECT</var> pelo número do projeto, ID do pool de cargas de trabalho e declaração sub da carga de trabalho) e gere um arquivo do Application Default Credentials usando gcloud iam workload-identity-pools create-cred-config.

Adicionar identidades federadas como usuários v1beta

Na API v1beta, os papéis do IAM desta etapa permitem que uma identidade federada chame sua instância. Para atuar dentro da instância como administrador, autor de políticas ou signatário, a identidade também precisa de um usuário. A instância identifica o autor da chamada ao comparar o principal dele com o campo principal de cada usuário.

Para uma identidade federada de colaboradores, defina principal como o identificador principal do assunto da identidade:

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

Substitua SUBJECT_ID pelo valor que seu provedor mapeia para google.subject. Com o mapeamento de atributos na Etapa 1, é a declaração sub do token de ID do usuário.

Ao definir principal, tenha em mente o seguinte:

Use um identificador principal://, não um identificador principalSet://. Um usuário é uma pessoa. Os identificadores de grupo e pool, como principalSet://.../group/mpc-signers, funcionam em vinculações de papéis do IAM, mas nunca correspondem a um autor da chamada. Portanto, um usuário criado com um deles não pode atuar na instância.
Corresponder exatamente ao assunto. A instância compara os assuntos de força de trabalho e de carga de trabalho diferenciando maiúsculas de minúsculas. Portanto, copie o assunto conforme emitido pelo IdP. Os e-mails da Conta do Google, como alice@example.com, são comparados sem diferenciar maiúsculas de minúsculas.
Não será possível mudar o principal depois. Para mudar a identidade de um usuário, desative-o e crie um novo.

Etapa 3: autenticar e receber um token de acesso federado

A API MPC não aceita tokens OIDC ou declarações SAML diretamente do seu IdP. Troque a credencial do IdP com o Security Token Service por um token de acesso federado do Google Cloud antes de chamar o endpoint da instância de computação multipartidária (*.mpc.goog).

É possível receber e gerenciar tokens de acesso federados automaticamente usando o Application Default Credentials (ADC) e a CLI gcloud ou de maneira programática usando a API Security Token Service.

Application Default Credentials e CLI gcloud

Em aplicativos cliente de produção e sessões interativas da CLI, use um arquivo de configuração para que o SDK Google Cloud e as bibliotecas de cliente do Cloud processem automaticamente a troca, o armazenamento em cache e as atualizações de tokens do Security Token Service em segundo plano.

Opção A: login interativo no navegador

Gere um arquivo de configuração de login e autentique a CLI gcloud e o Application Default Credentials (ADC) com seu IdP corporativo:

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"

Opção B: login não interativo com um arquivo de configuração de credenciais (ADC)

Se um processo externo fornecer e atualizar um token OIDC assinado em um arquivo local (por exemplo, /var/run/secrets/tokens/oidc-token) antes que o token expire, gere um arquivo de configuração de credencial externa:

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"

Exporte o token de acesso para solicitações curl:

Depois de concluir a Opção A ou a Opção B, exporte o token de acesso federado do ADC para ACCESS_TOKEN:

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

Troca direta de token STS REST

Se você estiver integrando um cliente personalizado sem os SDKs do Google Cloud , troque um token de ID do OIDC assinado (<var>IDP_ID_TOKEN</var>) diretamente com o Security Token Service. Inclua userProject no campo options para que o Google Cloud atribua o token ao projeto do consumidor:

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

Etapa 4: verificar o acesso federado à API

Verifique se as credenciais federadas, a atribuição de userProject e as vinculações de papéis do IAM estão funcionando listando os usuários na instância de computação multipartidária. Como mpc.googleapis.com/users.list está incluído em roles/mpc.viewer, roles/mpc.editor e roles/mpc.admin, qualquer persona federada autorizada pode executar esta verificação:

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 .

Uma resposta JSON 200 OK ({} em uma nova instância ou uma lista de users) confirma que sua identidade federada está autenticada e autorizada a chamar sua instância de computação multipartidária.

Essa verificação usa apenas o IAM. Para confirmar que a instância também reconhece sua identidade como usuário, verifique se um dos usuários retornados tem seu identificador principal:// no campo principal. Para mais informações, consulte Adicionar identidades federadas como usuários v1beta.

Solução de problemas

Se você encontrar erros de autenticação ou permissão ao chamar a computação multipartidária com credenciais federadas, verifique os seguintes requisitos:

Atribuição de projeto do usuário (`401 UNAUTHENTICATED: Unable to determine client project number`)

Causa: as credenciais do pool de colaboradores no nível da organização não estão vinculadas a um único projeto do Google Cloud , a menos que um projeto de usuário seja especificado durante a troca de tokens ou na solicitação.
Resolução: inclua options: {"userProject": "<var>PROJECT_ID</var>"} no corpo da solicitação de troca de token do Security Token Service (ou --workforce-pool-user-project em gcloud iam workforce-pools create-cred-config) e inclua o cabeçalho X-Goog-User-Project: <var>PROJECT_ID</var> nas chamadas de API do MPC.

Permissão de uso do serviço ausente (`403 PERMISSION_DENIED`)

Causa: o principal ou grupo federado não tem permissão para atribuir o uso da API ao projeto do consumidor especificado em userProject ou X-Goog-User-Project.
Resolução: conceda roles/serviceusage.serviceUsageConsumer ao membro principal:// ou principalSet:// no projeto do consumidor (consulte a Etapa 2).

Incompatibilidade do projeto do consumidor (`403 PERMISSION_DENIED: Project is not allowed to call the API through this host`)

Causa: cada endpoint de instância de computação multipartidária dedicada aceita apenas solicitações do projeto do consumidor configurado para essa instância.
Resolução: verifique se <var>PROJECT_ID</var> no caminho do URL da solicitação e no cabeçalho userProject / X-Goog-User-Project corresponde ao projeto de consumidor provisionado para sua instância de computação multipartidária.

Credencial inválida (`401 UNAUTHENTICATED: Request credential is invalid`)

Causa: um token OIDC de terceiros ou uma declaração SAML foi enviada diretamente ao endpoint de computação multipartidária sem antes ser trocada usando o Security Token Service.
Resolução: troque sua credencial do IdP por meio de https://sts.googleapis.com/v1/token (ou use o Application Default Credentials) e transmita o token de acesso Google Cloud resultante no cabeçalho Authorization: Bearer.

A política de compartilhamento restrito de domínio bloqueia as vinculações de papéis (`400 FAILED_PRECONDITION`)

Causa: sua organização do Google Cloud aplica a política da organização constraints/iam.allowedPolicyMemberDomains, que restringe quais domínios principais podem receber papéis do IAM em projetos.
Resolução: peça ao administrador de políticas da organização para adicionar o conjunto de principais do pool de colaboradores aos domínios de membros da política permitidos no projeto ou na organização do consumidor ou teste em um projeto em que constraints/iam.allowedPolicyMemberDomains permita o pool de colaboradores.

A seguir

Para criar usuários, equipes, políticas de transação e chaves, além de assinar transações com sua identidade federada, siga o Guia do usuário de computação multipartidária. Defina o principal de cada usuário como o identificador principal:// descrito em Adicionar identidades federadas como usuários v1beta.
O guia do usuário recupera o token de acesso de cada persona com gcloud auth print-access-token, que usa as credenciais da CLI gcloud, não o Application Default Credentials. Faça login de cada usuário federado com gcloud auth login --login-config, conforme mostrado na Opção A da Etapa 3.
Saiba mais sobre funções de usuário, permissões do IAM e condições no nível do recurso em Segurança e autorização.