Connettere Microsoft Entra ID

Questa pagina descrive come connettere Microsoft Entra ID a Gemini Enterprise.

Dopo aver configurato l'origine dati e importato i dati la prima volta, il datastore sincronizza i dati da questa origine con una frequenza che selezioni durante la configurazione.

Nota :dopo aver connesso Microsoft Entra ID alla tua app, Google consiglia vivamente di attivare Knowledge Graph per migliorare significativamente la qualità della ricerca per i tuoi utenti. Per ulteriori informazioni, vedi Knowledge Graph: potenziamento della ricerca intelligente e sensibile al contesto.

Versioni supportate

Il connettore Entra ID supporta tutte le versioni ospitate di Entra ID tramite l'API Microsoft Graph v1.0.

Prima di iniziare

Prima di configurare il tuo datastore e importare i dati, devi ottenere un ID cliente e un secret per l'autenticazione e configurare le autorizzazioni minime richieste per l'applicazione. Questa sezione fornisce informazioni su come completare queste attività.

Configura il controllo dell'accesso per Entra ID

Per applicare controllo dell'accesso all'origine dati e proteggere i dati in Gemini Enterprise, assicurati di aver configurato il tuo provider di identità.

Ottieni un ID client e un client secret

1. Crea un'applicazione Entra ID:

   1. Accedi al centro di amministrazione di Microsoft Entra come amministratore e fai clic su Application (Applicazione).
   2. Nell'elenco a discesa Application (Applicazione), fai clic su App registrations (Registrazioni di app).
   3. Nella pagina App registrations (Registrazioni app), fai clic su New registration (Nuova registrazione).
   4. Fai clic su Add new registration (Aggiungi nuova registrazione) ed esegui le seguenti operazioni:
      • Inserisci un nome per l'applicazione.
      • Nella sezione Supported account types (Tipi di account supportati), seleziona Accounts in the organizational directory only (Solo account nella directory dell'organizzazione).
      • In Redirect URI (URI di reindirizzamento), aggiungi un URI di reindirizzamento web che rimandi a: https://login.microsoftonline.com/common/oauth2/nativeclient.
   5. Fai clic su Register (Registrati).

2. Salva le credenziali:

   Nella finestra dell'applicazione registrata, salva i seguenti valori per utilizzarli in un secondo momento:

   1. Utilizza l'ID applicazione (client) per impostare il parametro ID client.
   2. Utilizza l'ID directory (tenant) per impostare il parametro Tenant Azure.

3. Crea il client secret:

   1. Vai a Certificates & secrets (Certificati e secret).
   2. Fai clic su New client secret (Nuovo client secret) e specifica una durata.
   3. Salva il client secret e copia il valore del client secret per utilizzarlo in un secondo momento.

Salva il valore del client secret

Configura le autorizzazioni minime richieste per l'applicazione

1. Nella finestra dell'applicazione registrata, fai clic su API permissions (Autorizzazioni API).

2. In Configured permissions (Autorizzazioni configurate), seleziona Microsoft Graph e configura le seguenti autorizzazioni:

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

   Se vuoi importare profileCardAttributes, configura le seguenti autorizzazioni:

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

3. Concedi il consenso amministratore per tutte le autorizzazioni aggiunte. Per utilizzare le credenziali client nel flusso di autenticazione è necessario il consenso di un amministratore.

Autorizzazioni minime

La seguente tabella elenca le autorizzazioni minime necessarie per creare un connettore Entra ID:

Autorizzazione	Motivo dell'utilizzo	Descrizione
User.Read	Importazione dati	Leggi i dettagli dell'organizzazione durante la creazione della connessione.
User.Read.All (Application)	Importazione dati	Legge tutti gli utenti dell'organizzazione.
People.Read.All (Application)	Importazione dati	Leggi tutte le informazioni pertinenti sulle persone, ad esempio i contatti, per tutti gli utenti di un'organizzazione.
PeopleSettings.Read.All (Application)	Importazione dati	Leggi le configurazioni utente per tutti gli utenti dell'organizzazione, ad esempio profileCardSettings.
PeopleSettings.Read.All (Delegated)	Importazione dati	Leggi le configurazioni utente per tutti gli utenti dell'organizzazione, ad esempio profileCardSettings.

Crea un datastore Entra ID

Per utilizzare la console Google Cloud per sincronizzare i dati da Entra ID ad Gemini Enterprise, segui questi passaggi:

1. Nella console Google Cloud , vai alla pagina Gemini Enterprise.

   Gemini Enterprise

2. Nel menu di navigazione, fai clic su Datastore.

3. Fai clic su Crea datastore.

4. Nella pagina Select a data source (Seleziona un'origine dati), scorri o cerca Entra ID per connettere l'origine di terze parti.

5. In Authentication settings (Impostazioni di autenticazione), inserisci l'ID client e il client secret.

6. Nella sezione Advanced options (Opzioni avanzate):

   • Se necessario, fai clic su Enable Static IP Addresses (Abilita indirizzi IP statici). Dopo aver creato il connettore, devi inserire gli IP statici registrati nella lista consentita affinché le esecuzioni della sincronizzazione vadano a buon fine.
   • Per consentire al connettore di recuperare le proprietà di estensione, che vengono utilizzate per aggiungere una proprietà personalizzata a un oggetto directory, seleziona la casella di controllo Attiva proprietà di estensione.

   • Se vuoi filtrare le informazioni utente importate, fornisci un filtro SQL personalizzato. Il filtro deve essere una stringa SQL valida.

     Le chiavi nella stringa di filtro devono corrispondere ai seguenti campi:

     • Id
     • employeeType
     • onPremisesSyncEnabled
     • accountEnabled

     Di seguito sono riportati alcuni esempi di filtri SQL validi:

     id = 'abc' AND accountEnabled = true
     
     employeeType='E' AND onPremisesSyncEnabled= true
     

   • Nel campo Azure Tenant (Tenant Azure), inserisci l'ID tenant Azure che hai ottenuto quando hai creato un'applicazione Entra ID.

   • Per applicare un limite di frequenza alle query che il connettore invia all'istanza di Entra ID, specifica il numero massimo di query al secondo nel campo Max QPS. Il valore predefinito è 80 QPS.

   • Fai clic su Continua.

7. In Scegli le entità da sincronizzare:

   • Fai clic su User Profiles (Profili utente). Per filtrare i dati in base a Id per l'importazione dei dati, fai clic su Filter (Filtra), quindi procedi nel seguente modo:
     • Per specificare i dati da includere nell'indice di ricerca, seleziona Include in the index (Includi nell'indice) e poi specifica la stringa di filtro nel campo ID.
     • Per specificare i dati da escludere dall'indice di ricerca, seleziona Exclude from the index (Escludi dall'indice) e poi specifica la stringa di filtro nel campo ID.
   • Seleziona la frequenza di Full sync (Sincronizzazione completa).

