Configurar a federação de identidade da carga de trabalho com certificados X.509

Este guia descreve como usar a federação de identidade da carga de trabalho com certificados X.509 emitidos pela autoridade certificadora (AC) para autenticar no Google Cloud e acessar recursos do Google Cloud .

Se as cargas de trabalho tiverem um certificado de cliente mTLS, será possível fazer a autenticação no Google Cloud registrando uma ou mais ACs com a federação de identidade da carga de trabalho como pontos de confiança. Também é possível registrar ACs intermediárias.

Ao usar a federação de identidade da carga de trabalho, é possível permitir que essas cargas de trabalho recebam credenciais de curta duração Google Cloud por uma conexão TLS mútua (mTLS). As cargas de trabalho podem usar essas credenciais de curta duração para acessar as APIs doGoogle Cloud .

Conceitos

Os conceitos de federação com base em certificados X.509 incluem:

  • Uma âncora de confiança é um certificado de AC considerado como raiz de confiança. Todas as cadeias de certificados do cliente precisam ser vinculadas a uma das âncoras de confiança.

  • Uma AC intermediária é um certificado de autoridade de certificação opcional que ajuda a criar a cadeia de certificados do cliente.

  • Um repositório de confiança contém os certificados de âncora de confiança e os certificados de AC intermediários que são usados para validar a cadeia de certificados do cliente. Uma AC emite certificados confiáveis para o cliente.

    Você pode fazer o upload dos seguintes tipos de certificados do cliente para o repositório de confiança:

    • Certificados emitidos por ACs de terceiros de sua escolha
    • Certificados emitidos pelas ACs particulares
    • Certificados assinados, conforme descrito em Criar certificados autoassinados

Antes de começar

Para começar a configurar a federação de identidade da carga de trabalho, faça isto:

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

    2. Recomendamos que você use um projeto dedicado para gerenciar pools de identidade da carga de trabalho e provedores.

  2. Verify that billing is enabled for your Google Cloud project.

    3. Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

Funções exigidas

Para receber as permissões necessárias para configurar a federação de identidade da carga de trabalho, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Como alternativa, o papel básico de Proprietário do IAM (roles/owner) também inclui permissões para configurar a federação de identidade. Não conceda papéis básicos em um ambiente de produção, recomendamos que você faça isso em um ambiente de desenvolvimento ou teste.

Criar um repositório de confiança

Nesta seção, mostramos como criar um repositório de confiança. Em geral, as etapas são as seguintes:

Gerar certificados autoassinados

Nesta seção, mostramos como gerar chaves e criar certificados assinados. Se você já tiver criado certificados, pule esta seção e continue com Formatar os certificados.

Esta seção usa comandos openssl para criar certificados raiz e intermediários.

Para gerar um certificado raiz e um certificado intermediário assinado com campos keyUsage e extendedKeyUsage válidos, faça o seguinte:

  1. Crie um arquivo de configuração openssl para criar seus certificados de assinatura. No mínimo, o arquivo é semelhante ao seguinte, mas é possível definir outros campos conforme necessário.

    cat > example.cnf << EOF
