Les entreprises gèrent généralement les identités (utilisateurs et groupes d'utilisateurs) à l'aide d'un fournisseur d'identité (IdP). Toutefois, les applications personnalisées qu'une entreprise a créées en interne peuvent permettre aux clients de créer des groupes d'utilisateurs définis localement dans cette application. Ces groupes d'utilisateurs spécifiques à l'application ou ces ID utilisateur secondaires sont appelés identités externes.
Pourquoi configurer le mappage d'identité ?
Pour vous assurer que Google peut appliquer correctement le contrôle des accès, mappez vos identités IDP à toutes les identités externes des applications personnalisées que vous prévoyez d'utiliser avec Gemini Enterprise.
Pour appliquer le contrôle des accès aux résultats de l'application, Google utilise l'IDP comme source de vérité afin de déterminer les données auxquelles vos utilisateurs ont accès. Les entreprises connectent souvent leur IdP à d'autres solutions SaaS afin qu'un employé puisse utiliser un seul ensemble d'identifiants d'entreprise pour se connecter et accéder à toutes les ressources de l'entreprise.
Si vous avez défini des identités externes via des applications que vous prévoyez de connecter à votre application, telles que des applications personnalisées, votre IdP n'est pas la seule source de vérité pour le contrôle des accès.
Par exemple, supposons que "JaneDoe" existe dans l'organisation "Example Organization", avec le domaine "example.com". L'ID dans l'IdP est défini comme "JaneDoe@example.com". Le même utilisateur possède un ID distinct dans une application personnalisée, "JDoe". Il est possible que le fournisseur d'identité ne connaisse pas cet ID. Par conséquent, Gemini Enterprise ne reçoit pas d'informations sur les ID d'application personnalisés via le fournisseur d'identité.
Dans Gemini Enterprise, les mappages d'identité sont stockés dans un magasin de mappages d'identité que vous créez et dans lequel vous importez les mappages. Si vous prévoyez d'utiliser un connecteur personnalisé, vous pouvez lier le store de mappage d'identité au data store du connecteur personnalisé, puis mettre à jour les métadonnées de LCA de votre datastore avec des informations sur vos identités externes.
Avant de commencer
Avant de configurer le mappage d'identité, connectez votre fournisseur d'identité à votre projet Google Cloud .
Préparer les entrées de mappage d'identité
Préparez les entrées de mappage d'identité pour l'importation. Les mappages d'identité doivent être formatés comme dans l'exemple suivant :
{
"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"
}
]
}
Par exemple, le graphique suivant représente un exemple d'appartenance à un groupe d'utilisateurs, où Ext représente des groupes externes. Ce diagramme montre un exemple de relation entre des groupes externes et des utilisateurs et groupes d'IDP.
Ce graphique d'appartenance utilisateur-groupe aurait le mappage suivant :
{
"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"
}
]
}
Les appartenances d'identité imbriquées, où les identités externes ont des identités enfants, doivent être aplaties.
Google suppose que le connecteur envoie un ID principal pour une identité externe. Par exemple, importez l'ID du groupe au lieu de son nom, car celui-ci peut être modifié au cours de la durée de vie du groupe dans l'application personnalisée.
Configurer le mappage d'identité
Suivez les procédures ci-dessous pour configurer le mappage d'identité dans Gemini Enterprise entre votre IdP et vos identités externes. Dans les étapes suivantes, vous allez créer un magasin de mappages d'identité et importer les mappages d'identité que vous avez préparés. Si vous prévoyez d'utiliser un connecteur personnalisé, vous allez également créer un datastore lié au magasin de mappage d'identité.
Créer un magasin de mappage d'identité
La première étape consiste à configurer un magasin de mappage d'identité. Il s'agit de la ressource parente dans laquelle tous les mappages d'identité sont stockés.
Lorsque vous créez le magasin de mappage d'identité, il récupère automatiquement la configuration du fournisseur d'identité que vous avez connecté à votre projet Gemini Enterprise.
Pour créer un magasin de mappage d'identités, exécutez la commande suivante à l'aide de la méthode
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" }'Remplacez les éléments suivants :
PROJECT_ID: par l'ID du projet.IDENTITY_MAPPING_STORE_ID: identifiant unique du magasin de mappage d'identités. Par exemple :test-id-mapping-store.
Importer des mappages d'identité
Après avoir créé le magasin de mappage d'identité, importez les entrées de mappage d'identité que vous avez préparées. Vous pouvez importer des mappages d'identité à l'aide d'une source intégrée (option 1) ou depuis Cloud Storage (option 2).
Lors de l'importation depuis Cloud Storage, les formats et contraintes suivants s'appliquent :
- Formats autorisés : les fichiers d'entrée doivent être au format NDJSON (
.ndjson) ou JSON Lines (.jsonl), chaque ligne représentant une seule entrée de mappage d'identité. - Contraintes de taille de fichier : chaque fichier ne doit pas dépasser 2 Go.
- Contraintes liées au nombre de mappages d'identités : vous pouvez importer jusqu'à
500,000mappages d'identités externes lors d'une opération d'importation. - Contraintes de nombre de fichiers : vous pouvez spécifier jusqu'à
2,000fichiers dans la listeinputUris. Si vous utilisez des caractères génériques, la limite s'applique au nombre total de fichiers après l'expansion des caractères génériques.
Option 1 : Importer à l'aide d'une source intégrée
Pour importer vos mappages d'identité à l'aide d'une source intégrée, exécutez la commande suivante à l'aide de la méthode
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://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/identityMappingStores/IDENTITY_MAPPING_STORE_ID:importIdentityMappings" \ -d '{"inline_source" : IDENTITY_MAPPINGS_JSON}'Remplacez les éléments suivants :
PROJECT_ID: l'ID du projet.ENDPOINT_LOCATION: emplacement multirégional de votre requête API. Spécifiez l'une des valeurs suivantes :uspour l'emplacement multirégional USeupour l'emplacement multirégional EUglobalpour l'emplacement mondial
LOCATION: emplacement multirégional de votre data store :global,usoueuIDENTITY_MAPPING_STORE_ID: identifiant unique du magasin de mappage d'identités.IDENTITY_MAPPINGS_JSON: mappages d'identité préparés au format JSON.
Si vous prévoyez de créer un connecteur personnalisé et d'utiliser des identités externes, accédez à Associer des datastores personnalisés au store de mappage d'identités. Sinon, passez à la section Mettre à jour les métadonnées de LCA.
Option 2 : Importer depuis Cloud Storage
Pour importer vos mappages d'identité depuis Cloud Storage, exécutez la commande suivante à l'aide de la méthode
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://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/identityMappingStores/IDENTITY_MAPPING_STORE_ID:importIdentityMappings" \ -d '{ "gcsSource": { "inputUris": ["gs://BUCKET_NAME/FILE_PATH"] }, "errorConfig": { "gcsPrefix": "gs://BUCKET_NAME/ERROR_DIR" }, "reconciliationMode": "FULL" }'Remplacez les éléments suivants :
PROJECT_ID: l'ID du projet.ENDPOINT_LOCATION: emplacement multirégional de votre requête API. Spécifiez l'une des valeurs suivantes :uspour l'emplacement multirégional USeupour l'emplacement multirégional EUglobalpour l'emplacement mondial
LOCATION: emplacement multirégional de votre data store :global,usoueuIDENTITY_MAPPING_STORE_ID: identifiant unique du magasin de mappage d'identités.BUCKET_NAME: nom du bucket Cloud Storage.FILE_PATH: chemin d'accès à votre fichier de mappages d'identité dans Cloud Storage.ERROR_DIR: répertoire dans Cloud Storage où les journaux d'erreurs seront stockés.
Si vous prévoyez de créer un connecteur personnalisé et d'utiliser des identités externes, accédez à Associer des datastores personnalisés au store de mappage d'identités. Sinon, passez à la section Mettre à jour les métadonnées de LCA.
Associer des datastores personnalisés au magasin de mappage d'identité
Cette procédure n'est nécessaire que si vous créez un connecteur personnalisé. Si vous ne créez pas de connecteur personnalisé, ignorez cette étape.
Pour les connecteurs personnalisés, le magasin de mappage d'identité doit être lié au datastore avant qu'une identité externe puisse être associée à ses documents. La définition de ce champ n'est autorisée que lors de la création du data store.
Pour lier un data store au store de mappage d'identité, spécifiez
identity_mapping_storelors de la création du data store à l'aide de la méthodeDatastores.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" }'Remplacez les éléments suivants :
PROJECT_ID: par l'ID du projet.DATA_STORE_ID: ID du data store que vous souhaitez créer. Cet ID ne peut contenir que des lettres minuscules, des chiffres, des traits de soulignement et des traits d'union.IDENTITY_MAPPING_STORE_NAME: nom complet de la ressource du magasin de mappage d'identités. Par exemple :projects/exampleproject/locations/global/identityMappingStores/test-id-mapping-store. Une fois le data store créé, ce nom ne peut plus être modifié.
Ajouter des métadonnées de LCA
Incluez les métadonnées de LCA dans l'objet AclInfo de vos documents.
Lorsqu'un utilisateur envoie une requête de recherche et que des documents dont les métadonnées de LCA incluent des identités externes sont récupérés, ces identités externes sont évaluées.
Si l'identité de l'utilisateur (groupID ou userID) est mappée à une identité externe (externalEntityId) associée à un document, l'utilisateur a accès à ce document.
Par exemple, supposons que vous ayez créé un connecteur personnalisé pour Jira. Une demande Jira donnée est accessible par certains utilisateurs du fournisseur d'identité, certains groupes du fournisseur d'identité et un rôle d'administrateur. Pour que ces personnes puissent accéder à ce problème dans les résultats de recherche, vous pouvez créer un store de mappage d'identités et mapper les utilisateurs et les groupes du fournisseur d'identité à des identités externes spécifiques à Jira. Lie l'espace de stockage de mappage d'identité à votre data store Jira. Ensuite, créez des documents dans vos datastores Jira avec aclInfo configuré avec les utilisateurs IDP, les groupes IDP et les identités externes qui doivent avoir accès à ces documents.
Pour mettre à jour vos métadonnées de LCA avec des informations sur vos identités externes, utilisez le format suivant pour spécifier les identités externes ainsi que les ID d'utilisateur et de groupe associés.
{
"aclInfo": {
"readers": [
{
"principals": [
{
"groupId": "group_1"
},
{
"userId": "user_1"
},
{
"externalEntityId": "external_id1"
}
]
}
]
}
}
Pour en savoir plus sur la mise à jour des métadonnées de LCA, consultez Configurer une source de données avec contrôle des accès.
Gérer les mappages d'identité
Vous pouvez lister les mappages d'identité dans un magasin d'identités ou purger un magasin d'identités en les définissant via une source intégrée ou en utilisant une condition de filtre.
Les tâches de gestion disponibles pour le mappage d'identité sont les suivantes :
- Lister les mappages d'identité
- Effectuer une suppression définitive à l'aide d'une source intégrée
- Effectuer une purge à l'aide d'une condition de filtre
Lister les mappages d'identité
Pour lister les mappages d'identité, exécutez la commande suivante à l'aide de la méthode
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"Remplacez les éléments suivants :
PROJECT_ID: par l'ID du projet.PAGE_SIZE: nombre maximal de magasins de mappage d'identité à renvoyer. Si aucune valeur n'est spécifiée, la valeur par défaut est 100. La valeur maximale autorisée est de 1 000. Les valeurs supérieures à 1 000 seront réduites à 1 000.PAGE_TOKEN: jeton de page reçu d'un appelListIdentityMappingStoresprécédent. Fournissez-le pour récupérer la page suivante.
Purger à l'aide d'une source intégrée
Vous pouvez supprimer des entrées spécifiées d'un store de mappage d'identités en fournissant un fichier JSON des identités à supprimer.
Pour supprimer les mappages d'identité à l'aide d'une source intégrée, exécutez la commande suivante à l'aide de la méthode
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}'Remplacez les éléments suivants :
PROJECT_ID: par l'ID du projet.IDENTITY_MAPPING_STORE_ID: identifiant unique du magasin de mappage d'identités.IDENTITY_MAPPING_STORE_NAME: nom du magasin de mappage d'identités.IDENTITY_MAPPINGS_JSON: mappages d'identité à supprimer.
Supprimer définitivement à l'aide d'une condition de filtre
Vous pouvez supprimer des entrées spécifiées d'un magasin de mappage d'identité en filtrant les entrées par heure de mise à jour, par identité externe ou par toutes les entrées.
Pour supprimer des mappages d'identité à l'aide d'une condition de filtre, exécutez la commande suivante à l'aide de la méthode
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"}'Remplacez les éléments suivants :
PROJECT_ID: par l'ID du projet.IDENTITY_MAPPING_STORE_ID: identifiant unique du magasin de mappage d'identités.IDENTITY_MAPPING_STORE_NAME: nom du magasin de mappage d'identités.FILTER_CONDITION: l'un des types de filtres suivants :- Modifier l'heure. Par exemple :
update_time > "2012-04-23T18:25:43.511Z" AND update_time < "2012-04-23T18:30:43.511Z"> - Identité externe. Par exemple :
external_id = "id1" - Tous les mappages d'identité. Par exemple :
*
Gérer les magasins de mappage d'identité
Vous pouvez obtenir, supprimer, lister et purger des magasins de mappage d'identité.
Obtenir le magasin de mappage d'identité
Pour obtenir un magasin de mappage d'identités, exécutez la commande suivante à l'aide de la méthode
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"Remplacez les éléments suivants :
PROJECT_ID: par l'ID du projet.IDENTITY_MAPPING_STORE_ID: identifiant unique du magasin de mappage d'identités.IDENTITY_MAPPING_STORE_NAME: nom du magasin de mappage d'identités.
Lister les magasins de mappage d'identité
Pour lister les magasins de mappage d'identité, exécutez la commande suivante à l'aide de la méthode
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"Remplacez les éléments suivants :
PROJECT_ID: par l'ID du projet.PAGE_SIZE: nombre maximal de magasins de mappage d'identité à renvoyer. Si aucune valeur n'est spécifiée, la valeur par défaut est 100. La valeur maximale autorisée est de 1 000. Les valeurs supérieures à 1 000 seront réduites à 1 000.PAGE_TOKEN: jeton de page reçu d'un appelListIdentityMappingStoresprécédent. Fournissez-le pour récupérer la page suivante.
Supprimer les magasins de mappage d'identité
Pour supprimer un magasin de mappages d'identités, il ne doit pas être lié à un data store, et aucun mappage d'identité ne doit être présent dans le magasin de mappages d'identités.
Pour supprimer un magasin de mappage d'identités, exécutez la commande suivante à l'aide de la méthode
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"Remplacez les éléments suivants :
PROJECT_ID: par l'ID du projet.IDENTITY_MAPPING_STORE_ID: identifiant unique du magasin de mappage d'identités.IDENTITY_MAPPING_STORE_NAME: nom du magasin de mappage d'identités.