Este documento mostra como configurar a federação de identidade da força de trabalho com o PingOne Advanced Identity Cloud (AIC) como um provedor de identidade (IdP) e gerenciar o acesso ao Google Cloud. Depois de configurar o IdP do PingOne AIC, os usuários federados podem acessar serviços do Google Cloud que oferecem suporte à federação de identidade da força de trabalho usando o protocolo SAML 2.0.
Antes de começar
- Verifique se você configurou uma organização do Google Cloud .
-
Instale a CLI do Google Cloud. Após a instalação, inicialize a Google Cloud CLI executando o seguinte comando:
gcloud initAo usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.
- Para fazer login, seu IdP precisa fornecer informações de autenticação assinadas. As respostas do IdP SAML precisam ser assinadas.
- Para receber informações importantes sobre mudanças na sua organização ou nos produtos doGoogle Cloud , forneça os Contatos essenciais. Para mais informações, consulte a visão geral da federação de identidade de colaboradores.
Custos
A federação de identidade da força de trabalho está disponível como um recurso sem custo financeiro. No entanto, o registro de auditoria detalhado da federação de identidade da força de trabalho usa o Cloud Logging. Para saber mais sobre os preços do Logging, consulte Preços do Google Cloud Observability.
Funções exigidas
Para receber as permissões
necessárias para configurar a federação de identidade de colaboradores,
peça ao administrador para conceder a você o
papel do IAM de Administrador de pool de colaboradores do IAM (roles/iam.workforcePoolAdmin) na organização.
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 usando papéis personalizados ou outros papéis predefinidos.
Se você configurar permissões em um ambiente de desenvolvimento ou teste, mas não em um ambiente de produção, conceda o papel básico de proprietário do Identity and Access Management (IAM, na sigla em inglês) (roles/owner). Esse papel também inclui permissões para
a federação de identidade de colaboradores.
Criar um pool de identidades da força de trabalho
gcloud
Para criar o pool de identidade de colaboradores, execute o seguinte comando:
gcloud iam workforce-pools create WORKFORCE_POOL_ID \
--organization=ORGANIZATION_ID \
--display-name="DISPLAY_NAME" \
--description="DESCRIPTION" \
--session-duration=SESSION_DURATION \
--location=global
Substitua:
WORKFORCE_POOL_ID: um ID escolhido para representar o Google Cloud pool de forças de trabalho. O ID do pool precisa ser globalmente exclusivo em todos os pools de identidades de força de trabalho no Google Cloud. Para informações sobre como formatar o ID, consulte a seção Parâmetros de consulta na documentação da API.ORGANIZATION_ID: o ID da organização numérico da sua Google Cloud organização para o pool de identidade da força de trabalho. Os pools de identidades da força de trabalho estão disponíveis em todos os projetos e pastas da organização.DISPLAY_NAME: opcional. Um nome de exibição para o pool de identidade de colaboradores.DESCRIPTION: opcional. : uma descrição do pool de identidade de colaboradoresSESSION_DURATION: opcional. A duração da sessão, expressa como um número anexado coms, por exemplo,3600s. A duração da sessão determina por quanto tempo os tokens de acesso do Google Cloud , as sessões de login do console (federado) e o login da CLI gcloud deste pool de força de trabalho são válidos. A duração padrão da sessão é de uma hora (3.600 segundos). O valor da duração da sessão precisa estar entre 15 minutos (900s) e 12 horas (43.200s).
Console
Para criar o pool de identidades de colaboradores, faça o seguinte:
No console Google Cloud , acesse a página Pools de identidade da força de trabalho:
Selecione a organização do pool de identidade da força de trabalho. Os pools de identidades da força de trabalho estão disponíveis em todos os projetos e pastas de uma organização.
Clique em Criar pool e faça o seguinte:
No campo Nome, digite o nome de exibição do pool. O ID do pool é derivado automaticamente do nome à medida que você digita e é exibido no campo Nome. Para atualizar o ID do pool, clique em Editar ao lado dele.
Opcional: em Descrição, insira uma descrição do pool.
Para criar o pool de identidades de colaboradores, clique em Próxima.
A duração da sessão do pool de identidade de colaboradores é de uma hora (3.600 segundos) por padrão. A duração da sessão determina por quanto tempo os tokens de acesso do Google Cloud , o console (federado) e as sessões de login da CLI gcloud desse pool de força de trabalho são válidos. Depois de criar o pool, é possível atualizá-lo para definir uma duração da sessão personalizada. A duração da sessão precisa ser de 15 minutos (900 s) a 12 horas (43.200 s).
Criar um aplicativo de IA do PingOne
Nesta seção, mostramos como criar uma integração de aplicativo do PingOne AIC.
Criar um IdP hospedado
- Em Native Consoles > Access Management, acesse Realms > REALM_NAME > Dashboard e clique em SAML Applications.
- Clique em Adicionar provedor de entidade > Hospedado.
Insira um ID da entidade. Anote esse valor para usar depois.
- Verifique se o valor do URL base do provedor de entidades está correto. O Advanced Identity Cloud usa esse valor para todos os endpoints relacionados ao SAML 2.0.
- Na seção Pseudônimos de metadados, forneça um valor compatível com URL na propriedade Pseudônimo de metadados do provedor de identidade. Esse alias precisa ser exclusivo no círculo de confiança.
- Clique em Criar.
- Na guia Processamento de declaração, na seção Mapeador de atributos, mapeie os nomes de atributos SAML para nomes de atributos locais. Os nomes dos atributos SAML são os usados em uma declaração.
- Clique em Adicionar ou Atualizar para cada mapeamento.
- Clique em Salvar alterações.
Usar atributos
Esta seção descreve como usar atributos da declaração SAML.
Nos exemplos a seguir, os atributos na declaração SAML são mapeados para atributos locais:
| Atributo SAML | Atributo local |
|---|---|
IDPEmail |
mail |
FirstName |
givenName |
groups |
groups |
Configure os atributos obrigatórios na seção de mapeamento de atributos. Você vai mapear esses atributos ao criar o provedor de pool de identidades da força de trabalho mais adiante neste guia.
Exportar metadados do provedor
É possível acessar os metadados do SAML 2.0 do seu provedor hospedado de uma das seguintes maneiras:
Por REST
Execute este comando:
curl --output METADATA_XML \ "https://TENANT_ENV_FQDN/am/ExportSamlMetadata?entityid=ENTITY_ID&realm=/REALM"Em um navegador
Abra o URL de metadados do ambiente do seu locatário em um navegador para baixar o arquivo XML:
https://TENANT_ENV_FQDN/am/ExportSamlMetadata?entityid=ENTITY_ID&realm=/REALM
- Salve o arquivo XML na sua máquina local.
Importar o Google como um SP remoto
Prepare o XML de metadados do Google Cloud SP. Use o modelo a seguir, substituindo os valores de marcador:
<?xml version="1.0" encoding="UTF-8"?> <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="https://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID"> <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat> <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat> <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID" index="0" isDefault="true"/> </md:SPSSODescriptor> </md:EntityDescriptor>Importe os metadados de uma das seguintes maneiras:
No console
- No console de administrador do PingOne AIC, acesse SAML Applications.
- Clique em Adicionar provedor de entidade > Remoto.
- Faça upload do arquivo XML de metadados do Google Cloud SP que você acabou de criar.
- Clique em Criar.
Por REST
- Converta os metadados XML em uma string codificada em base64url.
- Receba um token de acesso.
Execute este comando:
curl --request POST \ --header 'authorization: Bearer ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --header 'Accept-API-Version: resource=1.0' \ --data-raw '{"standardMetadata": "BASE64URL_ENCODED_METADATA"}' \ 'https://TENANT_ENV_FQDN/am/json/realms/root/realms/alpha/realm-config/saml2/remote?_action=importEntity'
Criar um círculo de confiança (CoT)
- Navegue até Realms > REALM_NAME > Applications > Federation > Circles of Trust.
- Clique em Adicionar círculo de confiança.
- Digite um nome e clique em Criar.
- Na página Círculo de confiança, na propriedade Provedores de entidades, selecione seu IdP hospedado e o Google Cloud SP remoto.
- Clique em Salvar alterações.
Criar o provedor de pool de identidade de colaboradores da AIC do PingOne
Nesta seção, descrevemos como criar um provedor de pool de identidade da força de trabalho para permitir que os usuários do IdP acessem Google Cloud. É possível configurar o provedor para usar o protocolo SAML.
Criar um provedor de pool de identidade de colaboradores SAML
Para criar um provedor de pool de identidade de colaboradores SAML, verifique se os metadados do provedor de identidade incluem pelo menos o ID da entidade SAML, o URL de Logon único e uma chave pública de assinatura. Para isso, siga estas etapas:
gcloud
Salve os metadados SAML do app PingOne AIC.
Para criar o provedor de pool de identidade de colaboradores SAML, execute o seguinte comando:
gcloud iam workforce-pools providers create-saml WORKFORCE_PROVIDER_ID \ --workforce-pool="WORKFORCE_POOL_ID" \ --display-name="DISPLAY_NAME" \ --description="DESCRIPTION" \ --idp-metadata-path="XML_METADATA_PATH" \ --attribute-mapping="ATTRIBUTE_MAPPING" \ --attribute-condition="ATTRIBUTE_CONDITION" \ --location=globalSubstitua:
WORKFORCE_PROVIDER_ID: um ID de provedor.WORKFORCE_POOL_ID: o ID do pool de identidade da força de trabalho.DISPLAY_NAME: um nome de exibição.DESCRIPTION: uma descrição.XML_METADATA_PATH: o caminho para o arquivo de metadados formatado em XML que você exportou do PingOne AIC.ATTRIBUTE_MAPPING: o mapeamento de atributo. Por exemplo,google.subject=assertion.subject,google.groups=assertion.attributes.groups,attribute.department=assertion.attributes.department[0].ATTRIBUTE_CONDITION: uma condição de atributo opcional. Por exemplo, para limitar o atributoipaddra um determinado intervalo de IP, defina a condiçãoassertion.ipaddr.startsWith('98.11.12.').
Para mais informações, consulte Mapeamento de atributos.
Esse comando atribui
subject,groupsedepartmentna declaração SAML aos atributosgoogle.subject,google.groupseattribute.department, respectivamente. A condição de atributo também garante que apenas usuários em um determinado intervalo de IP possam fazer login usando esse provedor de força de trabalho.
Console
Para configurar o provedor SAML usando o console Google Cloud , faça o seguinte:
- No console Google Cloud , acesse a página Pools de identidade da força de trabalho: Acessar os pools de identidade da força de trabalho
- Na tabela Pools de identidade de colaboradores, selecione o pool em que você quer criar o provedor.
- Na seção Provedores, clique em Adicionar provedor.
- Na lista Selecionar um fornecedor de provedor, escolha Provedor de identidade genérico.
- Em Selecionar um protocolo de autenticação, escolha SAML.
- Na seção Criar um provedor, faça o seguinte:
- Em Nome, digite um nome para o provedor.
- Opcional: em Descrição, digite uma descrição para o provedor.
- Em Arquivo de metadados do IdP (XML), selecione o arquivo XML de metadados exportado do PingOne AIC.
- Para criar um provedor ativado, verifique se a opção Ativar provedor está ativada.
- Clique em Continuar.
- Na seção Compartilhe as informações do provedor, clique em Continuar.
- Opcional: para ativar a geração de registros de auditoria detalhada, na seção Configurar provedor, em Registro detalhado, clique no botão Ativar a geração de registros de auditoria do valor do atributo.
A federação de identidade de colaboradores registro de auditoria detalhado registra as informações recebidas do seu IdP no Cloud Logging. O registro de auditoria detalhado pode ajudar você a resolver problemas na configuração do provedor de pool de identidade da força de trabalho. Para saber como resolver problemas de mapeamento de atributos com registros de auditoria detalhados, consulte Erros gerais de mapeamento de atributos. Para saber mais sobre os preços do Logging, consulte Preços do Google Cloud Observability.
Para desativar o registro de auditoria detalhado de um provedor de pool de identidades da força de trabalho, deixe a opção Ativar a geração de registros de auditoria do valor do atributo desativada ao criar o provedor. Para desativar o registro de auditoria detalhado, também é possível atualizar o provedor.
- Para criar o provedor, clique em Enviar.
Depois que o provedor for criado, você será redirecionado para a página de atributos dele.
Para configurar mapeamentos e condições de atributos, faça o seguinte:
- Quando solicitado, faça login no seu IdP externo para validar os mapeamentos de atributos padrão.
Na página de atributos do provedor, veja e edite os mapeamentos e as condições de atributos:
Para adicionar ou editar mapeamentos de atributos, faça o seguinte:
- Clique em Adicionar mapeamento para incluir um novo ou edite os mapeamentos atuais.
- No campo Google n, em que n é um número, selecione uma chave compatível com Google Cloud.
No campo SAML n correspondente, insira o nome do atributo do IdP ou uma expressão CEL. Por exemplo:
google.subject=assertion.subject, google.groups=assertion.attributes['https://example.com/aliases'], attribute.costcenter=assertion.attributes.costcenter[0]
Para adicionar uma condição de atributo, faça o seguinte:
- Clique em Adicionar condição.
- No campo Condições de atributo, insira uma condição no formato CEL. Por exemplo,
assertion.attributes.ipaddr.startsWith('98.11.12.').
Para validar seus mapeamentos, clique em Salvar e buscar token novamente.
Para concluir a configuração, clique em Salvar e sair.
Gerenciar o acesso a recursos do Google Cloud
Nesta seção, mostramos como gerenciar o acesso aos recursos do Google Cloud para usuários da AIC do PingOne.
O projeto de amostra usado neste guia pode ser diferente do projeto que você usou para configurar a federação de identidade da força de trabalho.
É possível gerenciar papéis para identidades únicas, um grupo de identidades ou um pool inteiro. Para mais informações, consulte Identificadores principais de colaboradores para políticas de permissão.
Usar atributos de departamento mapeados
Para conceder o papel de administrador do Storage (roles/storage.admin) a todas as identidades em um departamento específico do projeto TEST_PROJECT_ID, execute o seguinte comando:
gcloud projects add-iam-policy-binding TEST_PROJECT_ID \
--role="roles/storage.admin" \
--member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/attribute.department/DEPARTMENT_VALUE"
Substitua:
TEST_PROJECT_ID: o ID do projeto;WORKFORCE_POOL_ID: o ID do pool de identidade da força de trabalho.DEPARTMENT_VALUE: o valor mapeado deattribute.department.
Usar grupos mapeados
Para conceder o papel de administrador do Storage (roles/storage.admin) a todas as identidades no grupo GROUP_ID para o projeto TEST_PROJECT_ID, execute o seguinte comando:
gcloud projects add-iam-policy-binding TEST_PROJECT_ID \
--role="roles/storage.admin" \
--member="principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/group/GROUP_ID"
Substitua:
TEST_PROJECT_ID: o ID do projeto;WORKFORCE_POOL_ID: o ID do pool de identidade da força de trabalho.GROUP_ID: um grupo na declaraçãogoogle.groupsmapeada.
Fazer login e testar o acesso
Nesta seção, faça login como usuário do pool de identidades de força de trabalho e teste seu acesso.
Fazer login
login no console (federado)
Para fazer login no console da Google Cloud federação de identidade de colaboradores, também conhecido como console (federado), faça o seguinte:
-
Acesse a página de login no console (federada).
-
Digite o nome do provedor no formato a seguir:
locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
Insira suas credenciais do PingOne AIC quando solicitado.
Login baseado no navegador da Google Cloud CLI
Para fazer login na CLI gcloud usando um fluxo de login baseado em navegador:
Execute o comando a seguir para criar um arquivo de configuração de login:
Linux e macOS
gcloud iam workforce-pools create-login-config \ locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \ --output-file=LOGIN_CONFIG_PATH
Windows (PowerShell)
gcloud iam workforce-pools create-login-config ` locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID ` --output-file=LOGIN_CONFIG_PATH
Substitua:
WORKFORCE_POOL_ID: o ID do pool de federação de identidade da força de trabalho.WORKFORCE_PROVIDER_ID: o ID do provedor da Federação de identidade de colaboradores.-
LOGIN_CONFIG_PATH: o caminho para gravar o arquivo de configuração de login. Por exemplo,login-config.json.
O arquivo de configuração de login contém os endpoints usados pela CLI gcloud para ativar o fluxo de autenticação baseado em navegador e definir o público como o IdP configurado no provedor do pool de identidade de colaboradores. O arquivo não contém informações confidenciais.
O conteúdo do arquivo de configuração de login é semelhante a este:
{ "universe_domain": "googleapis.com", "universe_cloud_web_domain": "cloud.google", "type": "external_account_authorized_user_login_config", "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID", "auth_url": "https://auth.cloud.google/authorize", "token_url": "https://sts.googleapis.com/v1/oauthtoken", "token_info_url": "https://sts.googleapis.com/v1/introspect" }
Aponte para o arquivo de configuração de login com uma variável de ambiente, uma propriedade na configuração ativa da CLI gcloud ou use-o diretamente com o comando gcloud auth login:
Variável de ambiente
Para usar o arquivo de configuração de login com uma variável de ambiente, siga estas instruções:
-
Defina a variável de ambiente
CLOUDSDK_AUTH_LOGIN_CONFIG_FILEcomo o caminho do arquivo de configuração de login. -
Execute este comando:
gcloud auth login
- A CLI gcloud faz referência à variável de ambiente para encontrar o arquivo de configuração de login e inicia o processo de autenticação. Siga o fluxo baseado no navegador para autenticar e autorizar a CLI gcloud a acessar recursos em seu nome para comandos futuros.
Para parar de usar o arquivo de configuração de login para comandos gcloud auth login, limpe
a variável de ambiente CLOUDSDK_AUTH_LOGIN_CONFIG_FILE.
Configuração da CLI gcloud
Para usar o arquivo de configuração de login com uma propriedade de configuração da CLI gcloud, siga estas instruções:
-
Defina a propriedade
auth/login_config_fileda configuração ativa da CLI gcloud como o caminho do arquivo de configuração de login com o seguinte comando:gcloud config set auth/login_config_file LOGIN_CONFIG_PATH
-
Execute este comando:
gcloud auth login
- A CLI gcloud faz referência à propriedade de configuração para encontrar o arquivo de configuração de login e inicia o processo de autenticação. Siga o fluxo baseado no navegador para autenticar e autorizar a CLI gcloud a acessar recursos em seu nome para comandos futuros.
Para parar de usar o arquivo de configuração de login para comandos gcloud auth login, desative
a propriedade com o seguinte comando:
gcloud config unset auth/login_config_file
gcloud auth login
Para usar o arquivo de configuração de login diretamente com o comando gcloud auth login, siga estas instruções:
-
Se você usou a flag
--activateao criar o arquivo de configuração de login, execute o seguinte comando:gcloud auth login
-
Se você não usou a flag
--activateao criar o arquivo de configuração de login, execute o seguinte comando:Linux e macOS
gcloud auth login \ --login-config=LOGIN_CONFIG_PATH
Windows (PowerShell)
gcloud auth login ` --login-config=LOGIN_CONFIG_PATH
Substitua LOGIN_CONFIG_PATH pelo caminho do arquivo de configuração de login.
O comando gcloud auth login armazena credenciais de acesso no seu diretório principal. O principal autenticado se torna o principal ativo na configuração ativa da CLI gcloud. A menos que sejam substituídas, a CLI gcloud usa essas credenciais armazenadas para acessar o Google Cloud.
Login headless da CLI gcloud
Para fazer login no PingOne AIC com a CLI gcloud usando o protocolo SAML, faça o seguinte:
- Faça login de um usuário no aplicativo AIC do PingOne e receba a resposta SAML.
- Salve a resposta SAML retornada pelo PingOne AIC em um local seguro da sua máquina local. Armazene o caminho em uma variável de ambiente, por exemplo:
SAML_ASSERTION_PATH=/tmp/saml_assertion.xml. Gere um arquivo de configuração:
gcloud iam workforce-pools create-cred-config \ locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \ --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \ --credential-source-file=SAML_ASSERTION_PATH \ --workforce-pool-user-project=PROJECT_ID \ --output-file=config.jsonSubstitua:
SAML_ASSERTION_PATH: o caminho do arquivo de declaração SAML.PROJECT_ID: o ID do projeto;
O arquivo de configuração gerado é semelhante a este:
{ "type": "external_account", "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID", "subject_token_type": "urn:ietf:params:oauth:token-type:saml2", "token_url": "https://sts.googleapis.com/v1/token", "credential_source": { "file": "SAML_ASSERTION_PATH" }, "workforce_pool_user_project": "PROJECT_ID" }Para fazer login na CLI gcloud usando a troca de tokens, execute o seguinte comando:
gcloud auth login --cred-file=config.jsonEm seguida, o
gcloudtroca suas credenciais do PingOne AIC por tokens de acesso temporários do Google Cloud , permitindo que você faça outras chamadas degcloudpara o Google Cloud. O resultado será o seguinte:Authenticated with external account user credentials for: [principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/USER_ID].Para listar as contas credenciadas e a conta ativa, execute o seguinte comando:
gcloud auth list
Testar o acesso
Você pode acessar os serviços do Google Cloud que oferecem suporte à federação de identidade de colaboradores e a que você tem acesso. No início deste guia, você concedeu o papel de Administrador do Storage a todas as identidades de um departamento ou grupo específico no projeto TEST_PROJECT_ID. Para testar o acesso, liste os buckets do Cloud Storage.
login no console (federado)
Para verificar seu acesso no console (federado), faça o seguinte:
- Acessar a página do Cloud Storage.
- Verifique se é possível ver a lista de buckets para o projeto
TEST_PROJECT_ID.
CLI da gcloud
Para listar os buckets e objetos do Cloud Storage para o projeto a que você tem acesso, execute o seguinte comando:
gcloud alpha storage ls --project="TEST_PROJECT_ID"
O principal precisa ter a permissão serviceusage.services.use no projeto definido na sessão da CLI gcloud: PROJECT_ID.
A seguir
- Excluir os usuários da federação de identidade de colaboradores e respectivos dados.
- Saiba quais produtos do Google Cloud são compatíveis com a federação de identidade da força de trabalho.
- Configure o acesso do usuário ao console (federado).