[req]
distinguished_name = empty_distinguished_name
[empty_distinguished_name]
# Kept empty to allow setting via -subj command-line argument.
[ca_exts]
basicConstraints=critical,CA:TRUE
keyUsage=keyCertSign
extendedKeyUsage=clientAuth
[leaf_exts]
keyUsage=critical,Digital Signature, Key Encipherment
basicConstraints=critical, CA:FALSE
EOF

  2. Crie o certificado raiz.

    openssl req -x509 \
    -new -sha256 -newkey rsa:2048 -nodes \
    -days 3650 -subj '/CN=root' \
    -config example.cnf \
    -extensions ca_exts \
    -keyout root.key -out root.cert

  3. Crie a solicitação de assinatura do certificado intermediário.

    openssl req \
    -new -sha256 -newkey rsa:2048 -nodes \
    -subj '/CN=int' \
    -config example.cnf \
    -extensions ca_exts \
    -keyout int.key -out int.req

  4. Crie o certificado intermediário.

    openssl x509 -req \
    -CAkey root.key -CA root.cert \
    -set_serial 1 \
    -days 3650 \
    -extfile example.cnf \
    -extensions ca_exts \
    -in int.req -out int.cert

  5. Crie a solicitação de assinatura do certificado folha.

    openssl req -new -sha256 -newkey rsa:2048 -nodes \
    -subj '/CN=example' \
    -config example.cnf \
    -extensions leaf_exts \
    -keyout leaf.key -out leaf.req

  6. Crie o certificado folha emitido pelo intermediário.

    openssl x509 -req \
    -CAkey int.key -CA int.cert \
    -set_serial 1 -days 3650 \
    -extfile example.cnf \
    -extensions leaf_exts \
    -in leaf.req -out leaf.cert

Formatar os certificados

