In genere, le aziende gestiscono le identità (utenti e gruppi di utenti) utilizzando un provider di identità (IdP). Tuttavia, le applicazioni personalizzate che un'azienda ha creato internamente possono consentire ai clienti di creare nuovi gruppi di utenti definiti localmente all'interno dell'applicazione. Questi gruppi di utenti specifici dell'applicazione o gli ID utente secondari sono chiamati identità esterne.
Perché configurare la mappatura delle identità?
Per assicurarti che Google possa applicare correttamente controllo dell'accesso#39;accesso, mappa le identità del tuo IDP con le identità esterne delle applicazioni personalizzate che prevedi di utilizzare con Gemini Enterprise.
Per applicare controllo dell'accesso ai risultati delle app, Google utilizza l'IDP come fonte di verità per determinare a quali dati hanno accesso i tuoi utenti. Le aziende spesso collegano il proprio IdP ad altre soluzioni SaaS in modo che un dipendente possa utilizzare un unico insieme di credenziali aziendali per accedere a tutte le risorse aziendali.
Se hai definito identità esterne tramite applicazioni che prevedi di connettere alla tua app, ad esempio applicazioni personalizzate, l'IdP non è l'unica fonte di riferimento per controllo dell'accesso dell'accesso.
Ad esempio, supponiamo che "JaneDoe" esista all'interno dell'organizzazione di esempio, con il dominio "example.com". L'ID nel provider di identità è definito come "JaneDoe@example.com". Lo stesso utente ha un ID separato all'interno di un'applicazione personalizzata come "JDoe". Il provider di identità potrebbe non essere a conoscenza di questo ID. Per questo motivo, Gemini Enterprise non riceve informazioni sugli ID applicazione personalizzati tramite l'IDP.
In Gemini Enterprise, le mappature delle identità vengono archiviate in un archivio di mappature delle identità in cui crei e importi le mappature. Se prevedi di utilizzare un connettore personalizzato, puoi associare l'archivio di mapping delle identità all'datastorei del connettore personalizzato e poi aggiornare i metadati ACL dell'archivio dati con informazioni sulle tue identità esterne.
Prima di iniziare
Prima di configurare la mappatura delle identità, connetti il tuo provider di identità al tuo progetto Google Cloud .
Preparare le voci della mappatura delle identità
Prepara le voci della mappatura delle identità per l'importazione. Le mappature delle identità devono essere formattate come nell'esempio seguente:
{
"identity_mapping_entries": [
{
"external_identity": "u1",
"user_id": "user1@example.com"
},
{
"external_identity": "u2",
"user_id": "user2@example.com"
},
{
"external_identity": "gABC",
"group_id": "groupABC@example.com"
}
]
}
Ad esempio, il seguente grafico rappresenta un esempio di appartenenza a un gruppo di utenti, dove Ext rappresenta i gruppi esterni. Questo grafico mostra un esempio di relazione
tra gruppi esterni e utenti e gruppi IdP.
Questo grafico dell'appartenenza al gruppo di utenti avrebbe la seguente mappatura:
{
"identity_mapping_entries": [
{
"external_identity": "Ext1",
"user_id": "IDPUser1@example.com"
},
{
"external_identity": "Ext2",
"user_id": "IDPUser1@example.com"
},
{
"external_identity": "Ext2",
"user_id": "IDPUser2@example.com"
},
{
"external_identity": "Ext3",
"user_id": "IDPUser2@example.com"
},
{
"external_identity": "Ext3",
"group_id": "IDPGroup1@example.com"
},
{
"external_identity": "Ext3",
"group_id": "IDPGroup2@example.com"
}
]
}
Le appartenenze di identità nidificate, in cui le identità esterne hanno identità secondarie, devono essere appiattite.
Google presuppone che il connettore invii un ID principale per un'identità esterna. Ad esempio, importa l'ID gruppo anziché il nome del gruppo, perché il nome potrebbe essere modificato durante il ciclo di vita del gruppo all'interno dell'applicazione personalizzata.
Configurare la mappatura delle identità
Utilizza le seguenti procedure per configurare la mappatura delle identità in Gemini Enterprise tra il tuo IdP e le tue identità esterne. Nei passaggi successivi, creerai un archivio di mappature delle identità e importerai le mappature delle identità che hai preparato. Se prevedi di utilizzare un connettore personalizzato, creerai anche un nuovo datastore associato all'archivio di mapping delle identità.
Crea un archivio di mappatura delle identità
Il primo passaggio consiste nel configurare un archivio di mappatura delle identità. Questa è la risorsa principale in cui sono archiviate tutte le mappature delle identità.
Quando crei l'archivio di mapping delle identità, recupera automaticamente la configurazione IDP dall'IDP che hai connesso al tuo progetto Gemini Enterprise.
Per creare un archivio di mapping delle identità, esegui il comando seguente utilizzando il metodo
identityMappingStores.create:curl -X POST \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores?identityMappingStoreId=IDENTITY_MAPPING_STORE_ID" \ -d '{ "name": "projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID" }'Sostituisci quanto segue:
PROJECT_ID: l'ID progetto.IDENTITY_MAPPING_STORE_ID: l'ID univoco dell'archivio di mappatura delle identità. Ad esempio,test-id-mapping-store.
Importare le mappature delle identità
Dopo aver creato l'archivio delle mappature delle identità, importa le voci delle mappature delle identità che hai preparato.
Per importare i mapping delle identità, esegui questo comando utilizzando il metodo
importIdentityMappings:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" -H "x-goog-user-project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID:importIdentityMappings" \ -d '{"inline_source" : IDENTITY_MAPPINGS_JSON}'Sostituisci quanto segue:
PROJECT_ID: l'ID progetto.IDENTITY_MAPPING_STORE_ID: l'ID univoco dell'archivio di mappatura delle identità.IDENTITY_MAPPINGS_JSON: le mappature delle identità preparate in formato JSON.
Successivamente, se prevedi di creare un connettore personalizzato e utilizzare identità esterne, vai a Associare archivi dati personalizzati all'archivio di mappatura delle identità. In caso contrario, vai ad Aggiornare i metadati ACL.
Associare datastore personalizzati all'archivio di mappatura delle identità
Questa procedura è necessaria solo se crei un connettore personalizzato. Se non stai creando un connettore personalizzato, salta questo passaggio.
Per i connettori personalizzati, l'archivio di mapping delle identità deve essere associato al datastore prima che un'identità esterna possa essere associata ai relativi documenti. L'impostazione di questo campo è consentita solo durante la creazione del datastore.
Per collegare un datastore allo store di mappatura delle identità, specifica
identity_mapping_storedurante la creazione del datastore utilizzando il metodoDatastores.create.curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores?dataStoreId=DATA_STORE_ID \ -d '{ ... "identity_mapping_store": "IDENTITY_MAPPING_STORE_NAME" }'Sostituisci quanto segue:
PROJECT_ID: l'ID progetto.DATA_STORE_ID: l'ID del datastore che vuoi creare. Questo ID può contenere solo lettere minuscole, cifre, trattini bassi e trattini.IDENTITY_MAPPING_STORE_NAME: il nome completo della risorsa del negozio di mapping delle identità. Ad esempio,projects/exampleproject/locations/global/identityMappingStores/test-id-mapping-store. Dopo aver creato un datastore, questo nome non può essere aggiornato.
Aggiungere metadati ACL
Includi i metadati ACL nell'oggetto AclInfo per i tuoi documenti.
Quando un utente invia una richiesta di ricerca e vengono recuperati i documenti i cui metadati ACL includono identità esterne, queste vengono valutate.
Se l'identità dell'utente (groupID o userID) è mappata a un'identità esterna
(externalEntityId) associata a un documento, l'utente ottiene
l'accesso a quel documento.
Ad esempio, supponiamo di aver creato un connettore personalizzato per Jira. Un determinato problema di Jira
è accessibile a determinati utenti IDP, a determinati gruppi IDP e a un
ruolo di amministratore. Per consentire l'accesso a questo problema da parte di queste persone nei risultati di ricerca, puoi creare un archivio di mappatura delle identità e mappare utenti e gruppi IdP a identità esterne specifiche di Jira. Collega l'archivio di mappatura delle identità
al tuo datastore Jira. Poi, crea documenti nei tuoi datastore Jira con
aclInfo configurato con gli utenti IdP, i gruppi IdP e le identità esterne che
devono avere accesso a questi documenti.
Per aggiornare i metadati ACL con informazioni sulle tue identità esterne, utilizza il seguente formato per specificare le identità esterne e gli ID utente e gruppo associati.
{
"aclInfo": {
"readers": [
{
"principals": [
{
"groupId": "group_1"
},
{
"userId": "user_1"
},
{
"externalEntityId": "external_id1"
}
]
}
]
}
}
Per ulteriori informazioni sull'aggiornamento dei metadati ACL, consulta Configurare un'origine dati con il controllo dell'accesso.
Gestire le mappature delle identità
Puoi elencare i mapping delle identità in un archivio delle identità oppure puoi eliminare un archivio delle identità definendoli tramite un'origine inline o utilizzando una condizione di filtro.
Le attività di gestione disponibili per la mappatura delle identità sono:
- Elencare le mappature delle identità
- Eliminare utilizzando l'origine in linea
- Eliminare utilizzando una condizione di filtro
Elenca le mappature delle identità
Per elencare i mapping delle identità, esegui il seguente comando utilizzando il metodo
listIdentityMappings:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "x-goog-user-project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID:listIdentityMappings?page_size=PAGE_SIZE&page_token=PAGE_TOKEN"Sostituisci quanto segue:
PROJECT_ID: l'ID progetto.PAGE_SIZE: numero massimo di negozi di mapping delle identità da restituire. Se non specificato, il valore predefinito è 100. Il valore massimo consentito è 1000. I valori superiori a 1000 verranno forzati a 1000.PAGE_TOKEN: un token di pagina ricevuto da una precedente chiamataListIdentityMappingStores. Forniscilo per recuperare la pagina successiva.
Eliminazione definitiva utilizzando la fonte in linea
Puoi eliminare le voci specificate da un archivio di mappatura delle identità fornendo un file JSON delle identità da eliminare.
Per eliminare i mapping delle identità utilizzando l'origine inline, esegui il seguente comando utilizzando il metodo
purgeIdentityMappings:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "x-goog-user-project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID:purgeIdentityMappings" \ -d '{"inline_source" : IDENTITY_MAPPINGS_JSON}'Sostituisci quanto segue:
PROJECT_ID: l'ID progetto.IDENTITY_MAPPING_STORE_ID: l'ID univoco dell'archivio di mappatura delle identità.IDENTITY_MAPPING_STORE_NAME: il nome dell'archivio di mapping delle identità.IDENTITY_MAPPINGS_JSON: le mappature delle identità da eliminare.
Eliminare definitivamente utilizzando una condizione di filtro
Puoi eliminare le voci specificate da un archivio di mapping delle identità filtrando le voci in base all'ora di aggiornamento, all'identità esterna o a tutte le voci.
Per eliminare i mapping delle identità utilizzando una condizione di filtro, esegui il seguente comando utilizzando il metodo
purgeIdentityMappings:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "x-goog-user-project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID:purgeIdentityMappings" \ -d '{"identity_mapping_store":"IDENTITY_MAPPING_STORE_NAME", "filter": "FILTER_CONDITION"}'Sostituisci quanto segue:
PROJECT_ID: l'ID progetto.IDENTITY_MAPPING_STORE_ID: l'ID univoco dell'archivio di mappatura delle identità.IDENTITY_MAPPING_STORE_NAME: il nome dell'archivio di mapping delle identità.FILTER_CONDITION: uno dei seguenti tipi di filtro:- Ora di aggiornamento. Ad esempio,
update_time > "2012-04-23T18:25:43.511Z" AND update_time < "2012-04-23T18:30:43.511Z"> - Identità esterna. Ad esempio,
external_id = "id1" - Tutte le mappature delle identità. Ad esempio,
*
Gestire gli archivi di mappatura delle identità
Puoi ottenere, eliminare, elencare ed eliminare definitivamente gli archivi di mappatura delle identità.
Ottieni l'archivio della mappatura delle identità
Per ottenere un archivio di mapping delle identità, esegui il comando seguente utilizzando il metodo
identityMappingStores.get:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID"Sostituisci quanto segue:
PROJECT_ID: l'ID progetto.IDENTITY_MAPPING_STORE_ID: l'ID univoco dell'archivio di mappatura delle identità.IDENTITY_MAPPING_STORE_NAME: il nome dell'archivio di mapping delle identità.
Elenca gli archivi di mappatura delle identità
Per elencare gli archivi di mapping delle identità, esegui questo comando utilizzando il metodo
identityMappingStores.list:curl -X GET \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "x-goog-user-project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores?page_size=PAGE_SIZE&page_token=PAGE_TOKEN"Sostituisci quanto segue:
PROJECT_ID: l'ID progetto.PAGE_SIZE: numero massimo di negozi di mapping delle identità da restituire. Se non specificato, il valore predefinito è 100. Il valore massimo consentito è 1000. I valori superiori a 1000 verranno forzati a 1000.PAGE_TOKEN: un token di pagina ricevuto da una precedente chiamataListIdentityMappingStores. Forniscilo per recuperare la pagina successiva.
Elimina gli archivi di mappatura delle identità
Per eliminare un archivio di mappatura delle identità, questo non deve essere associato a un datastore e non devono essere presenti mappature delle identità nell'archivio di mappatura delle identità.
Per eliminare un archivio di mapping delle identità, esegui il seguente comando utilizzando il metodo
identityMappingStores.delete:curl -X DELETE \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "X-Goog-User-Project: PROJECT_ID" \ "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID"Sostituisci quanto segue:
PROJECT_ID: l'ID progetto.IDENTITY_MAPPING_STORE_ID: l'ID univoco dell'archivio di mappatura delle identità.IDENTITY_MAPPING_STORE_NAME: il nome dell'archivio di mapping delle identità.