Configurar a federação de identidade de colaboradores com o PingFederate

Este documento mostra como configurar a federação de identidade de colaboradores com o provedor de identidade (IdP) do PingFederate e gerenciar o acesso a Google Cloud. Depois de configurar o IdP do PingFederate, os usuários federados podem acessar Google Cloud serviços que oferecem suporte à federação de identidade de colaboradores usando o protocolo SAML 2.0.

Antes de começar

1. Verifique se você configurou uma Google Cloud organização.

2. Instale a Google Cloud CLI. Após a instalação, inicialize a Google Cloud CLI executando o seguinte comando:

   gcloud init

   Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

   Observação: se você instalou a CLI gcloud anteriormente, verifique se tem a versão mais recente executando gcloud components update.
Para configurar um aplicativo do PingFederate que usa o protocolo SAML 2.0, faça o seguinte no PingFederate:
1. Defina o ID da entidade SAML 2.0 do seu IdP do PingFederate. Para mais detalhes, consulte Especificar informações de federação.

2. Crie uma conexão de SP SAML 2.0. Consulte Escolher um tipo de conexão de SP e faça o seguinte:

   1. Em Tipo de conexão, selecione Perfis de SSO do navegador e Protocolo SAML 2.0.
   2. Em Importar metadados, selecione Nenhum.

3. Em Informações gerais, defina o ID da entidade do parceiro (ID da conexão) como:

   https://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
   

4. Em Perfis SAML, ative o SSO iniciado pelo SP. Se você também planeja usar o Logon único (SSO) iniciado pelo IdP, também é possível ativá-lo.

5. Em Contrato de atributo, defina atributos personalizados (por exemplo, e-mail e grupos) a serem transmitidos na declaração. Esses atributos podem ser usados em Google Cloud para criar políticas de gerenciamento de acesso mais tarde.

6. Em Preenchimento do contrato de atributo, verifique se SAML_SUBJECT está mapeado para um campo que tem um valor exclusivo para cada usuário. Por exemplo, um endereço de e-mail geralmente é exclusivo para cada usuário, não muda e é usado com frequência para se referir a um usuário específico em Google Cloud políticas de gerenciamento de acesso.

7. Para configurar o login no console (federado), em URL do serviço de declaração de consumidor, adicione o seguinte URL do endpoint:

   https://auth.cloud.google/signin-callback/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID
   

   Substitua:

   • WORKFORCE_POOL_ID: o ID do pool de colaboradores que você criou anteriormente.
   • WORKFORCE_PROVIDER_ID: o ID do provedor de colaboradores que você cria mais tarde.

8. Defina Vinculação para esse endpoint como POST.

9. Para ativar o login no console (federado), em Vinculações SAML permitidas, selecione Redirecionar.

10. Em Política de assinatura, selecione Assinar resposta conforme necessário.

11. Salve e ative a conexão.

Usar atributos

Esta seção descreve como usar atributos da declaração SAML.

Use contratos de atributo para especificar os atributos personalizados nas declarações SAML geradas. Depois de configurar os atributos, você pode usá-los em Google Cloud para criar políticas de gerenciamento de acesso. Para saber mais sobre contratos de atributo, consulte Contratos de atributo na documentação do servidor do PingFederate.

Por exemplo, neste guia, usamos o PingOne como o armazenamento de dados do PingFederate e mapeamos os contratos de atributo email, firstName e groups usando os atributos do usuário do armazenamento de dados do PingOne, da seguinte maneira:

Contrato de atributo	Valor
email	email
firstName	name.given
groups	memberOfGroupIDs

Criar o provedor de pool de identidade de colaboradores do PingFederate

Esta seção descreve como criar um provedor de pool de identidade de colaboradores 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 2.0

1. Para configurar o aplicativo SAML, faça o seguinte:

   gcloud

   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=global
   

   Substitua:

   • WORKFORCE_PROVIDER_ID: um ID do provedor.
   • WORKFORCE_POOL_ID: o ID do pool de identidade de colaboradores.
   • DISPLAY_NAME: um nome de exibição.
   • DESCRIPTION: uma descrição.
   • XML_METADATA_PATH: o caminho para o arquivo de metadados formatado em XML do PingFederate.
   • 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 atributo ipaddr a um determinado intervalo de IP, defina a condição como assertion.ipaddr.startsWith('98.11.12.').

   Esse comando atribui subject, groups e department na declaração SAML aos atributos google.subject, google.groups e attribute.department, respectivamente. A condição de atributo também garante que apenas usuários dentro de um determinado intervalo de IP possam fazer login usando esse provedor de colaboradores.

   Console

   Para configurar o provedor SAML usando o Google Cloud console, faça o seguinte:

   1. No Google Cloud console, acesse a página Pools de identidade de colaboradores: Acesse Pools de identidade de colaboradores
   2. Na tabela Pools de identidade de colaboradores, selecione o pool para o qual você quer criar o provedor.
   3. Na seção Provedores, clique em Adicionar provedor.
   4. Na lista Selecionar um fornecedor de provedor, selecione Provedor de identidade genérico.
   5. Em Selecionar um protocolo de autenticação, selecione SAML.
   6. Na seção Criar um provedor, faça o seguinte:
      1. Em Nome, digite um nome para o provedor.
      2. Em Arquivo de metadados do IdP (XML), selecione o arquivo XML de metadados do PingFederate.
      3. Clique em Continuar.
   7. Na seção Compartilhar as informações do provedor, clique em Continuar.

   8. Na seção Configurar provedor, faça o seguinte:

      1. Em Mapeamento de atributos, insira uma expressão CEL para google.subject (por exemplo, assertion.subject).

      2. Opcional: para inserir outros mapeamentos, clique em Adicionar mapeamento e insira outros, por exemplo:

         google.subject=assertion.subject,
         google.groups=assertion.attributes['https://example.com/aliases'],
         attribute.costcenter=assertion.attributes.costcenter[0]
         

   9. Para ativar o registro de auditoria detalhado, em Registro detalhado, clique no botão Ativar registro de auditoria do valor do atributo.

   10. Para criar o provedor, clique em Enviar.