8. Fai clic su Continua.

9. In Configure your data connector (Configura il connettore dati), seleziona una regione per il datastore.

10. Inserisci un nome per il tuo connettore dati.

11. Fai clic su Crea. Gemini Enterprise crea il datastore e mostra i datastore nella pagina Data Stores (Datastore).

12. Se hai selezionato Enable Static IP Addresses (Abilita indirizzi IP statici) in Advanced Options (Opzioni avanzate), visualizza gli indirizzi IP statici registrati per il connettore e aggiungili alla lista consentita per Entra ID.

    1. Vai alla pagina Datastore e fai clic sul nome del connettore per visualizzarne i dettagli nella pagina Data (Dati).
    2. Nel campo Static IPs (IP statici), fai clic su View and confirm IPs (Visualizza e conferma gli IP).
    3. Copia gli indirizzi IP statici per il connettore.
    4. Nel Centro amministrativo Microsoft Entra, aggiungi gli indirizzi IP statici a una località denominata o attendibile all'interno di una policy di accesso condizionale esistente. Per ulteriori informazioni, vedi Accesso condizionale: assegnazione di rete.

Controlla lo stato del connettore

1. Per controllare lo stato dell'importazione, vai alla pagina Datastore e fai clic sul nome del connettore dati per visualizzarne i dettagli nella pagina Data (Dati). Lo stato del connettore passa da Creating (Creazione) a Running (In esecuzione) quando inizia a sincronizzare i dati. Al termine dell'importazione, lo stato cambia in Attivo per indicare che la connessione all'origine dati è configurata e in attesa della successiva sincronizzazione pianificata.

   A seconda delle dimensioni dei dati, l'importazione può richiedere diversi minuti o diverse ore.

