Configure a Workload Identity Federation com certificados X.509

Este guia descreve como usar a Workload Identity Federation com certificados X.509 emitidos pela sua autoridade de certificação (AC) para autenticar e aceder Trusted Cloud Trusted Cloud a recursos.

Se as suas cargas de trabalho tiverem um certificado de cliente mTLS, pode autenticar-se em Trusted Cloud registando uma ou mais CAs na Workload Identity Federation como âncoras de confiança. Também pode registar ACs intermédias.

Ao usar a Workload Identity Federation, pode permitir que estas cargas de trabalho obtenham credenciais de curta duração através de uma ligação TLS mútua (mTLS). Trusted Cloud As cargas de trabalho podem usar estas credenciais de curta duração para aceder às APIs Trusted Cloud .

Conceitos

Os conceitos de federação baseados em certificados X.509 incluem o seguinte:

• Uma âncora de confiança é um certificado de AC considerado como a raiz de confiança. Todas as cadeias de certificados de cliente devem estar encadeadas até um dos pontos de confiança.

• Uma AC intermédia é um certificado da autoridade de certificação opcional que ajuda a criar a cadeia de certificados de cliente.

• Uma loja de confiança contém os certificados das âncoras de confiança e os certificados da AC intermédios que são usados para validar a cadeia de certificados do cliente. Uma AC emite certificados fidedignos para o cliente.

  Pode carregar os seguintes tipos de certificados de cliente para o repositório de confiança:

  • Certificados emitidos por ACs de terceiros à sua escolha
  • Certificados emitidos pelas suas ACs privadas
  • Certificados assinados, conforme descrito no artigo Crie certificados autoassinados

Antes de começar

Para começar a configurar a Workload Identity Federation, faça o seguinte:

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

   Go to project selector

Recomendamos que use um projeto dedicado para gerir os fornecedores e os conjuntos de identidades de carga de trabalho.

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

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

   Enable the APIs

Funções necessárias

Para obter as autorizações de que precisa para configurar a Workload Identity Federation, peça ao seu administrador para lhe conceder as seguintes funções de IAM no projeto:

• Administrador do Workload Identity Pool (roles/iam.workloadIdentityPoolAdmin)
• Administrador da conta de serviço (roles/iam.serviceAccountAdmin)

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Em alternativa, a função básica de proprietário do IAM (roles/owner) também inclui autorizações para configurar a federação de identidades. Não deve conceder funções básicas num ambiente de produção, mas pode concedê-las num ambiente de desenvolvimento ou teste.

Crie um repositório de confiança

Esta secção mostra como criar um repositório de confiança. A um nível elevado, os passos são os seguintes:

• Gere certificados autoassinados
• Formate os certificados
• Crie o repositório de confiança

Gere certificados autoassinados

Esta secção mostra-lhe como gerar chaves e criar certificados assinados. Se já tiver criado certificados, pode ignorar esta secção e continuar com Formatar os certificados.

Esta secção usa comandos openssl para criar certificados de raiz e intermédios.

Para gerar um certificado de raiz e um certificado intermédio assinado com campos keyUsage e extendedKeyUsage válidos, faça o seguinte:

1. Crie um ficheiro de configuração openssl para criar os seus certificados de assinatura. No mínimo, o ficheiro é semelhante ao seguinte, mas pode definir campos adicionais 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 de 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 o pedido de assinatura para o certificado intermédio.

   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 intermédio.

   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 o pedido de assinatura do certificado de 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 final emitido pelo certificado intermédio.

   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
   

Formate os certificados

Para incluir certificados novos ou existentes numa loja fidedigna, formate os certificados numa string de uma linha e armazene-os em variáveis de ambiente. Os certificados têm de estar no formato PEM. Para formatar os certificados e armazená-los em variáveis de ambiente, faça o seguinte:

1. Guarde o certificado de 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. Guarde um certificado intermédio 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')
   

Crie o repositório de confiança

Nesta secção, cria um repositório fidedigno através de um ficheiro formatado em YAML que contém as suas raízes de confiança e ACs intermédias.

Este ficheiro contém o conteúdo do certificado das variáveis de ambiente que criou em Formate os certificados. Para adicionar âncoras de confiança adicionais, adicione entradas trustAnchors adicionais em trustStore. Para adicionar certificados de AC intermédios adicionais, adicione entradas intermediateCas adicionais em trustStore.

