Neste guia, descrevemos como usar a federação de identidade da carga de trabalho com outros provedores de identidade (IdPs).
As cargas de trabalho executadas fora do Google Cloud podem ter acesso a credenciais específicas do ambiente que já existem, por exemplo:
Uma carga de trabalho pode receber uma declaração SAML ou um token do OpenID Connect (OIDC) de um provedor de identidade (IdP) executado no mesmo ambiente.
Para autenticação no Google Cloud, é possível permitir que a carga de trabalho troque as credenciais específicas do ambiente por credenciais de curta duração do Google Cloud usando a federação de identidade da carga de trabalho.
Uma carga de trabalho pode ter outros tipos de credenciais, como um certificado do cliente mTLS.
Ao combinar a federação de identidade da carga de trabalho com um agente de token personalizado, é possível permitir que as cargas de trabalho usem outros tipos de credenciais para receber credenciais de curta duração do Google Cloud.
O uso da federação de identidade da carga de trabalho pode ajudar você a reduzir o número de credenciais que exigem rotação.
As próximas seções descrevem como usar a federação de identidade da carga de trabalho com IdPs compatíveis com um destes protocolos de autenticação: OpenID Connect (OIDC) ou SAML.
Preparar seu IdP externo
Você só precisa realizar essas etapas uma vez para cada IdP.
Antes de começar, verifique se o IdP externo atende aos seguintes requisitos:
OIDC
O IdP é compatível com o OpenID Connect 1.0.
Os metadados OIDC e os endpoints JWKS do IdP são protegidos com SSL e TLS, os URLs do endpoint começam com
https://
e os endpoints são acessíveis publicamente pela Internet.O Google Cloud usa esses endpoints para fazer o download do conjunto de chaves do IdP e usa esse conjunto para validar tokens.
Os endpoints protegidos com certificados autoassinados não são compatíveis com o Google Cloud.
SAML
O IdP é compatível com SAML 2.0.
O IdP fornece um documento de metadados SAML SP que descreve a configuração do provedor de serviços SAML e contém o certificado de assinatura do IdP.
O Google Cloud usa esse certificado para validar declarações e respostas SAML.
Se o IdP atender a esses critérios, faça o seguinte:
OIDC
Configure seu IdP para que a carga de trabalho possa receber tokens de ID que atendam a estes critérios:
- Os tokens são assinados usando o algoritmo
RS256
ouES256
. Os tokens contêm uma declaração
aud
com o seguinte valor:https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
Substitua:
PROJECT_NUMBER
: o número do projeto do Google Cloud que você usa para criar o pool de identidades da carga de trabalho;POOL_ID
: ID de sua escolha que identifica o pool de identidades da carga de trabalho. É necessário usar o mesmo ID ao criar o pool de identidades da carga de trabalho posteriormente.PROVIDER_ID
: ID de sua escolha que identifica o provedor de pools de identidades de cargas de trabalho. É necessário usar o mesmo ID ao criar o provedor do pool de identidades de carga de trabalho posteriormente.
Como alternativa, é possível configurar o provedor de pool de identidade da carga de trabalho para esperar um público personalizado.
Os tokens contêm uma declaração
exp
no futuro e umaiat
no passado.O valor de
exp
precisa ser maior que o valor deiat
em até 24 horas.
Normalmente, é melhor usar tokens de ID ao realizar uma troca de tokens, porque eles refletem a identidade do usuário. Se você decidir usar tokens de acesso, verifique se eles atendem aos seguintes requisitos adicionais:
- Os tokens de acesso são formatados em JSON Web Token
Os tokens de acesso contêm uma declaração
ISSUER
para que o URLISSUER/.well-known/openid-configuration
aponte para o endpoint de metadados OIDC do IdP.Para fazer upload de chaves JWK locais, consulte Gerenciar JWKs do OIDC.
SAML
Configure seu IdP para que as declarações SAML contenham elementos que atendam aos seguintes critérios:
- um elemento
Issuer
definido como o ID da entidade configurado no provedor do pool de identidades da carga de trabalho. O formato do emissor precisa ser omitido ou definido comourn:oasis:names:tc:SAML:2.0:nameid-format:entity
; - um elemento
Subject
com:- um elemento
NameID
; - exatamente um elemento
SubjectConfirmation
comMethod
definido comourn:oasis:names:tc:SAML:2.0:cm:bearer
; - um elemento
SubjectConfirmationData
comNotOnOrAfter
definido como um carimbo de data/hora que ocorrerá no futuro e nenhum valorNotBefore
.
- um elemento
um elemento
Conditions
com:NotBefore
omitido ou antigo;NotOnOrAfter
omitido ou no futuro.um
Audience
, formatado da seguinte maneira:https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
Substitua:
PROJECT_NUMBER
: o número do projeto do Google Cloud que você usa para criar o pool de identidades da carga de trabalho;POOL_ID
: ID de sua escolha que identifica o pool de identidades da carga de trabalho. É necessário usar o mesmo ID ao criar o pool de identidades da carga de trabalho posteriormente.PROVIDER_ID
: ID de sua escolha que identifica o provedor de pools de identidades de cargas de trabalho. É necessário usar o mesmo ID ao criar o provedor do pool de identidades de carga de trabalho posteriormente.
pelo menos um elemento
AuthnStatement
;um elemento
SessionNotOnOrAfter
com um carimbo de data/hora que ocorrerá no futuro. Se preferir, omita o elemento.
Para declarações SAML incluídas em uma resposta SAML, a resposta SAML precisa conter:
- exatamente uma declaração que atenda aos critérios de declaração SAML descritos anteriormente nesta seção;
- um atributo
IssueInstant
com um valor inferior a uma hora no passado; - o StatusCode
urn:oasis:names:tc:SAML:2.0:status:Success
.
É preciso assinar a declaração SAML, a resposta ou ambas.
Configurar a federação de identidade da carga de trabalho
Você só precisa realizar essas etapas uma vez para cada IdP. Use o mesmo pool de identidade de carga de trabalho e servidor em várias cargas de trabalho e em vários projetos do Google Cloud.
Para começar a configurar a federação de identidade da carga de trabalho, faça isto:
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
É melhor
usar um projeto dedicado para gerenciar pools e provedores de identidade da carga de trabalho
-
Make sure that billing is enabled for your Google Cloud project.
Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs.
Gerenciar JWKs do OIDC (opcional)
Nesta seção, mostramos como gerenciar JWKs OIDC com upload automático em provedores oidc do pool de identidades de carga de trabalho.
Criar um provedor e fazer upload de JWKs do OIDC
Para criar JWKs do OIDC, consulte Implementações de JWT, JWS, JWE, JWK e JWA.
Para fazer upload de um arquivo JWK do OIDC ao criar um provedor de pool de identidade de carga de trabalho,
execute o comando gcloud iam workload-identity-pools providers create-oidc
com --jwk-json-path="JWK_JSON_PATH"
.
Substitua JWK_JSON_PATH
pelo caminho para o
arquivo JSON do JWKs.
Essa operação cria chaves enviadas com as chaves no arquivo.
Atualizar JWKs do OIDC
Para atualizar as JWKs do OIDC, execute o comando gcloud iam workload-identity-pools providers update-oidc com --jwk-json-path="JWK_JSON_PATH"
.
Substitua JWK_JSON_PATH
pelo caminho para o
arquivo JSON do JWKs.
Essa operação substitui todas as chaves atuais enviadas pelas chaves no arquivo. Não é possível restaurar as chaves substituídas.
Excluir todos os JWKs do OIDC enviados por upload
Para excluir todos os JWKs do OIDC enviados e voltar a usar o URI do emissor para buscar as chaves, execute o comando gcloud iam workload-identity-pools providers update-oidc com --jwk-json-path="JWK_JSON_PATH"
.
Substitua JWK_JSON_PATH
pelo caminho para um arquivo vazio.
Use a sinalização --issuer-uri
para definir o URI do emissor.
Essa operação exclui todas as chaves atuais enviadas por upload no arquivo. Não é possível restaurar as chaves excluídas.
Definir um mapeamento e uma condição de atributo
Os tokens OIDC ou declarações SAML emitidas pelo IdP podem conter vários atributos, e você precisa decidir qual atributo quer usar como identificador do assunto (google.subject
) no Google Cloud.
Também é possível mapear outros atributos. Consulte esses atributos ao conceder acesso aos recursos.
OIDC
Os mapeamentos de atributos podem usar as declarações incorporadas no token de ID ou de acesso emitido pelo IdP externo.
Mapeie uma dessas declarações para google.subject
para identificar exclusivamente o usuário. Para se proteger contra ameaças de spoofing, escolha uma reivindicação com um valor exclusivo que não possa ser alterado.
Muitos IdPs preenchem a declaração sub
com um ID
exclusivo e imutável. Para esses IdPs, considere mapear a declaração sub
para
google.subject
:
google.subject=assertion.sub
Evite usar uma reivindicação como email
para essa finalidade. Geralmente, os endereços de e-mail
podem ser reatribuídos ou alterados para que não identifiquem um usuário de maneira exclusiva
e permanente.
SAML
Os mapeamentos de atributos podem usar os elementos <Subject>
e <Attribute>
incorporados na declaração emitida pelo IdP externo. Os
atributos SAML podem ser referenciados usando as seguintes palavras-chave:
assertion.subject
contém oNameID
do usuário autenticado encontrado no elemento<Subject>
.assertion.attributes['ATTRIBUTE_NAME']
contém uma lista de valores com o nome<Attribute>
.
Mapeie uma dessas declarações para google.subject
para identificar
exclusivamente o usuário. Para se proteger contra ameaças de spoofing, escolha uma reivindicação com
um valor exclusivo que não possa ser alterado.
Muitos IdPs preenchem o NameId
com um ID exclusivo e
imutável. Para esses IdPs, considere mapear o
atributo NameId
para google.subject
:
google.subject=assertion.subject
Evite usar um atributo como
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
para essa finalidade. Geralmente, os endereços de e-mail podem ser reatribuídos ou alterados para que
não identifiquem um usuário de maneira exclusiva
e permanente.
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.
OIDC
Use uma condição de atributo para restringir quais usuários podem usar a federação de identidade da carga de trabalho para conseguir tokens do Google Cloud de curta duração.
Por exemplo, a condição a seguir restringe o acesso a tokens que
contêm uma declaração service_account
personalizada com um valor true
:
assertion.service_account==true
SAML
Use uma condição de atributo para restringir quais usuários podem usar a federação de identidade da carga de trabalho para conseguir tokens do Google Cloud de curta duração.
Por exemplo, a condição a seguir restringe o acesso a declarações que
contenham um atributo https://example.com/SAML/Attributes/AllowGcpFederation
personalizado com um valor true
:
assertion.attributes['https://example.com/SAML/Attributes/AllowGcpFederation'][0]=='true'
Crie um pool de identidades e um provedor de carga de trabalho
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:
-
Administrador de pool de Identidade da carga de trabalho (
roles/iam.workloadIdentityPoolAdmin
) -
Administrador da conta de serviço (
roles/iam.serviceAccountAdmin
)
Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.
Também é possível conseguir as permissões necessárias com papéis personalizados ou 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.
Agora que você coletou todas as informações necessárias para criar um pool e um provedor de identidade de carga de trabalho:
Console
No Console do Google Cloud, acesse a página Novo provedor de carga de trabalho e pool.
Em Criar um pool de identidades, digite o seguinte:
- Nome: o nome do pool. O nome também é usado como o ID do pool. Não será possível alterar o ID do pool posteriormente.
- Descrição: texto que descreve a finalidade do pool.
Clique em Continuar.
Defina as configurações do provedor da seguinte maneira:
OIDC
- Em Selecionar um provedor, selecione OpenID Connect (OIDC).
- Em Nome do provedor, digite um nome para o provedor. O nome também é usado como o ID do provedor. Não é possível alterar o ID do provedor depois que ele for criado.
- Em URL do emissor, digite o URL do emissor do seu IdP. O URL precisa começar com
https://
. - Opcional: em Arquivo JWK(JSON), escolha um arquivo JWK para fazer upload. Se esse campo não for fornecido, o Google Cloud tentará buscar um JWK do emissor.
- Públicos-alvo permitidos: público-alvo esperado dos tokens de ID.
SAML
- Em Selecionar um provedor, escolha SAML.
- Em Nome do provedor, digite um nome para o provedor. O nome também é usado como o ID do provedor. Não é possível alterar o ID do provedor depois que ele for criado.
- Em Arquivo de metadados do IdP (XML), faça upload do documento XML de metadados SAML fornecido pelo seu provedor de identidade.
Clique em Continuar.
Em Configurar atributos do provedor, adicione os mapeamentos de atributos identificados anteriormente neste guia.
Em Condições de atributo, insira a condição de atributo que você identificou anteriormente neste guia. Deixe o campo em branco se não houver uma condição de atributo.
Para criar o pool de identidades e o provedor de carga de trabalho, clique em Salvar.
gcloud
Para criar um novo pool de identidades de 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.
Para adicionar um provedor de pool de Identidade da carga de trabalho, faça o seguinte:
OIDC
Para adicionar um provedor de pool de identidade de carga de trabalho do OIDC, execute o seguinte comando:
gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \ --location="global" \ --workload-identity-pool="POOL_ID" \ --issuer-uri="ISSUER" \ --allowed-audiences="AUDIENCE" \ --attribute-mapping="MAPPINGS" \ --attribute-condition="CONDITIONS" --jwk-json-path="JWK_JSON_PATH"
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.ISSUER
: um URI do emissor, conforme definido nos metadados OIDC.AUDIENCE
: o público esperado de tokens de ID, que, para muitos provedores, correspondem ao ID do cliente.MAPPINGS
: uma lista separada por vírgulas de mapeamentos de atributos criados anteriormente neste guia.CONDITIONS
: uma condição de atributo opcional que você criou anteriormente neste guia. Remova o parâmetro se você não tiver uma condição de atributo.JWK_JSON_PATH
: um caminho opcional para JWKs do OIDC de upload local. Se esse parâmetro não for fornecido, o Google Cloud usará o caminho/.well-known/openid-configuration
do IdP para gerar as JWKs que contêm as chaves públicas.
SAML
Para adicionar um provedor de pool de identidade de carga de trabalho SAML, execute o seguinte comando:
gcloud iam workload-identity-pools providers create-saml PROVIDER_ID \ --location="global" \ --workload-identity-pool="POOL_ID" \ --idp-metadata-path="IDP_METADATA_PATH" \ --attribute-mapping="MAPPINGS" \ --attribute-condition="CONDITIONS"
Substitua:
POOL_ID
: o ID do poolIDP_METADATA_PATH
: o caminho local para o documento de metadados do IdP do SAML.MAPPINGS
: uma lista separada por vírgulas de mapeamentos de atributos criados anteriormente neste guia.CONDITIONS
: opcional. A condição do atributo que você criou anteriormente neste guia.
O prefixo
gcp-
é reservado e não pode ser usado em um ID de pool ou de provedor.Opcional: aceitar declarações SAML criptografadas do seu IdP
Para permitir que o IdP do SAML 2.0 produza declarações SAML criptografadas que podem ser aceitas pela federação de identidade da carga de trabalho, faça isto:
- Na federação de identidade da carga de trabalho, faça isto:
- Crie um par de chaves assimétricas para seu provedor de pool de identidade da carga de trabalho.
- Faça o download de um arquivo de certificado que contém a chave pública.
- Configure o IdP do SAML para que use a chave pública para criptografar as declarações SAML emitidas.
- No IdP, faça isto:
- Ative a criptografia de declaração, também conhecida como criptografia de token.
- Faça upload da chave pública que você criou na federação de identidade da carga de trabalho.
- Confirme se o IdP produz declarações SAML criptografadas.
Criar chaves de criptografia de declaração SAML da federação de identidade da carga de trabalho
Nesta seção, mostramos como criar um par de chaves assimétricas que permite que a federação de identidade da carga de trabalho aceite declarações SAML criptografadas.
O Google Cloud usa a chave privada para descriptografar as declarações SAML emitidas pelo IdP. Para criar um par de chaves assimétricas para uso com criptografia SAML, execute o seguinte comando. Para saber mais, consulte Algoritmos de criptografia SAML compatíveis.
gcloud iam workload-identity-pools providers keys create KEY_ID \ --workload-identity-pool WORKLOAD_POOL_ID \ --provider PROVIDER_ID \ --location global \ --use encryption \ --spec KEY_SPECIFICATION
Substitua:
KEY_ID
: o nome da chave que você escolherWORKLOAD_POOL_ID
: o ID do poolPROVIDER_ID
: o ID do provedor-
KEY_SPECIFICATION
: a especificação da chave, que pode ser uma destas:rsa-2048
,rsa-3072
ersa-4096
.
Depois que o par de chaves for criado, execute o comando a seguir para fazer o download da chave pública em um arquivo de certificado. Somente a federação de identidade da carga de trabalho tem acesso à chave privada.
gcloud iam workload-identity-pools providers keys describe KEY_ID \ --workload-identity-pool WORKLOAD_POOL_ID \ --provider PROVIDER_ID \ --location global \ --format "value(keyData.key)" \ > CERTIFICATE_PATH
Substitua:
KEY_ID
: o nome da chaveWORKLOAD_POOL_ID
: o ID do poolPROVIDER_ID
: o ID do provedorCERTIFICATE_PATH
: o caminho para gravar o certificado em, por exemplo,saml-certificate.cer
ousaml-certificate.pem
Configurar o IdP compatível com SAML 2.0 para emitir declarações SAML criptografadas
Configure o IdP do SAML para que use o certificado público transferido por download na última etapa para criptografar as declarações SAML emitidas. Consulte a equipe do IdP para ter instruções específicas.
Depois de configurar o IdP para criptografar declarações SAML, recomendamos que você confira se as declarações geradas estão realmente criptografadas. Mesmo com a criptografia da declaração SAML configurada, a federação de identidade da carga de trabalho ainda pode processar declarações de texto simples.
Excluir chaves de criptografia da federação de identidade da carga de trabalho
Para excluir as chaves de criptografia SAML, execute o seguinte comando:gcloud iam workload-identity-pools providers keys delete KEY_ID \ --workload-identity-pool WORKLOAD_POOL_ID \ --provider PROVIDER_ID \ --location global
Substitua:
KEY_ID
: o nome da chaveWORKLOAD_POOL_ID
: o ID do poolPROVIDER_ID
: o ID do provedor
Algoritmos de criptografia SAML compatíveis
A federação de identidade da carga de trabalho é compatível com os seguintes algoritmos de transporte de chaves:
- http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p (link em inglês)
- http://www.w3.org/2009/xmlenc11#rsa-oaep" (link em inglês)
- http://www.w3.org/2001/04/xmlenc#rsa-1_5" (link em inglês)
A federação de identidade da carga de trabalho é compatível com os seguintes algoritmos de criptografia em blocos:
- http://www.w3.org/2001/04/xmlenc#aes128-cbc (link em inglês)
- http://www.w3.org/2001/04/xmlenc#aes192-cbc (link em inglês)
- http://www.w3.org/2001/04/xmlenc#aes256-cbc (link em inglês)
- http://www.w3.org/2009/xmlenc11#aes128-gcm (link em inglês)
- http://www.w3.org/2009/xmlenc11#aes256-gcm (link em inglês)
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ço do Google 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 do Google Cloud ou a gcloud CLI.
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.
- No Console do Google Cloud, acesse a página Buckets do Cloud Storage.
Na lista de buckets, clique no nome do bucket ao qual você quer conceder o papel.
Selecione a guia Permissões na parte superior da página.
Clique no botão add_boxPermitir acesso.
A caixa de diálogo Adicionar principais será exibida.
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 projetoPOOL_ID
: o ID do pool de carga de trabalhoSUBJECT
: 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 projetoWORKLOAD_POOL_ID
: o ID do pool de carga de trabalhoGROUP
: 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 projetoWORKLOAD_POOL_ID
: o ID do pool de carga de trabalhoATTRIBUTE_NAME
: um dos atributos que foi mapeado do IdPATTRIBUTE_VALUE
: o valor do atributo
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.
Clique em Save.
gcloud
Para usar a gcloud CLI a fim de conceder papéis do IAM em um recurso de um projeto, faça isto:
Consiga o número do projeto em que o recurso está definido.
gcloud projects describe $(gcloud config get-value core/project) --format=value\(projectNumber\)
Conceda acesso ao recurso.
Para usar a gcloud CLI para conceder o papel Usuário de Identidade da carga de trabalho (
roles/iam.workloadIdentityUser
) 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á concedidoPROJECT_NUMBER
: o número do projeto que contém o pool de Identidade da carga de trabalhoPOOL_ID
: o ID do pool de identidade da carga de trabalhoSUBJECT
: o valor esperado do atributo mapeado paragoogle.subject
GROUP
: o valor esperado do atributo mapeado paragoogle.groups
ATTRIBUTE_NAME
: o nome de um atributo personalizado no seu mapeamento de atributosATTRIBUTE_VALUE
: o valor do atributo personalizado no seu mapeamento de atributos
É possível conceder papéis em qualquer recurso do Google Cloud compatível com políticas de permissão do IAM.
Identidade temporária de conta de serviço
Para criar uma conta de serviço para a carga de trabalho externa, faça isto:
Enable the IAM, Security Token Service, and Service Account Credentials APIs.
Crie uma conta de serviço que represente a carga de trabalho. Recomendamos usar 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 identidades da carga de trabalho.
Conceda à conta de serviço acesso a recursos que você quer que as identidades externas acessem.
Conceda o papel Usuário de Identidade da carga de trabalho (
roles/iam.workloadIdentityUser
) à conta de serviço: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.
Para conceder acesso a uma identidade federada usando a identidade temporária de conta de serviço pelo console do Google Cloud ou pela gcloud CLI, faça isto:
Console
Para usar o console do Google Cloud para conceder papéis do IAM a uma identidade federada com conta de serviço, faça isto:
Crie uma conta de serviço que sirva como a identidade que será representada, conforme a seguir:
Enable the IAM, Security Token Service, and Service Account Credentials APIs.
Crie uma conta de serviço que represente a identidade para 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, ao conceder acesso ao IAM, você precisa se referir ao projeto que contém a conta de serviço.
Conceda à conta de serviço acesso a recursos que você quer que as identidades externas acessem.
Para conceder acesso usando a identidade temporária de conta de serviço, faça isto.
Acesse a página pools de Identidade da carga de trabalho.
Selecione Conceder acesso.
Na caixa de diálogo Conceder acesso à conta de serviço, selecione Conceder acesso usando a identidade temporária de conta de serviço.
Na lista Contas de serviço, selecione a conta de serviço para as identidades externas que serão representadas e faça isto:
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 comsubject
e o Valor do atributo com o valor da declaraçãosub
em tokens emitidos pelo seu provedor de identidade externo.
Para salvar a configuração, clique em Salvar e em Dispensar.
gcloud
Para usar a gcloud CLI para conceder o papel Usuário de Identidade da carga de trabalho (
roles/iam.workloadIdentityUser
) a identidades externas que atendam a determinados critérios, execute o comando a seguir.Por assunto
gcloud storage buckets add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \ --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 SERVICE_ACCOUNT_EMAIL \ --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 SERVICE_ACCOUNT_EMAIL \ --role=roles/storage.objectViewer \ --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çoPROJECT_NUMBER
: o número do projeto que contém o pool de Identidade da carga de trabalhoPOOL_ID
: o ID do pool de identidade da carga de trabalhoSUBJECT
: o valor esperado do atributo mapeado paragoogle.subject
GROUP
: o valor esperado do atributo mapeado paragoogle.groups
ATTRIBUTE_NAME
: o nome de um atributo personalizado no seu mapeamento de atributosATTRIBUTE_VALUE
: o valor do atributo personalizado no seu mapeamento de atributos
Baixar uma configuração de credencial
Nesta seção, descrevemos como baixar a configuração de credencial usando o console do Google Cloud.
Para permitir que sua carga de trabalho acesse as bibliotecas de cliente, primeiro baixe e configure o Application Default Credentials (ADC) conforme a seguir:
-
No Console do Google Cloud, acesse a página Pools de Identidades da carga de trabalho.
Acesse Pools de identidade da carga de trabalho -
Na tabela, selecione o pool para acessar a página de detalhes dele.
-
Clique em Conceder acesso.
-
Selecione Conceder acesso usando identidades federadas (recomendado)
-
Para baixar o Application Default Credentials (ADC) para que sua carga de trabalho possa acessar as bibliotecas de cliente, faça isto:
-
Clique em Baixar configuração.
-
Na caixa de diálogo Configurar seu aplicativo, faça isto:
-
Na lista suspensa Provedor, selecione seu provedor.
-
No Caminho do token OIDC ou no caminho da declaração SAML, insira o caminho em que o token ou a declaração está localizado.
Na lista suspensa Tipo de formato, selecione o formato.
-
-
Clique em Baixar configuração e anote o caminho em que você salvou o arquivo.
-
Criar uma configuração de credencial
As bibliotecas de cliente do Cloud, a gcloud CLI e o Terraform podem receber credenciais externas automaticamente e usá-las para acessar o Google Cloud. Para permitir que bibliotecas e ferramentas concluam esse processo, você precisa fornecer um arquivo de configuração de credenciais. Esse arquivo define o seguinte:
- De onde receber credenciais externas
- Qual pool de identidades de carga de trabalho e provedor usar
- Qual conta de serviço representar, se você usa a identidade temporária de conta de serviço
As bibliotecas de cliente do Cloud recebem credenciais externas de um arquivo local, um URL HTTP, executando um executável local:
Credenciais de execução executável: as bibliotecas iniciam um executável sempre que precisam de uma nova credencial. Se o executável conseguir uma nova credencial externa, ele precisará gravar um documento JSON em
STDOUT
semelhante a este:OIDC
{ "version": 1, "success": true, "token_type": "urn:ietf:params:oauth:token-type:id_token", "id_token": "HEADER.PAYLOAD.SIGNATURE", "expiration_time": 1620499962 }
Se o executável não conseguir uma nova credencial, ele precisará gravar um documento JSON em
STDOUT
semelhante a este:{ "version": 1, "success": false, "code": "401", "message": "Caller not authorized." }
Os documentos JSON usam os seguintes campos:
version
: a versão da saída JSON. Apenas a versão 1 é compatível.success
: o status da resposta.Quando
true
, a resposta precisa conter os camposid_token
etoken_type
. O executável precisa sair com o código de saída 0.Quando
false
, a resposta precisa conter os camposcode
emessage
e sair com um valor diferente de zero.token_type
: o tipo de token da credencial externa. Os valores aceitos sãourn:ietf:params:oauth:token-type:id_token
urn:ietf:params:oauth:token-type:jwt
id_token
: a credencial externa.expiration_time
: o prazo de validade do token OIDC em segundos (horário Unix). Esse campo só é necessário quando um arquivo de saída é especificado na configuração da credencial.code
: a string do código de erro.message
: a mensagem de erro
SAML
{ "version": 1, "success": true, "token_type": "urn:ietf:params:oauth:token-type:saml2", "saml_response": "...", "expiration_time": 1620499962 }
Se o executável não conseguir uma nova credencial, ele precisará gravar um documento JSON em
STDOUT
semelhante a este:{ "version": 1, "success": false, "code": "401", "message": "Caller not authorized." }
Os documentos JSON usam os seguintes campos:
version
: a versão da saída JSON. Apenas a versão 1 é compatível.success
: o status da resposta.Quando
true
, a resposta precisa conter os camposid_token
etoken_type
. O executável precisa sair com o código de saída 0.Quando
false
, a resposta precisa conter os camposcode
emessage
e sair com um valor diferente de zero.token_type
: o tipo de token da credencial externa. Precisa serurn:ietf:params:oauth:token-type:saml2
.saml_response
: a resposta SAML ou a declaração SAML codificada em base64.expiration_time
: o prazo de validade da declaração em segundos (horário Unix). Esse campo só é necessário quando um arquivo de saída é especificado na configuração da credencial.code
: a string do código de erro.message
: a mensagem de erro
Ao iniciar o executável, as bibliotecas de cliente definem as seguintes variáveis de ambiente:
GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE
: público-alvo da configuração de credenciais. Sempre presente.GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE
: tipo de token de assunto esperado. Sempre presente.GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL
: e-mail da conta de serviço Presente apenas quando a representação da conta de serviço é usada.GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE
: o local do arquivo de saída da configuração da credencial. Presente somente quando especificado na configuração de credencial.
Para usar credenciais de origem executável, é necessário definir a variável de ambiente
GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES
como1
.Credenciais fornecidas pelo arquivo: as bibliotecas leem a credencial externa de um arquivo de texto simples local ou JSON. Exemplo:
JSON
{ "mytoken": "ey... }
Texto
ey...
A credencial externa pode ser:
- um token OIDC;
- uma resposta SAML;
- uma declaração SAML codificada em Base64.
É necessário atualizar o arquivo periodicamente para que ele sempre tenha uma credencial válida. Por exemplo, se o token OIDC ou declaração SAML for válido por uma hora, atualize o arquivo pelo menos uma vez por hora.
Credenciais fornecidas pelo URL: as bibliotecas executam uma solicitação
GET
para um endpoint HTTP sempre que precisam de uma nova credencial. O endpoint precisa retornar um texto simples ou uma resposta JSON equivalente ao formato usado pelas credenciais fornecidas pelo arquivo.
Para criar um arquivo de configuração de credencial, faça o seguinte:
Credenciais de origem executáveis
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 \ --output-file=FILEPATH.json \ --executable-command=EXECUTABLE_COMMAND \ --executable-timeout-millis=EXECUTABLE_TIMEOUT \ --executable-output-file=EXECUTABLE_OUTPUT_FILE
Substitua:
PROJECT_NUMBER
: o número do projeto que contém o pool de Identidade da carga de trabalhoPOOL_ID
: o ID do pool de Identidade da carga de trabalhoPROVIDER_ID
: o ID do provedor do pool de Identidade da carga de trabalhoSERVICE_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. Omita essa flag se você não usa a identidade temporária de conta de serviço.SERVICE_ACCOUNT_TOKEN_LIFETIME
: se você usa a identidade temporária de conta de serviço, substitua pelo ciclo de vida do token de acesso à conta de serviço, em segundos. Quando não informado, o padrão é 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 organizacionalconstraints/iam.allowServiceAccountCredentialLifetimeExtension
.FILEPATH
: o arquivo em que a configuração será salva.EXECUTABLE_COMMAND
: o comando completo, incluindo argumentos, a ser executado para recuperar o token de ID do OIDC. Por exemplo,--executable-command="/path/to/command --foo=bar"
.EXECUTABLE_TIMEOUT
: a duração opcional em milissegundos para aguardar a execução do executável (o padrão é 30s).EXECUTABLE_OUTPUT_FILE
: um caminho que aponta para as credenciais 3PI geradas pelo executável. Isso é útil para armazenar as credenciais em cache. Ao especificar esse caminho, as bibliotecas do Auth verificam a existência dele antes de executar o executável.
Credenciais fornecidas pelo arquivo
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 \ --output-file=FILEPATH.json \ --credential-source-file=TOKEN_FILEPATH \ --credential-source-type=SOURCE_TYPE \ --credential-source-field-name=FIELD_NAME
Substitua:
PROJECT_NUMBER
: o número do projeto que contém o pool de Identidade da carga de trabalhoPOOL_ID
: o ID do pool de Identidade da carga de trabalhoPROVIDER_ID
: o ID do provedor do pool de Identidade da carga de trabalhoSERVICE_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. Omita essa flag se você não usa a identidade temporária de conta de serviço.SERVICE_ACCOUNT_TOKEN_LIFETIME
: se você usa a identidade temporária de conta de serviço, substitua pelo ciclo de vida do token de acesso à conta de serviço, em segundos. Quando não informado, o padrão é 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 organizacionalconstraints/iam.allowServiceAccountCredentialLifetimeExtension
.FILEPATH
: o arquivo em que a configuração será salva.TOKEN_FILEPATH
: caminho em que os tokens de ID do OIDC são armazenados.SOURCE_TYPE
: formato do arquivo de token de ID do OIDC, definido comotext
(padrão) oujson
.FIELD_NAME
: campo no arquivo de texto que contém o token (seSOURCE_TYPE
forjson
)
Credenciais fornecidas pelo URL
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 \ --output-file=FILEPATH.json \ --credential-source-url="TOKEN_URL" \ --credential-source-headers="KEY_1=VALUE_1,KEY_2=VALUE_2" \ --credential-source-type=SOURCE_TYPE \ --credential-source-field-name=FIELD_NAME
Substitua:
PROJECT_NUMBER
: o número do projeto que contém o pool de Identidade da carga de trabalho.POOL_ID
: ID do pool de Identidade da carga de trabalho.PROVIDER_ID
: ID do provedor do pool de Identidade da carga de trabalhoSERVICE_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. Omita essa flag se você não usa a identidade temporária de conta de serviço.SERVICE_ACCOUNT_TOKEN_LIFETIME
: se você usa a identidade temporária de conta de serviço, substitua pelo ciclo de vida do token de acesso à conta de serviço, em segundos. Quando não informado, o padrão é 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 organizacionalconstraints/iam.allowServiceAccountCredentialLifetimeExtension
.FILEPATH
: o arquivo em que a configuração será salva.TOKEN_URL
: URL do qual o token de ID do OIDC será recuperadoKEY_n
,VALUE_n
: cabeçalhos personalizados para incluir na solicitação HTTP paraTOKEN_URL
SOURCE_TYPE
: formato do arquivo de token de ID do OIDC, definido comotext
(padrão) oujson
FIELD_NAME
: campo no arquivo de texto que contém o token (seSOURCE_TYPE
forjson
)
Usar a configuração de credencial para acessar o Google Cloud
Para permitir que as ferramentas e as bibliotecas de cliente usem a configuração da sua credencial, faça o seguinte:
Inicialize uma variável de ambiente
GOOGLE_APPLICATION_CREDENTIALS
e aponte-a para o arquivo de configuração de credenciais:Bash
export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
em queFILEPATH
é o caminho relativo do arquivo de configuração de credenciais.PowerShell
$env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
em queFILEPATH
é o caminho relativo do arquivo de configuração de credenciais.Use uma biblioteca de cliente ou ferramenta compatível com a federação de identidade da carga de trabalho e que possa encontrar credenciais automaticamente:
C++
As bibliotecas de cliente do Google Cloud para C++ são compatíveis com a federação de identidade da carga de trabalho desde a versão v2.6.0. Para usar a federação de identidade da carga de trabalho, crie as bibliotecas de cliente com a versão 1.36.0 ou mais recente do gRPC.
Go
As bibliotecas de cliente do Go são compatíveis com a federação de identidade se usarem a versão v0.0.0-20210218202405-ba52d332ba99 ou posteriores do módulo
golang.org/x/oauth2
.Para verificar qual versão deste módulo sua biblioteca de cliente usa, execute os seguintes comandos:
cd $GOPATH/src/cloud.google.com/go go list -m golang.org/x/oauth2
Java
As bibliotecas de cliente do Java aceitam federação de identidade se usarem a versão 0.24.0 ou posteriores do artefato
com.google.auth:google-auth-library-oauth2-http
.Para verificar qual versão desse artefato a biblioteca de cliente usa, execute o seguinte comando do Maven no diretório do aplicativo:
mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http
Node.js
As bibliotecas de cliente do Node.js são compatíveis com a federação de identidade de carga de trabalho se usarem a versão 7.0.2 ou posteriores do pacote
google-auth-library
.Para verificar qual versão desse pacote sua biblioteca de cliente usa, execute o seguinte comando no diretório do seu aplicativo:
npm list google-auth-library
Ao criar um objeto
GoogleAuth
, é possível especificar um ID de projeto ou permitir queGoogleAuth
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 oREADME
do pacotegoogle-auth-library
.Python
As bibliotecas de cliente do Python são compatíveis com a federação de identidade se usarem a versão 1.27.0 ou posteriores 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 pacotegoogle-auth
.gcloud
Para autenticar usando a federação de identidade da carga de trabalho, use o comando
gcloud auth login
:gcloud auth login --cred-file=FILEPATH.json
Substitua
FILEPATH
pelo caminho do arquivo de configuração de credencial.O suporte para a federação de identidade de carga de trabalho na CLI gcloud está disponível na versão 363.0.0 e posteriores da CLI gcloud.
Terraform
O provedor do Google Cloud é compatível com a federação de identidade da carga de trabalho se você usar a versão 3.61.0 ou posterior:
terraform { required_providers { google = { source = "hashicorp/google" version = "~> 3.61.0" } } }
gsutil
Para autenticar usando a federação de identidade da carga de trabalho, use um dos seguintes métodos:
Quando você usar a gsutil com a gcloud, faça login normalmente:
gcloud auth login --cred-file=FILEPATH.json
Ao usar a gsutil como um aplicativo de linha de comando autônomo, edite o arquivo .boto para incluir a seguinte seção:
[Credentials] gs_external_account_file = FILEPATH
Substitua
FILEPATH
, em ambos os casos, pelo caminho do arquivo para a configuração da credencial.O suporte para a federação de identidade de carga de trabalho na gsutil está disponível na versão 379.0.0 e posteriores da CLI gcloud.
bq
Para autenticar usando a federação de identidade de carga de trabalho, use o comando
gcloud auth login
da seguinte maneira:gcloud auth login --cred-file=FILEPATH.json
Substitua
FILEPATH
pelo caminho do arquivo de configuração de credencial.O suporte para a federação de identidade de carga de trabalho no bq está disponível na versão 390.0.0 e posteriores da CLI gcloud.
A seguir
- Leia mais sobre a federação de identidade da carga de trabalho.
- Conheça as práticas recomendadas para usar a federação de identidade da carga de trabalho.
- Veja como gerenciar pools e provedores de identidade de carga de trabalho.