Para incluir certificados novos ou atuais em um armazenamento de confiança, formate os certificados em uma string de uma linha e armazene-os em variáveis de ambiente. Os certificados precisam estar no formato PEM. Para formatar os certificados e armazená-los em variáveis de ambiente, faça o seguinte:

  1. Salve o certificado raiz como uma string de uma linha.

    export ROOT_CERT=$(cat root.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')

  2. Salve um certificado intermediário como uma string de uma linha.

    export INTERMEDIATE_CERT=$(cat int.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')

Criar o repositório de confiança

Nesta seção, você cria um repositório de confiança usando um arquivo formatado em YAML que contém as âncoras de confiança e as ACs intermediárias.

Esse arquivo contém o conteúdo do certificado das variáveis de ambiente que você criou em Formatar os certificados. Para adicionar mais âncoras de confiança, adicione mais entradas trustAnchors em trustStore. Para adicionar outros certificados de AC intermediários, adicione outras entradas de intermediateCas em trustStore.

Para criar o arquivo do repositório de confiança, execute o seguinte comando:

cat << EOF > trust_store.yaml
trustStore:
  trustAnchors:
  - pemCertificate: "${ROOT_CERT}"
  intermediateCas:
  - pemCertificate: "${INTERMEDIATE_CERT}"
EOF

Definir um mapeamento e uma condição de atributo

O certificado X.509 do cliente pode conter vários atributos. Selecione qual atributo você quer usar como identificador do assunto mapeando google.subject em Google Cloud para o atributo do certificado. Por exemplo, se o atributo no certificado for o nome comum do assunto, o mapeamento será o seguinte: google.subject=assertion.subject.dn.cn

Também é possível mapear outros atributos. Consulte esses atributos ao conceder acesso aos recursos.

Os mapeamentos de atributos podem usar os atributos no certificado do cliente, incluindo:

  • serialNumberHex: o número de série
  • subject.dn.cn: o nome comum do assunto
  • subject.dn.o: o nome da organização do assunto
  • subject.dn.ou: a última unidade organizacional do assunto
  • issuer.dn.cn: o nome comum do emissor
  • issuer.dn.o: o nome da organização emissora
  • issuer.dn.ou: a última unidade organizacional do emissor
  • san.dns: o primeiro nome de DNS do nome alternativo do assunto
  • san.uri: o primeiro URI do nome alternativo do assunto
  • sha256Fingerprint: hash do certificado folha SHA256 (Base64)

Mapeie um desses atributos para google.subject para identificar exclusivamente o assunto. Para se proteger contra ameaças de spoofing, escolha um atributo com um valor exclusivo que não possa ser alterado. Por padrão, o identificador google.subject é definido como o nome comum do assunto do certificado do cliente, assertion.subject.dn.cn.

Também é possível definir uma condição de atributo. As condições de atributo são expressões CEL que podem verificar atributos de declaração e atributos de destino. Se a condição do atributo for avaliada como true para uma determinada credencial, a credencial será aceita. Caso contrário, a credencial será rejeitada.

Use uma condição de atributo para restringir quais sujeitos podem usar a federação de identidade da carga de trabalho para conseguir tokens de curta duração Google Cloud.

Por exemplo, a condição a seguir restringe o acesso a certificados de cliente que contêm o ID SPIFFE spiffe://example/path:

assertion.san.uri=="spiffe://example/path"

Configurar a federação de identidade da carga de trabalho

Nesta seção, mostramos como configurar um pool de identidade da carga de trabalho e um provedor de pool de identidade da carga de trabalho. Você só precisa realizar essas etapas uma vez para cada repositório de confiança. É possível, então, usar o mesmo pool de identidade da carga de trabalho e servidor em várias cargas de trabalho e em vários projetos do Google Cloud .

Criar o pool de identidade da carga de trabalho

  1. Para criar um novo pool de identidade da carga de trabalho, execute o seguinte comando:

    gcloud iam workload-identity-pools create POOL_ID \
    --location="global" \
    --description="DESCRIPTION" \
    --display-name="DISPLAY_NAME"

    Substitua:

    • POOL_ID: o ID exclusivo do pool.
    • DISPLAY_NAME: o nome do pool.
    • DESCRIPTION: uma descrição do pool escolhido. Essa descrição aparece quando você concede acesso às identidades do pool.

Criar o provedor de pool de identidades da carga de trabalho

  1. Para adicionar um provedor de pool de identidade da carga de trabalho X.509, execute o seguinte comando:

    gcloud iam workload-identity-pools providers create-x509 PROVIDER_ID \
    --location=global \
    --workload-identity-pool="POOL_ID" \
    --trust-store-config-path="TRUST_STORE_CONFIG" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"

    Substitua:

    • PROVIDER_ID: um ID de provedor do pool de Identidade da carga de trabalho exclusivo de sua escolha.
    • POOL_ID: o ID do pool de Identidade da carga de trabalho que você criou anteriormente.
    • TRUST_STORE_CONFIG: o arquivo YAML do repositório de confiança.
    • MAPPINGS: uma lista separada por vírgulas de mapeamentos de atributos criados anteriormente neste guia. Por exemplo, google.subject=assertion.subject.dn.cn.
    • CONDITIONS: opcional. Uma condição de atributo que você criou anteriormente neste guia. Remova o parâmetro se você não tiver uma condição de atributo.

Configurar a aplicação da política de acesso baseado no contexto para a federação de identidade da carga de trabalho

É possível reforçar a segurança dos recursos contra ataques de repetição de token ativando o Acesso baseado no contexto, que aplica a validação de mTLS para solicitações de acesso. Nesse processo, uma vinculação mTLS incorpora políticas com base no contexto de transporte e usa o estado do certificado do cliente na sessão TLS para tomar decisões de autorização. Para a federação de identidade da carga de trabalho X.509, uma vinculação mTLS garante que todo o fluxo de autenticação esteja vinculado com segurança a uma carga de trabalho confiável. Isso reduz o risco de roubo de credenciais, porque a autenticação está vinculada a um endpoint específico e confiável.

Autenticar uma carga de trabalho

É necessário realizar essas etapas uma vez para cada carga de trabalho.

Permitir que a carga de trabalho externa acesse recursos do Google Cloud

Para fornecer à sua carga de trabalho acesso aos recursos do Google Cloud , recomendamos que você conceda ao principal acesso direto aos recursos. Nesse caso, o principal é o usuário federado. Alguns produtos do Google Cloud têm limitações de APIs do Google Cloud. Se sua carga de trabalho chamar um endpoint de API que apresenta limitação, será possível usar a identidade temporária de conta de serviço. Nesse caso, o principal é a conta de serviçoGoogle Cloud , que atua como a identidade. Você concede acesso à conta de serviço no recurso.

Acesso direto a recursos

É possível conceder acesso a uma identidade federada diretamente nos recursos usando o console Google Cloud ou a CLI gcloud.

Console

Para usar o console do Google Cloud para conceder papéis do IAM diretamente em um recurso, acesse a página do recurso e conceda o papel. O exemplo a seguir mostra como acessar a página do Cloud Storage e conceder o papel Leitor de objetos do Storage (roles/storage.objectViewer) a uma identidade federada diretamente em um bucket do Cloud Storage.

  1. No console do Google Cloud , acesse a página Buckets do Cloud Storage.

    Acessar buckets

  2. Na lista de buckets, clique no nome do bucket ao qual você quer conceder o papel.

  3. Selecione a guia Permissões na parte superior da página.

  4. Clique no botão Permitir acesso.

    A caixa de diálogo Adicionar principais será exibida.

  5. No campo Novos principais, insira uma ou mais identidades que precisam acessar seu bucket.

    Por assunto 

    principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT

    Substitua:

    • PROJECT_NUMBER: o número do projeto
    • POOL_ID: o ID do pool de carga de trabalho
    • SUBJECT: o sujeito individual mapeado do IdP, por exemplo, administrator@example.com

    Por grupo 

    principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP

    Substitua:

    • PROJECT_NUMBER: o número do projeto
    • WORKLOAD_POOL_ID: o ID do pool de carga de trabalho
    • GROUP: o grupo mapeado do IdP, por exemplo: administrator-group@example.com

    Por atributo 

    principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE

    Substitua:

    • PROJECT_NUMBER: o número do projeto
    • WORKLOAD_POOL_ID: o ID do pool de carga de trabalho
    • ATTRIBUTE_NAME: um dos atributos que foi mapeado do IdP
    • ATTRIBUTE_VALUE: o valor do atributo

  6. Escolha um papel ou mais no menu suspenso Selecionar um papel. Os papéis selecionados são exibidos no painel com uma breve descrição das permissões que eles concedem.

  7. Clique em Salvar.

gcloud

Para usar a gcloud CLI a fim de conceder papéis do IAM em um recurso de um projeto, faça isto:

  1. Consiga o número do projeto em que o recurso está definido.

    gcloud projects describe $(gcloud config get-value core/project) --format=value\(projectNumber\)

  2. Conceda acesso ao recurso.

    Para usar a gcloud CLI para conceder o papel de leitor de objetos de armazenamento (roles/storage.objectViewer) a identidades externas que atendam a determinados critérios, execute o comando a seguir.

    Por assunto

    gcloud storage buckets add-iam-policy-binding BUCKET_ID \
    --role=roles/storage.objectViewer \
    --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"

    Por grupo

    gcloud storage buckets add-iam-policy-binding BUCKET_ID \
    --role=roles/storage.objectViewer \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"

    Por atributo

    gcloud storage buckets add-iam-policy-binding BUCKET_ID \
    --role=roles/storage.objectViewer \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"

    Substitua:

    • BUCKET_ID: o bucket em que o acesso será concedido
    • PROJECT_NUMBER: o número do projeto que contém o pool de Identidade da carga de trabalho
    • POOL_ID: o ID do pool de identidade da carga de trabalho
    • SUBJECT: o valor esperado do atributo mapeado para google.subject
    • GROUP: o valor esperado do atributo mapeado para google.groups
    • ATTRIBUTE_NAME: o nome de um atributo personalizado no seu mapeamento de atributos
    • ATTRIBUTE_VALUE: o valor do atributo personalizado no seu mapeamento de atributos

    É possível conceder papéis em qualquer recurso do Google Cloud que seja compatível com políticas de permissão do IAM.

Identidade temporária de conta de serviço

  1. Para criar uma conta de serviço para a carga de trabalho externa, faça isto:

    1. Enable the IAM, Security Token Service, and Service Account Credentials APIs.

      Roles required to enable APIs

      To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

      Enable the APIs

    2. Crie uma conta de serviço que represente a carga de trabalho. Recomendamos que você use uma conta de serviço dedicada para cada carga de trabalho. A conta de serviço não precisa estar no mesmo projeto que o pool de Identidade da carga de trabalho, mas você precisa se referir ao projeto que contém a conta de serviço.

    3. Conceda à conta de serviço acesso a recursos que você quer que as identidades externas acessem.

  2. Para permitir que a identidade federada represente a conta de serviço, faça o seguinte:

Console

Para usar o console Google Cloud para conceder papéis do IAM a uma identidade federada com conta de serviço, faça o seguinte:

Conta de serviço no mesmo projeto

  1. Para conceder acesso usando a identidade temporária de conta de serviço no mesmo projeto, faça o seguinte:

    1. Acesse a página pools de Identidade da carga de trabalho.

      Acesse Pools de identidade da carga de trabalho

    2. Selecione Conceder acesso.

    3. Na caixa de diálogo Conceder acesso à conta de serviço, selecione Conceder acesso usando a identidade temporária de conta de serviço.

    4. Na lista Contas de serviço, selecione a conta de serviço para as identidades externas que serão representadas e faça isto:

    5. Para escolher quais identidades no pool podem representar a conta de serviço, realize uma das seguintes ações:

      • Para permitir que apenas identidades específicas do pool de Identidade da carga de trabalho representem a conta de serviço, selecione Somente identidades correspondentes ao filtro.

      • Na lista Nome do atributo, selecione o atributo que você quer filtrar.

      • No campo Valor do atributo, insira o valor esperado do atributo. Por exemplo, se você usar um google.subject=assertion.sub de mapeamento de atributos, defina o nome do Atributo com subject e o Valor do atributo com o valor da declaração sub em tokens emitidos pelo seu provedor de identidade externo.

    6. Para salvar a configuração, clique em Salvar e em Dispensar.

Conta de serviço em um projeto diferente

  1. Para conceder acesso usando a identidade temporária de conta de serviço em um projeto diferente, faça o seguinte:

    1. Acesse a página Contas de serviço.

      Acessar a página "Contas de serviço"

    2. Selecione a conta de serviço que você quer representar.

    3. Clique em Gerenciar acesso.

    4. Clique em Adicionar principal.

    5. No campo Novo principal, insira um dos seguintes identificadores principais para as identidades no pool que vão representar a identidade da conta de serviço.

      Por assunto 

      principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT

      Substitua:

      • PROJECT_NUMBER: o número do projeto
      • POOL_ID: o ID do pool de carga de trabalho
      • SUBJECT: o sujeito individual mapeado do IdP, por exemplo, administrator@example.com

      Por grupo 

      principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP

      Substitua:

      • PROJECT_NUMBER: o número do projeto
      • WORKLOAD_POOL_ID: o ID do pool de carga de trabalho
      • GROUP: o grupo mapeado do IdP, por exemplo: administrator-group@example.com

      Por atributo 

      principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE

      Substitua:

      • PROJECT_NUMBER: o número do projeto
      • WORKLOAD_POOL_ID: o ID do pool de carga de trabalho
      • ATTRIBUTE_NAME: um dos atributos que foi mapeado do IdP
      • ATTRIBUTE_VALUE: o valor do atributo

      Por pool

      principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*

      Substitua:

      • PROJECT_NUMBER: o número do projeto
      • WORKLOAD_POOL_ID: o ID do pool de carga de trabalho

    6. Em Selecionar um papel, selecione a função de usuário da Identidade da carga de trabalho (roles/iam.workloadIdentityUser).

    7. Para salvar a configuração, clique em Salvar.

gcloud

Para conceder o papel de usuário da Identidade da carga de trabalho (roles/iam.workloadIdentityUser) a um principal federado ou conjunto de principais, execute o seguinte comando. Para saber mais sobre os identificadores principais da federação de identidade da carga de trabalho, consulte Tipos principais.

Por assunto

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"

Por grupo

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"

Por atributo

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"

Substitua:

  • SERVICE_ACCOUNT_EMAIL: o endereço de e-mail da conta de serviço
  • PROJECT_NUMBER: o número do projeto que contém o pool de Identidade da carga de trabalho
  • POOL_ID: o ID do pool de identidade da carga de trabalho
  • SUBJECT: o valor esperado do atributo mapeado para google.subject
  • GROUP: o valor esperado do atributo mapeado para google.groups
  • ATTRIBUTE_NAME: o nome de um atributo personalizado no seu mapeamento de atributos
  • ATTRIBUTE_VALUE: o valor do atributo personalizado no seu mapeamento de atributos

Fazer o download ou criar uma configuração de credencial

As bibliotecas de cliente do Cloud e a CLI gcloud podem receber automaticamente credenciais externas e usá-las para representar uma conta de serviço. Para permitir que bibliotecas e ferramentas concluam esse processo, você precisa fornecer um arquivo de configuração de credenciais. Esse arquivo fornece as seguintes informações:

  • De onde receber credenciais externas
  • Qual pool de identidades de carga de trabalho e provedor usar
  • Qual conta de serviço representar

Além disso, para a federação de certificados X.509, é necessário um arquivo de configuração de certificado. Esse arquivo contém caminhos para o certificado de cliente X.509 e os arquivos de chave privada.

Crie arquivos de configuração de credenciais e certificados que permitam que a biblioteca receba tokens de acesso usando certificados X.509.

Acesso direto a recursos

Para criar arquivos de configuração de credenciais e certificados para acesso direto a recursos usando gcloud iam workload-identity-pools create-cred-config, faça o seguinte:

gcloud iam workload-identity-pools create-cred-config \
  projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --credential-cert-path=CLIENT_CERT_PATH \
    --credential-cert-private-key-path=CLIENT_PRIVATE_KEY_PATH \
    --credential-cert-trust-chain-path=TRUST_CHAIN_PATH \
    --output-file=FILEPATH.json

Substitua:

  • PROJECT_NUMBER: o número do projeto que contém o pool de Identidade da carga de trabalho
  • POOL_ID: o ID do pool de identidade da carga de trabalho
  • PROVIDER_ID: o ID do provedor do pool de Identidade da carga de trabalho
  • CLIENT_CERT_PATH: o caminho do arquivo de certificado
  • CLIENT_PRIVATE_KEY_PATH: o caminho do arquivo de chave privada do certificado do cliente.
  • TRUST_CHAIN_PATH: opcional. O caminho do arquivo da cadeia de confiança que contém certificados intermediários não configurados no provedor x509.
  • FILEPATH: o arquivo em que a configuração será salva.

A execução desse comando também cria um arquivo de configuração de certificado e o armazena no local padrão da CLI gcloud:

  • Linux e macOS: ~/.config/gcloud/certificate_config.json

  • Windows: %APPDATA%\gcloud\certificate_config.json

Identidade temporária de conta de serviço

Para criar arquivos de configuração de credenciais e certificados com a identidade temporária de conta de serviço usando gcloud iam workload-identity-pools create-cred-config, faça o seguinte:

gcloud iam workload-identity-pools create-cred-config \
  projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --credential-cert-path=CLIENT_CERT_PATH \
    --credential-cert-private-key-path=CLIENT_KEY_PATH \
    --credential-cert-trust-chain-path=TRUST_CHAIN_PATH \
    --output-file=FILEPATH.json

Substitua:

  • PROJECT_NUMBER: o número do projeto que contém o pool de Identidade da carga de trabalho
  • POOL_ID: o ID do pool de identidade da carga de trabalho
  • PROVIDER_ID: o ID do provedor do pool de Identidade da carga de trabalho
  • SERVICE_ACCOUNT_EMAIL: se você usa a identidade temporária de conta de serviço, substitua pelo endereço de e-mail da conta de serviço.
  • SERVICE_ACCOUNT_TOKEN_LIFETIME: o ciclo de vida do token de acesso da conta de serviço, em segundos, se você usa a identidade temporária de conta de serviço. Se omitido, o padrão será de uma hora. Omita essa flag se você não usa a identidade temporária de conta de serviço. Para especificar um ciclo de vida com mais de uma hora, configure a restrição da política organizacional constraints/iam.allowServiceAccountCredentialLifetimeExtension.
  • CLIENT_CERT_PATH: o caminho do arquivo de certificado
  • CLIENT_PRIVATE_KEY_PATH: o caminho do arquivo de chave privada do certificado do cliente.
  • TRUST_CHAIN_PATH: opcional. O caminho do arquivo da cadeia de confiança que contém certificados intermediários não configurados no provedor x509.
  • FILEPATH: o arquivo em que a configuração será salva.

A execução desse comando também cria um arquivo de configuração de certificado e o armazena no local padrão da CLI do Google Cloud:

  • Linux e macOS: ~/.config/gcloud/certificate_config.json

  • Windows: %APPDATA%\gcloud\certificate_config.json

Usar a configuração de credencial para acessar Google Cloud

Para permitir que as ferramentas e as bibliotecas de cliente usem a configuração da sua credencial, faça o seguinte: Para saber mais sobre Application Default Credentials, consulte Como Application Default Credentials funcionam.

  1. Inicialize uma variável de ambiente GOOGLE_APPLICATION_CREDENTIALS e defina-a como o arquivo de configuração de credenciais:

    Bash

      export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
    Substitua FILEPATH pelo caminho relativo do arquivo de configuração de credenciais.

    PowerShell

      $env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
    Substitua FILEPATH pelo caminho relativo do arquivo de configuração de credenciais.

  2. Verifique se a biblioteca de cliente consegue encontrar o arquivo de configuração do certificado. O arquivo de configuração do certificado está localizado em um dos seguintes caminhos:

    • O caminho padrão da CLI gcloud:

      • Linux e macOS: ~/.config/gcloud/certificate_config.json

      • Windows: %APPDATA%\gcloud\certificate_config.json

    • O caminho definido na variável de ambiente GOOGLE_API_CERTIFICATE_CONFIG.

  3. Use as seguintes bibliotecas de cliente do Cloud compatíveis com a federação de identidade da carga de trabalho com certificados X.509.

    Go

    As bibliotecas de cliente para Go são compatíveis com a federação de identidade da carga de trabalho X.509 se usarem a versão 0.16.0 ou mais recente do módulo cloud.google.com/go/auth e a versão 0.189.0 do módulo google.golang.org/api.

    Para verificar qual versão desses módulos a biblioteca de cliente usa, execute o seguinte comando no diretório que contém o arquivo go.mod do módulo:

      go list -m cloud.google.com/go/auth
  go list -m cloud.google.com/api

    Python

    As bibliotecas de cliente para Python são compatíveis com a federação de identidade da carga de trabalho X.509 se usarem a versão 2.39.0 ou mais recente do pacote google-auth.

    Para verificar qual versão desse pacote sua biblioteca de cliente usa, execute o seguinte comando no ambiente em que o pacote está instalado:

      pip show google-auth

    Para especificar um ID de projeto para o cliente de autenticação, defina a variável de ambiente GOOGLE_CLOUD_PROJECT ou permita que o cliente encontre o ID do projeto automaticamente. Para encontrar o ID do projeto automaticamente, a conta de serviço no arquivo de configuração precisa ter o papel de Navegador (roles/browser) ou um papel com permissões equivalentes no projeto. Para ver detalhes, consulte o guia do usuário do pacote google-auth.

  4. Se a carga de trabalho for executada no macOS, defina CLOUDSDK_PYTHON_SITEPACKAGES=1 para configurar a CLI gcloud de modo a usar bibliotecas Python fora do diretório de instalação.

  5. Para autenticar usando a CLI gcloud, execute o seguinte comando:

    gcloud auth login --cred-file=FILEPATH.json

    Substitua FILEPATH pelo caminho para o arquivo de configuração de credencial.

    O suporte para a federação de identidade da carga de trabalho X.509 na CLI gcloud está disponível na versão 538.0 e posteriores da gcloud CLI.

Receber um token de acesso usando uma solicitação simples para acessar Google Cloud

Criar a cadeia de confiança

Esta etapa mostra como criar a cadeia de confiança. Você transmite a cadeia de confiança no campo subject_token ao chamar o Serviço de token de segurança em uma solicitação simples.

Formate os certificados que precisam ser incluídos na cadeia como uma lista formatada em JSON, conforme especificado na RFC 7515. O certificado folha usado para o handshake de mTLS precisa ser especificado como o primeiro item. Cada certificado no pacote precisa ser uma string codificada em base64.

  1. Salve o certificado folha e o certificado intermediário em strings codificadas em base64.

    export LEAF_CERT=$(openssl x509 -in leaf.cert -out leaf.der -outform DER && cat leaf.der | openssl enc -base64 -A)

    export INTERMEDIATE_CERT=$(openssl x509 -in int.cert -out int.der -outform DER && cat int.der | openssl enc -base64 -A)

  2. Crie uma lista de strings formatada em JSON que pode ser transmitida como subject_token na chamada ao Security Token Service, mais adiante neste documento.

    export TRUST_CHAIN="[\\\"${LEAF_CERT}\\\", \\\"${INTERMEDIATE_CERT}\\\"]"

Receber token de acesso

Para receber o token de acesso, faça o seguinte:

  1. Realize a troca de token com mTLS e o certificado do cliente:

    curl --key CLIENT_CERT_KEY \
--cert CLIENT_CERT \
--request POST 'https://sts.mtls.googleapis.com/v1/token' \
--header "Content-Type: application/json" \
--data-raw '{
    "subject_token_type": "urn:ietf:params:oauth:token-type:mtls",
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "audience": "WORKLOAD_IDENTITY_POOL_URI",
    "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "scope": "https://www.googleapis.com/auth/cloud-platform",
    "subject_token": "TRUST_CHAIN"
}'

    Substitua:

    • CLIENT_CERT_KEY: a chave privada do certificado do cliente
    • CLIENT_CERT: certificado do cliente

    • WORKLOAD_IDENTITY_POOL_URI: o URL do provedor do pool de identidades da carga de trabalho no seguinte formato:

      //iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

    • TRUST_CHAIN: a cadeia de confiança necessária para verificar o certificado de folha precisa incluir pelo menos CLIENT_CERT como o primeiro item. Se você seguiu as instruções na seção Formatar os certificados, substitua TRUST_CHAIN por '"${TRUST_CHAIN}"'.

  2. Use o token de acesso de portador gerado na etapa anterior para acessar recursos doGoogle Cloud . Por exemplo:

    curl -X GET 'https://storage.googleapis.com/my_object' -H "Authorization: Bearer $ACCESS_TOKEN"

Limites

A tabela a seguir lista os limites.

Item Limite Observações
Número de âncoras de confiança 3 Cada certificado não pode exceder 32 KB.
Número de certificados intermediários 10 Cada certificado não pode exceder 32 KB.
Número de restrições de nome permitidas durante a validação de certificados raiz e intermediários 10
Certificados intermediários que compartilham as mesmas informações de Assunto e de Chave pública do assunto 5 Esse limite é para cada repositório de confiança.
Profundidade da cadeia de certificados 5 A profundidade máxima de uma cadeia de certificados, incluindo os certificados raiz e do cliente.
Número de vezes que os certificados intermediários podem ser avaliados ao tentar criar a cadeia de confiança 100
Chaves de certificados enviados e passados do cliente

As chaves RSA podem ter de 2.048 a 4.096 bits.

Os certificados ECDSA precisam usar curvas P-256 ou P-384.

 RSA-2048 e P-256 são recomendados para casos de uso normais. Use outros para práticas recomendadas de segurança.
Ciclo de vida máximo do certificado de folha 390 dias. Certificados de folha emitidos há mais de 390 dias serão rejeitados.

A seguir