2. Quando lo stato del connettore diventa Active (Attivo), vai alla scheda Entity (Entità).

3. Fai clic sull'entità userprofiles.

4. Controlla il numero di documenti inseriti e verifica che corrisponda al numero di utenti in Entra ID.

I seguenti attributi utente standard vengono importati come parte di ogni record utente:

Nome del campo dello schema Vertex AI	Nome attributo Entra ID
name.displayName	Nome visualizzato
name.familyName	Cognome
name.givenName	Nome
name.username	Nome dell'entità utente
email.value	Email
employeeId	ID dipendente
personId
employeeType	Tipo di dipendente
hireDate	Data di assunzione del dipendente
department	Dipartimento
organizations.jobTitle	Qualifica
organizations.location	Posizione dell'ufficio
Phone	Telefono aziendale
managers.email, managers.personId	Non è un attributo diretto (catena di gestione dall'amministratore immediato all'amministratore di primo livello)
directManager.personId	Non è un attributo diretto (personId del manager)
displayphoto.imagebinary.data	Immagine del profilo con codifica Base64

Se l'app Entra ID dispone delle autorizzazioni necessarie per importare gli attributi personalizzati, importa fino a 15 attributi della scheda del profilo per record. Per impostazione predefinita, gli attributi personalizzati non sono disponibili per la ricerca.

Configurare gli attributi ricercabili

Per rendere ricercabili gli attributi personalizzati:

1. Nella pagina userprofiles, vai alla scheda Schema.
2. Fai clic su Modifica.

3. Deseleziona gli attributi, ad esempio indirizzo, in modo che non siano recuperabili, ricercabili e indicizzabili, poi fai clic su Salva.

   Il pulsante Modifica rimane inattivo per alcuni minuti prima di riattivarsi.

4. Quando il pulsante Modifica è in stato Attivo, fai clic su Modifica.

5. Seleziona le caselle recuperabili, ricercabili e indicizzabili per gli attributi personalizzati obbligatori.

6. Attiva la ricerca.

7. Fai clic su Salva.

Testare il motore di ricerca

Dopo aver configurato il motore di ricerca, testane le funzionalità per verificare se restituisce risultati accurati in base all'accesso degli utenti.

1. Abilita l'app web:

   1. Vai alle configurazioni di integrazione dell'app e attiva Abilita l'app web.

2. Testa l'app web:

   1. Fai clic su Apri accanto al link dell'app web e accedi come utente.

   2. Verifica che i risultati di ricerca siano limitati agli elementi accessibili all'utente.

Visualizzare l'anteprima dei risultati della ricerca di persone

1. Nell'app di ricerca, vai su Anteprima e inizia a eseguire ricerche all'interno della console quando utilizzi Google IdP.

   • In alternativa, vai al link fornito e accedi con il tuo IdP per iniziare la ricerca.
   • I risultati di ricerca vengono visualizzati come schede persona, che mostrano i dettagli dell'utente, ad esempio nome, qualifica, email e immagine del profilo.

2. Fai clic su una scheda di persona per visualizzare una pagina del profilo dettagliata, che include quanto segue:

   • Nome
   • Immagine del profilo
   • Posizione professionale
   • Reparto
   • Catena di gestione
   • Dipendenti subordinati