Para criar o ficheiro da loja de confiança, execute o seguinte comando:

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

Defina um mapeamento de atributos e uma condição

O certificado X.509 do cliente pode conter vários atributos. Tem de selecionar o atributo que quer usar como identificador do assunto mapeando google.subject em Trusted Cloud para o atributo do seu certificado. Por exemplo, se o atributo no certificado for o nome comum do assunto, o mapeamento seria o seguinte: google.subject=assertion.subject.dn.cn

Opcionalmente, pode mapear atributos adicionais. Em seguida, pode consultar estes atributos quando conceder acesso a recursos.

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

• 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 DNS do nome alternativo do requerente
• san.uri: o primeiro URI do nome alternativo do requerente
• sha256Fingerprint: hash do certificado de folha SHA256 (Base64)

Tem de mapear um destes atributos para google.subject para identificar exclusivamente o assunto. Para se proteger contra ameaças de roubo de identidade, escolha um atributo com um valor exclusivo que não possa ser alterado. Por predefinição, o identificador google.subject está definido como o nome comum do assunto do certificado de cliente, assertion.subject.dn.cn.

Opcionalmente, pode definir uma condição de atributo. As condições de atributos são expressões CEL que podem verificar atributos de afirmação e atributos de destino. Se a condição do atributo for avaliada como true para uma determinada credencial, a credencial é aceite. Caso contrário, a credencial é rejeitada.

Pode usar uma condição de atributo para restringir os assuntos que podem usar a Workload Identity Federation para obter tokens Trusted Cloudde curta duração.

Por exemplo, a seguinte condição restringe o acesso a certificados de cliente que contenham o ID SPIFFE spiffe://example/path:

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

Configure a Workload Identity Federation

Esta secção mostra como configurar um Workload Identity Pool e um fornecedor do Workload Identity Pool. Só tem de realizar estes passos uma vez para cada repositório de confiança. Em seguida, pode usar o mesmo Workload Identity Pool e fornecedor para várias cargas de trabalho e em vários projetos. Trusted Cloud

Crie o Workload Identity Pool

1. Para criar um novo Workload Identity Pool, execute o seguinte comando:

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

   Substitua o seguinte:

   • POOL_ID: o ID exclusivo do conjunto.
   • DISPLAY_NAME: o nome do conjunto.
   • DESCRIPTION: uma descrição do grupo que escolhe. Esta descrição é apresentada quando concede acesso a identidades de conjunto.

Crie o fornecedor do Workload Identity Pool

1. Para adicionar um fornecedor do Workload Identity Pool 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 o seguinte:

   • PROVIDER_ID: um ID do fornecedor do Workload Identity Pool exclusivo à sua escolha.
   • POOL_ID: o ID do Workload Identity Pool que criou anteriormente.
   • TRUST_STORE_CONFIG: o ficheiro YAML da loja de confiança.
   • MAPPINGS: uma lista separada por vírgulas de mapeamentos de atributos que criou anteriormente neste guia. Por exemplo, google.subject=assertion.subject.dn.cn.
   • CONDITIONS: opcional. Uma condição de atributo que criou anteriormente neste guia. Remova o parâmetro se não tiver uma condição de atributo.

Autentique uma carga de trabalho

Tem de realizar estes passos uma vez para cada carga de trabalho.

Permita que a sua carga de trabalho externa aceda aos recursos do Trusted Cloud

Para dar acesso aos recursos à sua carga de trabalho, recomendamos que conceda acesso direto aos recursos ao principal. Trusted Cloud Neste caso, o principal é o utilizador federado. Alguns Trusted Cloud produtos têm limitações da API Google Cloud. Se a sua carga de trabalho chamar um ponto final da API que tenha uma limitação, pode, em alternativa, usar a representação de contas de serviço. Neste caso, o principal é a Trusted Cloud conta de serviço, que funciona como a identidade. Concede acesso à conta de serviço no recurso.

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"

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"

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"

Transfira ou crie uma configuração de credenciais

As bibliotecas cliente do Google Cloud e a CLI gcloud podem obter automaticamente credenciais externas e usar estas credenciais para se fazerem passar por uma conta de serviço. Para permitir que as bibliotecas e as ferramentas concluam este processo, tem de fornecer um ficheiro de configuração de credenciais. Este ficheiro fornece as seguintes informações:

• Onde obter credenciais externas
• Que Workload Identity Pool e fornecedor usar
• Que conta de serviço usar como identidade

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

Crie ficheiros de configuração de credenciais e certificados que permitam à biblioteca obter tokens de acesso através de certificados X.509.

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

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

Use a configuração de credenciais para aceder a Trusted Cloud

Para permitir que as ferramentas e as bibliotecas de cliente usem a configuração das suas credenciais, faça o seguinte: Para saber mais acerca das Credenciais padrão da aplicação, consulte o artigo Como funcionam as Credenciais padrão da aplicação.

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

   Bash

     export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
     

   Substitua FILEPATH pelo caminho relativo para o ficheiro de configuração das credenciais.

   PowerShell

     $env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
     

   Substitua FILEPATH pelo caminho relativo para o ficheiro de configuração das credenciais.

2. Certifique-se de que a biblioteca de cliente consegue encontrar o ficheiro de configuração do certificado. O ficheiro de configuração do certificado encontra-se num dos seguintes caminhos:

   • O caminho predefinido 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 cliente do Google Cloud que suportam a Workload Identity Federation com certificados X.509.

   Ir

   As bibliotecas cliente para Go suportam a federação de identidades da carga de trabalho X.509 se usarem a versão 0.16.0 ou posterior do módulo cloud.google.com/go/auth e a versão 0.189.0 do módulo google.golang.org/api.

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

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

   Python

   As bibliotecas cliente para Python suportam a Workload Identity Federation X.509 se usarem a versão 2.39.0 ou posterior do pacote google-auth

   Para verificar que versão deste pacote a sua biblioteca de cliente usa, execute o seguinte comando no ambiente onde o pacote está instalado:

     pip show google-auth
   

   Para especificar um ID do projeto para o cliente de autenticação, pode definir a variável de ambiente GOOGLE_CLOUD_PROJECT ou permitir que o cliente encontre o ID do projeto automaticamente. Para encontrar o ID do projeto automaticamente, a conta de serviço no ficheiro de configuração tem de ter a função de navegador (roles/browser) ou uma função com autorizações equivalentes no seu projeto. Para obter detalhes, consulte o manual do utilizador do pacote google-auth.

4. Se a sua 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 respetivo diretório de instalação.

5. Para fazer a autenticação através da CLI gcloud, execute o seguinte comando:

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

   Substitua FILEPATH pelo caminho para o ficheiro de configuração das credenciais.

   O apoio técnico para a Workload Identity Federation X.509 na CLI gcloud está disponível na versão 519.0 e versões posteriores da CLI gcloud.

Obtenha um token de acesso através de um pedido simples para aceder a Trusted Cloud

Crie a cadeia de confiança

Este passo mostra como criar a cadeia de confiança. Transmite a cadeia de confiança no campo subject_token quando chama o serviço de tokens de segurança num pedido simples.

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

1. Guarde o certificado de folha e o certificado intermédio 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 possa ser transmitida como subject_token na chamada ao serviço de tokens de segurança, mais adiante neste documento

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

Obtenha a chave de acesso

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

1. Efetue a troca de tokens com mTLS e o certificado de cliente:

   curl --key CLIENT_CERT_KEY \
   --cert CLIENT_CERT \
   --request POST 'https://sts.mtls.s3nsapis.fr/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 o seguinte:

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

   • WORKLOAD_IDENTITY_POOL_URI: o URL do fornecedor do Workload Identity Pool 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 validar o certificado de folha tem de incluir, pelo menos, CLIENT_CERT como o primeiro item. Se seguiu as instruções na secção Formatar os certificados, substitua TRUST_CHAIN por '"${TRUST_CHAIN}"'

2. Use o token de acesso de portador gerado no passo anterior para aceder aos Trusted Cloud recursos, por exemplo:

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

Limites

A tabela seguinte apresenta os limites.

O que se segue?

• Leia mais sobre a federação de identidades da carga de trabalho.
• Saiba mais acerca das práticas recomendadas para usar a Workload Identity Federation.
• Veja como pode gerir Workload Identity Pools e fornecedores.