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 fiable pour 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 fiable pour le contrôle des accès.
Supposons, par exemple, que "JaneDoe" existe dans l'organisation Example, avec le domaine "example.com". L'ID dans l'IdP est défini comme "JaneDoe@example.com". Le même utilisateur dispose d'un ID distinct dans une application personnalisée : "JDoe". L'IdP n'est peut-être pas au courant de cet ID. Par conséquent, Gemini Enterprise ne reçoit pas d'informations sur les ID d'application personnalisée via l'IdP.
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 magasin de mappages d'identité au data store du connecteur personnalisé, puis mettre à jour les métadonnées de la liste de contrôle d'accès (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 Google Cloud projet.
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 au format 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 les groupes externes. Ce graphique montre un exemple de relation entre les groupes externes et les utilisateurs et groupes IdP.
Ce graphique d'appartenance à un groupe d'utilisateurs 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 de groupe au lieu du nom du groupe, car le nom peut être modifié au cours de la durée de vie du groupe dans l'application personnalisée.
Configurer le mappage d'identité
Procédez comme suit pour configurer le mappage d'identité dans Gemini Enterprise entre votre IdP et vos identités externes. Au cours des é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 mappages d'identité.
Créer un magasin de mappages d'identité
La première étape consiste à configurer un magasin de mappages 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 mappages d'identité, il récupère automatiquement la configuration de l'IdP à partir de l'IdP que vous avez connecté à votre projet Gemini Enterprise.
Pour créer un magasin de mappages d'identité, exécutez la commande suivante à l'aide de la
identityMappingStores.createméthode :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: l'ID du projet.IDENTITY_MAPPING_STORE_ID: l'ID unique du magasin de mappages d'identité. Par exemple,test-id-mapping-store.
Importer des mappages d'identité
Après avoir créé le magasin de mappages 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 à partir de Cloud Storage (option 2).
Lorsque vous importez des données 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 sur le nombre de mappages d'identité : vous pouvez importer jusqu'à
500,000mappages d'identité externes dans une opération d'importation. - Contraintes sur le 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
importIdentityMappingsméthode :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: l'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: ID unique du magasin de mappages d'identité.IDENTITY_MAPPINGS_JSON: les 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, consultez Lier des datastores personnalisés au magasin de mappages d'identité. Sinon, passez à Mettre à jour les métadonnées de la 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
importIdentityMappingsméthode :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: l'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: ID unique du magasin de mappages d'identité.BUCKET_NAME: nom de votre bucket Cloud Storage.FILE_PATH: chemin d'accès à votre fichier de mappages d'identité dans Cloud Storage.ERROR_DIR: répertoire de Cloud Storage dans lequel les journaux d'erreurs seront stockés.
Si vous prévoyez de créer un connecteur personnalisé et d'utiliser des identités externes, consultez Lier des datastores personnalisés au magasin de mappages d'identité. Sinon, passez à Mettre à jour les métadonnées de la LCA.
Lier des datastores personnalisés au magasin de mappages 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 mappages 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 magasin de mappages d'identité, spécifiez
identity_mapping_storelors de la création du data store à l'aide de laDatastores.createméthode.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: 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 mappages d'identité. 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 des 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.
Supposons, par exemple, que vous ayez créé un connecteur personnalisé pour Jira. Un problème Jira donné est accessible à certains utilisateurs IdP, à certains groupes IdP et à un rôle d'administrateur. Pour que ce problème soit accessible à ces personnes dans les résultats de recherche, vous pouvez créer un magasin de mappages d'identité et mapper les utilisateurs et groupes IdP à des identités externes spécifiques à Jira. Liez le magasin de mappages 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 et 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 le contrôle des accès.
Gérer les mappages d'identité
Vous pouvez répertorier 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 à l'aide d'une condition de filtre.
Les tâches de gestion disponibles pour le mappage d'identité sont les suivantes :
- Répertorier les mappages d'identité
- Purger à l'aide d'une source intégrée
- Purger à l'aide d'une condition de filtre
Répertorier les mappages d'identité
Pour répertorier les mappages d'identité, exécutez la commande suivante à l'aide de la
listIdentityMappingsméthode :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: l'ID du projet.PAGE_SIZE: nombre maximal de magasins de mappages d'identité à renvoyer. Si aucune valeur n'est spécifiée, la valeur par défaut est 100. La valeur maximale autorisée est 1 000. Les valeurs supérieures à 1 000 seront forcées à 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 purger des entrées spécifiées d'un magasin de mappages d'identité en fournissant un fichier JSON des identités à purger.
Pour purger les mappages d'identité à l'aide d'une source intégrée, exécutez la commande suivante à l'aide de la
purgeIdentityMappingsméthode :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: l'ID du projet.IDENTITY_MAPPING_STORE_ID: ID unique du magasin de mappages d'identité.IDENTITY_MAPPING_STORE_NAME: nom du magasin de mappages d'identité.IDENTITY_MAPPINGS_JSON: mappages d'identité à purger.
Purger à l'aide d'une condition de filtre
Vous pouvez purger des entrées spécifiées d'un magasin de mappages d'identité en filtrant les entrées par heure de mise à jour, identité externe ou toutes les entrées.
Pour purger les mappages d'identité à l'aide d'une condition de filtre, exécutez la commande suivante à l'aide de la
purgeIdentityMappingsméthode :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: l'ID du projet.IDENTITY_MAPPING_STORE_ID: ID unique du magasin de mappages d'identité.IDENTITY_MAPPING_STORE_NAME: nom du magasin de mappages d'identité.FILTER_CONDITION: l'un des types de filtres suivants :- Heure de mise à jour. 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 mappages d'identité
Vous pouvez obtenir, supprimer, répertorier et purger des magasins de mappages d'identité.
Obtenir un magasin de mappages d'identité
Pour obtenir un magasin de mappages d'identité, exécutez la commande suivante à l'aide de la
identityMappingStores.getméthode :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: l'ID du projet.IDENTITY_MAPPING_STORE_ID: ID unique du magasin de mappages d'identité.IDENTITY_MAPPING_STORE_NAME: nom du magasin de mappages d'identité.
Répertorier les magasins de mappages d'identité
Pour répertorier les magasins de mappages d'identité, exécutez la commande suivante à l'aide de la
identityMappingStores.listméthode :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: l'ID du projet.PAGE_SIZE: nombre maximal de magasins de mappages d'identité à renvoyer. Si aucune valeur n'est spécifiée, la valeur par défaut est 100. La valeur maximale autorisée est 1 000. Les valeurs supérieures à 1 000 seront forcées à 1 000.PAGE_TOKEN: jeton de page, reçu d'un appelListIdentityMappingStoresprécédent. Fournissez-le pour récupérer la page suivante.
Supprimer des magasins de mappages d'identité
Pour supprimer un magasin de mappages d'identité, 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é.
Pour supprimer un magasin de mappages d'identité, exécutez la commande suivante à l'aide de la
identityMappingStores.deleteméthode :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: l'ID du projet.IDENTITY_MAPPING_STORE_ID: ID unique du magasin de mappages d'identité.IDENTITY_MAPPING_STORE_NAME: nom du magasin de mappages d'identité.