Conectar o Microsoft Entra ID

Nesta página, descrevemos como conectar o Microsoft Entra ID ao Gemini Enterprise.

Depois de configurar a fonte de dados e importar os dados pela primeira vez, o repositório de dados sincroniza as informações dessa fonte com uma frequência que você seleciona durante a configuração.

Versões compatíveis

O conector do Entra ID é compatível com todas as versões hospedadas do Entra ID pela API Microsoft Graph v1.0.

Antes de começar

Antes de configurar o repositório de dados e importar dados, é necessário ter um ID de cliente e um segredo para autenticação, bem como configurar as permissões mínimas necessárias para o aplicativo. Esta seção fornece informações sobre como concluir essas tarefas.

Configurar o controle de acesso para o Entra ID

Para aplicar o controle de acesso à fonte de dados e proteger os dados no Gemini Enterprise, verifique se você configurou seu provedor de identidade.

Estabelecer um ID e uma chave secreta do cliente

  1. Crie um aplicativo do Entra ID:

    1. Faça login no centro de administração do Microsoft Entra como administrador e clique em App.
    2. Na lista suspensa Aplicativo, clique em Registros de apps.
    3. Na página Registros de apps, clique em Novo registro.
    4. Clique em Adicionar novo registro e faça o seguinte:
      • Insira um nome para o aplicativo.
      • Em Tipos de conta compatíveis, selecione Apenas contas no diretório organizacional.
      • Em URI de redirecionamento, adicione um URI de redirecionamento da Web que aponte para: https://login.microsoftonline.com/common/oauth2/nativeclient.
    5. Clique em Registrar.

  2. Salvar credenciais:

    Na janela do aplicativo registrado, salve os seguintes valores para uso posterior:

    1. Use o ID do aplicativo (cliente) para definir o parâmetro ID do cliente.
    2. Use o ID do diretório (locatário) para definir o parâmetro Azure Tenant.

  3. Crie uma chave secreta do cliente:

    1. Navegue até Certificados e chaves secretas.
    2. Clique em Nova chave secreta do cliente e especifique uma duração.
    3. Salve a chave secreta do cliente e copie o valor para uso posterior.
save-client-secret-value
Salve o valor da chave secreta do cliente

Configurar as permissões mínimas necessárias para o app

  1. Na janela do aplicativo registrado, clique em Permissões da API.

  2. Em Permissões configuradas, selecione Microsoft Graph e configure as seguintes permissões:

    • User.Read
    • User.Read.All (Application)

    Se você quiser transferir profileCardAttributes, configure as seguintes permissões:

    • People.Read.All (Application)
    • PeopleSettings.Read.All (Application)
    • PeopleSettings.Read.All (Delegated)

  3. Conceda o consentimento do administrador para todas as permissões adicionadas. O consentimento de um administrador é necessário para usar as credenciais do cliente no fluxo de autenticação.

Permissões mínimas

A tabela a seguir lista as permissões mínimas necessárias para criar um conector do Entra ID:

Permissão Motivo do uso Descrição
User.Read Ingestão de dados Ler detalhes da organização durante o estabelecimento da conexão.
User.Read.All (Application) Ingestão de dados Ler todos os usuários na organização.
People.Read.All (Application) Ingestão de dados Ler todas as informações relevantes de pessoas, como contatos, de todos os usuários em uma organização.
PeopleSettings.Read.All (Application) Ingestão de dados Ler as configurações de usuário de todos os usuários na organização, como profileCardSettings.
PeopleSettings.Read.All (Delegated) Ingestão de dados Ler as configurações de usuário de todos os usuários na organização, como profileCardSettings.

Criar um repositório de dados do Entra ID

Para usar o Google Cloud console e sincronizar dados do Entra ID com o Gemini Enterprise, siga estas etapas:

  1. No console do Google Cloud , acesse a página Gemini Enterprise.

    Gemini Enterprise

  2. No menu de navegação, selecione Repositório de dados.

  3. Clique em Criar repositório de dados.

  4. Na página Selecionar uma fonte de dados, role a tela ou pesquise Entra ID para conectar sua fonte de terceiros.

  5. Em Configurações de autenticação, insira o ID e a chave secreta do cliente.

  6. Em Opções avançadas:

    • Se necessário, clique em Ativar endereços IP estáticos. Depois de criar o conector, você vai precisar colocar os IPs estáticos registrados na lista de permissões para que as execuções de sincronização sejam bem-sucedidas.
    • Para permitir que o conector busque propriedades de extensão, que são usadas para adicionar uma propriedade personalizada a um objeto de diretório, marque a caixa de seleção Ativar propriedades de extensão.

    • Se quiser filtrar informações de usuários ingeridas, forneça um filtro SQL personalizado. O filtro precisa ser uma string SQL válida.

      As chaves na string de filtro precisam corresponder aos seguintes campos:

      • Id
      • employeeType
      • onPremisesSyncEnabled
      • accountEnabled

      Confira abaixo exemplos de filtros SQL válidos:

      id = 'abc' AND accountEnabled = true