3. Se gli attributi personalizzati (proprietà della scheda del profilo) vengono importati e resi indicizzabili, ricercabili e recuperabili:

   • La ricerca in base al valore di un attributo personalizzato restituisce solo i profili delle persone che contengono questi attributi.
   • Gli attributi personalizzati vengono visualizzati nei risultati di ricerca, ma è possibile accedervi solo tramite l'API, non tramite l'interfaccia utente di Vertex AI Search.

Configurare il pool di forza lavoro per l'IdP non Google senza SSO

1. Se i tuoi dipendenti utilizzano un IdP non Google, non hanno SSO con Google o non sono clienti Google Workspace, configura un pool di forza lavoro come descritto in [Configura i controlli di accesso per le origini dati personalizzate][data-source-access-control] per attivare la ricerca dei dipendenti.

   Il pool di forza lavoro consente di gestire e autenticare gli utenti di provider di identità esterni, come Azure o Okta, all'interno della console Google Cloud .

2. Per configurare il pool di forza lavoro e abilitare l'app web per un accesso utente senza interruzioni, segui questi passaggi:

   1. Crea un pool di forza lavoro a livello di organizzazione in Google Cloud seguendo il manuale di configurazione appropriato:

      1. Configurazione di Azure OIDC
      2. Configurazione di Azure SAML
      3. Configurazione di Okta e OIDC
      4. Configurazione di Okta e SAML

   2. Configura il pool di forza lavoro in Gemini Enterprise > Impostazioni per la regione in cui crei l'app.

Limiti di frequenza consigliati

La tabella seguente elenca i limiti di frequenza consigliati in base al numero di utenti. Le richieste che superano i limiti vengono limitate.

Gruppo di quote	Richieste al secondo
S (meno di 50 utenti)	105
M (50-500 utenti)	150
L (più di 500 utenti)	240

Limitazioni note

Di seguito sono riportate le limitazioni note per il connettore Entra ID:

• La sincronizzazione incrementale non è supportata.
• Gli elenchi di controllo dell'accesso (ACL) non sono supportati. Tutti gli utenti sono accessibili in tutta l'organizzazione.
• Se aggiungi un progetto a un perimetro Controlli di servizio VPC dopo aver creato una connessione, l'esecuzione della sincronizzazione del connettore non va a buon fine e viene visualizzato il seguente errore: Connector is blocked due to the project being added to the VPC-SC perimeter. Please re-create the data store. Ricrea il datastore per consentirgli di funzionare all'interno del perimetro Controlli di servizio VPC.

Messaggi di errore

Nella tabella seguente sono elencati i messaggi di errore che potresti visualizzare quando utilizzi il connettore Entra ID:

Messaggio di errore	Descrizione	Risoluzione dei problemi
Authorization_RequestDenied Privilegi insufficienti per completare l'operazione.	L'account utente non contiene gli ambiti richiesti per leggere i dati.	Fornisci gli ambiti richiesti all'account utente utilizzato per creare la connessione.
Impossibile recuperare le informazioni sul token OAuth	La credenziale client fornita durante la configurazione del connettore non è valida.	Verifica quanto segue: Viene fornito il client secret corrispondente all'ID client. Quando configuri la connessione, specifica il valore di client secret e non il relativo ID secret. L'ID tenant è valido. Il client secret non è scaduto. Se il client secret è scaduto, modifica la connessione e specifica il nuovo client secret.
Il connettore è bloccato perché il progetto è stato aggiunto al perimetro VPC-SC. Ricrea il datastore.	Il connettore è stato creato prima che il progetto venisse aggiunto a un perimetro dei Controlli di servizio VPC.	Ricrea il datastore per consentirgli di funzionare all'interno del perimetro dei Controlli di servizio VPC.

Passaggi successivi

• Per collegare il datastore a un'app, crea un'app e seleziona il datastore seguendo i passaggi descritti in Crea un'app.

• Per visualizzare l'anteprima dell'aspetto dei risultati di ricerca dopo la configurazione dell'app e del datastore, consulta Ottenere i risultati di ricerca.