Configurar a federação de identidade de colaboradores com o PingOne AIC

Este documento mostra como configurar a federação de identidade de colaboradores 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 os serviços do Google Cloud 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 organização do Google Cloud .

2. Instale a CLI do Google Cloud. 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ê já instalou a CLI gcloud, execute o comando gcloud components update para verificar se tem a versão mais recente.

Criar um IdP hospedado

1. Em Consoles nativos > Gerenciamento de acesso, acesse Reinos > REALM_NAME > Painel e clique em Aplicativos SAML.
2. Clique em Adicionar provedor de entidade > Hospedado.

3. Insira um ID da entidade. Anote esse valor para usar depois.

   Observação: o Advanced Identity Cloud trunca vários espaços em um único espaço em valores como IDs de entidade. Por exemplo, se o valor MyEntityID (um espaço) existir, adicionar uma nova entidade chamada My Entity ID (vários espaços) vai causar um erro porque o Advanced Identity Cloud os trata como idênticos.
   1. 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.
   2. 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.
   3. Clique em Criar.
   4. 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 de atributos SAML são os usados em uma declaração.
   5. Clique em Adicionar ou Atualizar para cada mapeamento.
   6. 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 para 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

1. Salve o arquivo XML na sua máquina local.

Importar o Google como um SP remoto

1. 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>
   

2. Importe os metadados de uma das seguintes maneiras:

   • No console

     1. No console de administrador do PingOne AIC, acesse SAML Applications.
     2. Clique em Adicionar provedor de entidade > Remoto.
     3. Faça upload do arquivo XML de metadados do Google Cloud SP que você acabou de criar.
     4. Clique em Criar.

   • Por REST

     1. Converta os metadados XML em uma string codificada em base64url.
     2. Receba um token de acesso.

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

1. Navegue até Realms > REALM_NAME > Applications > Federation > Circles of Trust.
2. Clique em Adicionar círculo de confiança.
3. Digite um nome e clique em Criar.
4. Na página Círculo de confiança, na propriedade Provedores de entidades, selecione seu IdP hospedado e o Google Cloud SP remoto.
5. 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

1. Para criar um provedor de pool de identidade da força de trabalho 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

   1. Salve os metadados SAML do seu app PingOne AIC.

   2. 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 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 atributo ipaddr a um determinado intervalo de IP, defina a condição assertion.ipaddr.startsWith('98.11.12.').

      Para mais informações, consulte Mapeamento de atributos.

      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 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:

   1. 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
   2. Na tabela Pools de identidade de colaboradores, selecione o pool em que você quer criar o provedor.
   3. Na seção Provedores, clique em Adicionar provedor.
   4. Na lista Selecionar um fornecedor de provedor, escolha Provedor de identidade genérico.
   5. Em Selecionar um protocolo de autenticação, escolha SAML.
   6. Na seção Criar um provedor, faça o seguinte:
      1. Em Nome, digite um nome para o provedor.
      2. Opcional: em Descrição, digite uma descrição para o provedor.
      3. Em Arquivo de metadados do IdP (XML), selecione o arquivo XML de metadados exportado do PingOne AIC.
      4. Verifique se o Provedor ativado está ativado.
      5. Clique em Continuar.
   7. Na seção Compartilhe 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]
         

      3. Opcional: para adicionar uma condição de atributo, clique em Adicionar condição e insira uma expressão CEL que represente uma condição de atributo. Por exemplo, para limitar o atributo ipaddr a um determinado intervalo de IP, defina a condição assertion.attributes.ipaddr.startsWith('98.11.12.'). Este exemplo de condição garante que apenas os usuários com um endereço IP que comece com 98.11.12. possam fazer login usando esse provedor de força de trabalho.

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

   10. Para criar o provedor, clique em Enviar.

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 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 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 de attribute.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ção google.groups mapeada.

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:

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

   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 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:

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 flag --activate. Assim, você pode executar gcloud auth login sem especificar o caminho do arquivo de configuração todas as vezes.

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 configurado no provedor do pool de identidades dos 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 foi validado. Uma pessoa mal-intencionada com acesso de gravação a este arquivo pode alterar os endpoints e interceptar as credenciais.

Para impedir que o gcloud auth login use esse arquivo de configuração automaticamente, execute gcloud config unset auth/login_config_file para desativá-lo.

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 ativou esse arquivo 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 PingOne AIC com a CLI gcloud usando o protocolo SAML, faça o seguinte:

1. Faça login de um usuário no aplicativo PingOne AIC e receba a resposta SAML.
2. Salve a resposta SAML retornada pelo PingOne AIC em um local seguro na sua máquina local. Armazene o caminho em uma variável de ambiente, por exemplo: SAML_ASSERTION_PATH=/tmp/saml_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 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"
   }
   

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 PingOne AIC por tokens de acesso temporários do Google Cloud , permitindo que você faça outras chamadas de gcloud para 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].

6. 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:

1. Acessar a página do Cloud Storage.
2. 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 de colaboradores.
• Configure o acesso do usuário ao console (federado).