employeeType='E' AND onPremisesSyncEnabled= true

    • No campo Locatário do Azure, insira o ID do locatário do Azure que você recebeu quando criou um aplicativo do Entra ID.

    • Para aplicar um limite de taxa às consultas que o conector envia para a instância do Entra ID, especifique o número máximo de consultas por segundo no campo QPS máximo. O valor padrão é 80 QPS.

    • Clique em Continuar.

  7. Em Escolher as entidades para sincronizar:

    • Clique em Perfis de usuários. Para filtrar os dados com base em Id para ingestão de dados, clique em Filtrar e faça o seguinte:
      • Para especificar os dados a serem incluídos no índice de pesquisa, selecione Incluir no índice e especifique a string de filtro no campo ID.
      • Para especificar os dados que serão excluídos do índice de pesquisa, selecione Excluir do índice e especifique a string de filtro no campo ID.
    • Selecione a frequência de Sincronização completa.

  8. Clique em Continuar.

  9. Em Configurar o conector de dados, selecione uma região para o repositório de dados.

  10. Insira um nome para o conector de dados.

  11. Clique em Criar. O Gemini Enterpriserise cria e exibe os repositórios de dados na página Repositórios de dados.

  12. Se você selecionou Ativar endereços IP estáticos em Opções avançadas, confira os endereços IP estáticos registrados para o conector e adicione-os à lista de permissões do Entra ID.

    1. Acesse a página Repositórios de dados e clique no nome do conector para conferir os detalhes na página Dados.
    2. No campo IPs estáticos, clique em Ver e confirmar IPs.
    3. Copie os endereços IP estáticos do conector.
    4. No centro de administração do Microsoft Entra, adicione os endereços IP estáticos a um local de confiança ou nomeado em uma política de acesso condicional. Para mais informações, consulte Acesso condicional: atribuição de rede.

Verificar o estado do conector

  1. Para verificar o status da ingestão, acesse a página Repositórios de dados e clique no nome do conector para conferir os detalhes na página Dados. O estado do conector muda de Criando para Em execução quando ele começa a sincronizar dados. Quando a transferência for concluída, o estado vai mudar para Ativo para indicar que a conexão com a origem de dados está configurada e aguardando a próxima sincronização programada.

    Dependendo do tamanho dos dados, a ingestão pode levar de vários minutos a várias horas.

  2. Quando o estado do conector mudar para Ativo, navegue até a guia Entidade.

  3. Clique na entidade userprofiles.

  4. Verifique o número de documentos processados e verifique se ele corresponde ao número de usuários no ID da Entra.

Os seguintes atributos padrão do usuário são ingeridos como parte de cada registro de usuário:

Nome do campo de esquema da Vertex AI Nome do atributo do Entra ID
name.displayName Nome de exibição
name.familyName Sobrenome
name.givenName Nome
name.username Nome do principal do usuário
email.value E-mail
employeeId ID do funcionário
personId
employeeType Tipo de funcionário
hireDate Data de contratação do funcionário
department Departamento
organizations.jobTitle Cargo
organizations.location Local do escritório
Phone Telefone comercial
managers.email, managers.personId Não é um atributo direto (cadeia de gestão do gerente imediato ao gerente de nível superior)
directManager.personId Não é um atributo direto (personId do gerente)
displayphoto.imagebinary.data Foto do perfil codificada em base64

Se o app Entra ID tiver as permissões necessárias para importar atributos personalizados, ele vai importar até 15 atributos de cartão de perfil por registro. Por padrão, os atributos personalizados não são pesquisáveis.

Configurar atributos pesquisáveis

Para tornar os atributos personalizados pesquisáveis, faça o seguinte:

  1. Na página userprofiles, navegue até a guia Esquema.
  2. Clique em Editar.

  3. Desmarque os atributos, como endereço, para que não sejam recuperáveis, pesquisáveis e indexáveis. Depois, clique em Salvar.

    O botão Editar permanece inativo por alguns minutos antes de ser reativado.

  4. Quando o botão Editar estiver no estado Ativo, clique em Editar.

  5. Marque as caixas recuperável, pesquisável e indexável para os atributos personalizados obrigatórios.

  6. Ative a pesquisa.

  7. Clique em Salvar.

Testar o mecanismo de pesquisa