Gerenciar o acesso a Google Cloud recursos

Esta seção mostra como gerenciar o acesso a Google Cloud recursos para usuários do PingFederate.

O projeto de amostra usado neste guia pode ser diferente do projeto usado para configurar a federação de identidade de colaboradores.

É possível gerenciar papéis para identidades únicas, um grupo de identidades ou um pool inteiro. Para mais informações, consulte Representar usuários do pool de identidades de força de trabalho nas políticas do IAM.

Usar atributos de departamento mapeados

Para conceder o papel de Administrador do Storage (roles/storage.admin) a todas as identidades de 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 de colaboradores;
• DEPARTMENT_VALUE: o valor attribute.department mapeado.

Usar grupos mapeados

Para conceder o papel de Administrador do Storage (roles/storage.admin) a todas as identidades do 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 de colaboradores;
• GROUP_ID: um grupo na declaração google.groups mapeada.

Fazer login e testar o acesso

Nesta seção, você faz login como um usuário do pool de identidade de colaboradores e testa seu acesso.

Fazer login

login no console (federado)

Para fazer login no Google Cloud console de federação de identidade de colaboradores, também conhecido como console (federado), faça o seguinte:

1. Acesse a página de login no console (federado).

   Acesse o console (federado)

2. Digite o nome do provedor no formato a seguir:

   locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID

Insira suas credenciais do PingFederate quando solicitado.

Login baseado no navegador da CLI gcloud

Para fazer login na CLI gcloud usando um fluxo de login baseado em navegador:

Para criar o arquivo de configuração de login, execute o comando a seguir. Também é possível ativar o arquivo como padrão para a CLI gcloud adicionando a --activate flag. Em seguida, execute gcloud auth login sem especificar o caminho do arquivo de configuração a cada vez.

gcloud iam workforce-pools create-login-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --output-file=LOGIN_CONFIG_FILE_PATH

Substitua:

• WORKFORCE_POOL_ID: o ID do pool de colaboradores
• PROVIDER_ID: o ID do provedor
• LOGIN_CONFIG_FILE_PATH: o caminho para um arquivo de configuração especificado. Por exemplo, login.json

O arquivo 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 que foi configurado no provedor de pool de identidade de colaboradores. O arquivo não contém informações confidenciais.

A saída será assim:

{
  "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"
}

Atenção: recomendamos que você confira se o conteúdo do arquivo está correto e depois o proteja. Por exemplo, torne-o somente leitura e restrinja o acesso com uma ACL. O arquivo não é validado. Um agente malicioso com acesso de gravação a esse arquivo pode mudar os endpoints e interceptar credenciais.

Para impedir que gcloud auth login use esse arquivo de configuração automaticamente, cancele a definição executando gcloud config unset auth/login_config_file.

Para usar a autenticação de login baseada em navegador, use um dos seguintes métodos:

• Se você usou a flag --activate ao criar o arquivo de configuração ou se você ativou o arquivo de configuração com gcloud config set auth/login_config_file, a CLI gcloud fará uso dele automaticamente:

  gcloud auth login

• Para fazer login especificando o local do arquivo de configuração, execute o seguinte comando:

  gcloud auth login --login-config=LOGIN_CONFIG_FILE_PATH

• Para usar uma variável de ambiente para especificar o local do arquivo de configuração, defina CLOUDSDK_AUTH_LOGIN_CONFIG_FILE como o caminho de configuração.

Para interromper o uso do arquivo de configuração de login, faça o seguinte:

• Se você usou a flag --activate ao criar o arquivo de configuração ou ativou esse arquivo com gcloud config set auth/login_config_file, execute o seguinte comando para cancelar a definição:

  gcloud config unset auth/login_config_file

• Limpe a variável de ambiente CLOUDSDK_AUTH_LOGIN_CONFIG_FILE, se ela estiver definida.

Login headless da CLI gcloud

Para fazer login no PingFederate com a CLI gcloud usando o protocolo SAML, faça o seguinte:

1. Faça login de um usuário no app PingFederate e receba a resposta SAML.
2. Salve a resposta SAML retornada pelo PingFederate em um local seguro da máquina local. Armazene o caminho em uma variável de ambiente. Por exemplo: SAML_ASSERTION_PATH=/path/to/assertion.xml.

3. 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.json
   

   Substitua:

   • SAML_ASSERTION_PATH: o caminho do arquivo de declaração SAML.
   • PROJECT_ID: o ID do projeto;

4. O arquivo de configuração gerado é semelhante ao seguinte:

   {
     "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"
   }
   

5. Para fazer login na CLI gcloud usando a troca de tokens, execute o seguinte comando:

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

   Em seguida, o gcloud troca suas credenciais do PingFederate por tokens de acesso temporários Google Cloud , permitindo que você faça outras chamadas de gcloud para 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].

6. Para listar as contas credenciadas e a conta ativa, execute o seguinte comando:

   gcloud auth list
   

Testar o acesso

Você tem acesso aos Google Cloud serviços 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:

1. Acessar a página do Cloud Storage.
2. Verifique se você pode conferir a lista de buckets atuais do projeto TEST_PROJECT_ID.

CLI 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 Google Cloud produtos oferecem suporte à federação de identidade de colaboradores.
• Configurar o acesso do usuário ao console (federado).