Depois de configurar o mecanismo de pesquisa, teste os recursos dele para verificar se ele retorna resultados precisos com base no acesso do usuário.

  1. Ative o app da Web:

    1. Acesse as configurações de integração do app e ative a opção Ativar o app da Web.

  2. Testar o app da Web:

    1. Clique em Abrir ao lado do link do app da Web e faça login como um usuário.

    2. Verifique se os resultados da pesquisa estão restritos a itens acessíveis ao usuário.

Visualizar os resultados da pesquisa de pessoas

  1. No app de pesquisa, acesse Prévia e comece a pesquisar no console ao usar o IdP do Google.

    • Se preferir, acesse o link fornecido e faça login com seu IdP para começar a pesquisar.
    • Os resultados da pesquisa aparecem como cards de pessoas, mostrando detalhes do usuário, como nome, cargo, e-mail e foto do perfil.

  2. Clique em um card de pessoas para ver uma página de perfil detalhada, que inclui o seguinte:

    • Nome
    • Foto do perfil
    • Cargo
    • Departamento
    • Cadeia de gerenciamento
    • Subordinados diretos

  3. Se os atributos personalizados (propriedades do cartão de perfil) forem ingeridos e tornados indexáveis, pesquisáveis e recuperáveis:

    • A pesquisa por um valor de atributo personalizado retorna apenas perfis de pessoas que contêm esses atributos.
    • Os atributos personalizados aparecem nos resultados da pesquisa, mas só podem ser acessados pela API, não pela interface do usuário da Pesquisa do Vertex.

Configurar o pool de força de trabalho para IdP que não é do Google sem SSO

  1. Se os funcionários usarem um IdP que não é do Google, não tiverem SSO com o Google ou não forem clientes do Google Workspace, configure um pool de força de trabalho conforme descrito em [Configurar controles de acesso para fontes de dados personalizadas][data-source-access-control] para ativar a pesquisa de funcionários.

    Com o pool de colaboradores, é possível gerenciar e autenticar usuários de provedores de identidade externos, como o Azure ou o Okta, no console Google Cloud .

  2. Para configurar o pool de força de trabalho e ativar o app da Web para acesso fácil do usuário, faça o seguinte:

    1. Crie um pool de força de trabalho no nível da organização em Google Cloud seguindo o manual de configuração adequado:

      1. Configuração do OIDC do Azure
      2. Configuração do SAML do Azure
      3. Configuração do Okta e do OIDC
      4. Configuração do Okta e do SAML

    2. Configure o pool de força de trabalho em Gemini Enterprise > Configurações para a região em que você cria o app.

Limites de taxa recomendados

A tabela a seguir lista os limites de taxa recomendados com base no número de usuários. As solicitações que excedem os limites são limitadas.

Grupo de cotas Solicitações por segundo
S (menos de 50 usuários) 105
M (50 a 500 usuários) 150
L (mais de 500 usuários) 240

Limitações conhecidas

Estas são as limitações conhecidas do conector do Entra ID:

  • A sincronização incremental não é compatível.
  • As listas de controle de acesso (ACLs) não são compatíveis. Todos os usuários estão acessíveis em toda a organização.
  • Se você adicionar um projeto a um perímetro do VPC Service Controls depois de criar uma conexão, a execução da sincronização do conector vai falhar com o seguinte erro: Connector is blocked due to the project being added to the VPC-SC perimeter. Please re-create the data store.. Recrie o repositório de dados para que ele funcione no perímetro do VPC Service Controls.

Mensagens de erro

A tabela a seguir lista as mensagens de erro que podem aparecer ao usar o conector do Entra ID:

Mensagem de erro Descrição Solução de problemas
Authorization_RequestDenied: privilégios insuficientes para concluir a operação. A conta de usuário não tem os escopos necessários para ler dados. Forneça os escopos necessários à conta de usuário usada para criar a conexão.
Falha ao recuperar informações do token OAuth A credencial do cliente fornecida ao configurar o conector é inválida. Verifique o seguinte:
  • A chave secreta correspondente ao ID do cliente é fornecida. Ao configurar a conexão, especifique o valor da chave secreta do cliente, e não o ID dela.
  • O ID do locatário é válido.
  • A chave secreta do cliente não expirou. Se a chave secreta do cliente tiver expirado, edite a conexão e especifique a nova chave secreta do cliente.
O conector está bloqueado porque o projeto foi adicionado ao perímetro do VPC-SC. Recrie o repositório de dados. O conector foi criado antes de o projeto ser adicionado a um perímetro do VPC Service Controls. Recrie o repositório de dados para que ele funcione dentro do perímetro do VPC Service Controls.

Próximas etapas

  • Para anexar seu repositório de dados a um app, crie um app e selecione o repositório de dados seguindo as etapas em Criar um app.

  • Para ver como os resultados da pesquisa aparecem depois que o app e o repositório de dados são configurados, consulte Receber resultados da pesquisa.