Perusahaan biasanya mengelola identitas (pengguna dan grup pengguna) menggunakan penyedia identitas (IDP). Namun, aplikasi kustom yang dibangun sendiri oleh perusahaan dapat memungkinkan pelanggan membuat grup pengguna baru yang ditentukan secara lokal dalam aplikasi tersebut. Grup pengguna khusus aplikasi atau ID pengguna sekunder ini disebut sebagai identitas eksternal.
Mengapa perlu menyiapkan pemetaan identitas?
Untuk memastikan bahwa Google dapat menerapkan kontrol akses dengan benar, petakan identitas IdP Anda ke identitas eksternal dari aplikasi kustom yang akan Anda gunakan dengan Gemini Enterprise.
Untuk menerapkan kontrol akses ke hasil aplikasi, Google menggunakan IDP sebagai sumber kebenaran untuk menentukan data mana yang dapat diakses pengguna Anda. Perusahaan sering kali menghubungkan IDP mereka ke solusi SaaS lain sehingga karyawan dapat menggunakan satu set kredensial perusahaan untuk login dan mengakses semua resource perusahaan.
Jika Anda memiliki identitas eksternal yang ditentukan melalui aplikasi yang akan Anda hubungkan ke aplikasi Anda seperti aplikasi kustom, maka IDP Anda bukan satu-satunya sumber tepercaya untuk kontrol akses.
Misalnya, "JaneDoe" ada dalam Organisasi Contoh, dengan domain "example.com". ID di IDP ditentukan sebagai "JaneDoe@example.com". Pengguna yang sama memiliki ID terpisah dalam aplikasi kustom sebagai "JDoe". IDP mungkin tidak mengetahui ID ini. Oleh karena itu, Gemini Enterprise tidak menerima informasi tentang ID aplikasi kustom melalui IDP.
Di Gemini Enterprise, pemetaan identitas disimpan dalam penyimpanan pemetaan identitas yang Anda buat dan impor pemetaannya. Jika Anda berencana menggunakan konektor kustom, Anda dapat mengikat penyimpanan pemetaan identitas ke penyimpanan data konektor kustom, lalu memperbarui metadata ACL penyimpanan data dengan informasi tentang identitas eksternal Anda.
Sebelum memulai
Sebelum menyiapkan pemetaan identitas, hubungkan penyedia identitas Anda ke project Google Cloud Anda.
Menyiapkan entri pemetaan identitas
Siapkan entri pemetaan identitas untuk diimpor. Pemetaan identitas harus diformat seperti dalam contoh berikut:
{
"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"
}
]
}
Misalnya, diagram berikut menunjukkan contoh keanggotaan grup pengguna, dengan Ext mewakili grup eksternal. Diagram ini menunjukkan contoh hubungan antara grup eksternal dengan pengguna dan grup IDP.
Grafik keanggotaan grup pengguna ini akan memiliki pemetaan berikut:
{
"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"
}
]
}
Keanggotaan identitas bertingkat, dengan identitas eksternal memiliki identitas turunan, harus diratakan.
Google mengasumsikan bahwa konektor mengirimkan ID utama untuk identitas eksternal. Misalnya, impor ID grup, bukan nama grup, karena nama dapat diubah selama masa aktif grup dalam aplikasi kustom.
Menyiapkan pemetaan identitas
Gunakan prosedur berikut untuk menyiapkan pemetaan identitas di Gemini Enterprise antara IDP Anda dan identitas eksternal Anda. Pada langkah-langkah berikut, Anda akan membuat penyimpanan pemetaan identitas, mengimpor pemetaan identitas yang telah Anda siapkan. Jika berencana menggunakan konektor kustom, Anda juga akan membuat penyimpanan data baru yang terikat ke penyimpanan pemetaan identitas.
Membuat toko pemetaan identitas
Langkah pertama adalah menyiapkan penyimpanan pemetaan identitas. Ini adalah resource induk tempat semua pemetaan identitas disimpan.
Saat Anda membuat penyimpanan pemetaan identitas, penyimpanan tersebut akan otomatis mengambil konfigurasi IDP dari IDP yang Anda hubungkan ke project Gemini Enterprise Anda.
Untuk membuat penyimpanan pemetaan identitas, jalankan perintah berikut menggunakan metode
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" }'Ganti kode berikut:
PROJECT_ID: ID project Anda.IDENTITY_MAPPING_STORE_ID: ID unik untuk penyimpanan pemetaan identitas. Contoh,test-id-mapping-store.
Mengimpor pemetaan identitas
Setelah membuat penyimpanan pemetaan identitas, impor entri pemetaan identitas yang Anda siapkan.
Untuk mengimpor pemetaan identitas, jalankan perintah berikut menggunakan metode
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}'Ganti kode berikut:
PROJECT_ID: ID project Anda.IDENTITY_MAPPING_STORE_ID: ID unik dari penyimpanan pemetaan identitas.IDENTITY_MAPPINGS_JSON: pemetaan identitas yang disiapkan dalam format JSON.
Selanjutnya, jika Anda berencana membuat konektor kustom dan menggunakan identitas eksternal, buka Mengikat penyimpanan data kustom ke penyimpanan pemetaan identitas. Jika tidak, lewati ke Memperbarui metadata ACL.
Mengikat penyimpanan data kustom ke penyimpanan pemetaan identitas
Prosedur ini hanya diperlukan jika Anda membuat konektor kustom. Jika Anda tidak membuat konektor kustom, lewati langkah ini.
Untuk konektor kustom, penyimpanan pemetaan identitas harus terikat ke penyimpanan data sebelum identitas eksternal dapat dikaitkan dengan dokumennya. Penetapan kolom ini hanya diizinkan selama pembuatan penyimpanan data.
Untuk mengikat penyimpanan data ke penyimpanan pemetaan identitas, tentukan
identity_mapping_storeselama pembuatan penyimpanan data menggunakan metodeDatastores.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" }'Ganti kode berikut:
PROJECT_ID: ID project Anda.DATA_STORE_ID: ID penyimpanan data yang ingin Anda buat. ID ini hanya boleh berisi huruf kecil, angka, garis bawah, dan tanda hubung.IDENTITY_MAPPING_STORE_NAME: nama resource lengkap dari penyimpanan pemetaan identitas. Contoh,projects/exampleproject/locations/global/identityMappingStores/test-id-mapping-store. Setelah penyimpanan data dibuat, nama ini tidak dapat diperbarui.
Menambahkan metadata ACL
Sertakan metadata ACL dalam objek AclInfo untuk dokumen Anda.
Saat pengguna mengirim permintaan penelusuran dan dokumen yang metadata ACL-nya mencakup identitas eksternal diambil, identitas eksternal tersebut akan dievaluasi.
Jika identitas pengguna (groupID atau userID) dipetakan ke identitas eksternal
(externalEntityId) yang terkait dengan dokumen, maka pengguna akan mendapatkan
akses ke dokumen tersebut.
Misalnya, Anda telah membuat konektor kustom untuk Jira. Masalah Jira tertentu dapat diakses oleh pengguna IdP tertentu, grup IdP tertentu, dan peran administrator. Agar masalah tersebut dapat diakses oleh orang-orang tersebut di hasil penelusuran, Anda dapat membuat penyimpanan pemetaan identitas dan memetakan pengguna dan grup IdP ke identitas eksternal khusus Jira. Ikat penyimpanan pemetaan identitas ke penyimpanan data Jira Anda. Kemudian, buat dokumen di penyimpanan data Jira Anda dengan
aclInfo yang dikonfigurasi dengan pengguna IdP, grup IdP, dan identitas eksternal yang
seharusnya memiliki akses ke dokumen tersebut.
Untuk memperbarui metadata ACL Anda dengan informasi tentang identitas eksternal Anda, gunakan format berikut untuk menentukan identitas eksternal dan ID pengguna serta grup terkait.
{
"aclInfo": {
"readers": [
{
"principals": [
{
"groupId": "group_1"
},
{
"userId": "user_1"
},
{
"externalEntityId": "external_id1"
}
]
}
]
}
}
Untuk mengetahui informasi selengkapnya tentang cara memperbarui metadata ACL, lihat Mengonfigurasi sumber data dengan kontrol akses.
Mengelola pemetaan identitas
Anda dapat mencantumkan pemetaan identitas di penyimpanan identitas, atau menghapus penyimpanan identitas dengan menentukannya melalui sumber inline atau menggunakan kondisi filter.
Tugas pengelolaan yang tersedia untuk pemetaan identitas adalah:
- Mencantumkan pemetaan identitas
- Menghapus menggunakan sumber inline
- Menghapus menggunakan kondisi filter
Mencantumkan pemetaan identitas
Untuk mencantumkan pemetaan identitas, jalankan perintah berikut menggunakan metode
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"Ganti kode berikut:
PROJECT_ID: ID project Anda.PAGE_SIZE: jumlah maksimum penyimpanan pemetaan identitas yang akan ditampilkan. Jika tidak ditentukan, nilai defaultnya adalah 100. Nilai maksimum yang diizinkan adalah 1000. Nilai yang lebih tinggi dari 1.000 akan dikonversi menjadi 1.000.PAGE_TOKEN: token halaman, yang diterima dari panggilanListIdentityMappingStoressebelumnya. Berikan ini untuk mengambil halaman berikutnya.
Menghapus menggunakan sumber inline
Anda dapat menghapus entri tertentu dari penyimpanan pemetaan identitas dengan memberikan file JSON yang berisi identitas yang akan dihapus.
Untuk menghapus pemetaan identitas menggunakan sumber inline, jalankan perintah berikut menggunakan metode
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}'Ganti kode berikut:
PROJECT_ID: ID project Anda.IDENTITY_MAPPING_STORE_ID: ID unik dari penyimpanan pemetaan identitas.IDENTITY_MAPPING_STORE_NAME: nama penyimpanan pemetaan identitas.IDENTITY_MAPPINGS_JSON: pemetaan identitas yang akan dihapus.
Menghapus menggunakan kondisi filter
Anda dapat menghapus entri tertentu dari penyimpanan pemetaan identitas dengan memfilter entri menurut waktu pembaruan, identitas eksternal, atau semua entri.
Untuk menghapus pemetaan identitas menggunakan kondisi filter, jalankan perintah berikut menggunakan metode
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"}'Ganti kode berikut:
PROJECT_ID: ID project Anda.IDENTITY_MAPPING_STORE_ID: ID unik dari penyimpanan pemetaan identitas.IDENTITY_MAPPING_STORE_NAME: nama penyimpanan pemetaan identitas.FILTER_CONDITION: salah satu jenis filter berikut:- Waktu update. Contoh,
update_time > "2012-04-23T18:25:43.511Z" AND update_time < "2012-04-23T18:30:43.511Z"> - Identitas Eksternal. Contoh,
external_id = "id1" - Semua pemetaan identitas. Contoh,
*
Mengelola penyimpanan pemetaan identitas
Anda dapat mengambil, menghapus, mencantumkan, dan menghapus permanen penyimpanan pemetaan identitas.
Mendapatkan penyimpanan pemetaan identitas
Untuk mendapatkan penyimpanan pemetaan identitas, jalankan perintah berikut menggunakan metode
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"Ganti kode berikut:
PROJECT_ID: ID project Anda.IDENTITY_MAPPING_STORE_ID: ID unik dari penyimpanan pemetaan identitas.IDENTITY_MAPPING_STORE_NAME: nama penyimpanan pemetaan identitas.
Mencantumkan toko pemetaan identitas
Untuk mencantumkan penyimpanan pemetaan identitas, jalankan perintah berikut menggunakan metode
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"Ganti kode berikut:
PROJECT_ID: ID project Anda.PAGE_SIZE: jumlah maksimum penyimpanan pemetaan identitas yang akan ditampilkan. Jika tidak ditentukan, nilai defaultnya adalah 100. Nilai maksimum yang diizinkan adalah 1000. Nilai yang lebih tinggi dari 1.000 akan dikonversi menjadi 1.000.PAGE_TOKEN: token halaman, yang diterima dari panggilanListIdentityMappingStoressebelumnya. Berikan ini untuk mengambil halaman berikutnya.
Menghapus penyimpanan pemetaan identitas
Untuk menghapus penyimpanan pemetaan identitas, penyimpanan tersebut tidak boleh terikat ke penyimpanan data, dan tidak boleh ada pemetaan identitas dalam penyimpanan pemetaan identitas.
Untuk menghapus penyimpanan pemetaan identitas, jalankan perintah berikut menggunakan metode
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"Ganti kode berikut:
PROJECT_ID: ID project Anda.IDENTITY_MAPPING_STORE_ID: ID unik dari penyimpanan pemetaan identitas.IDENTITY_MAPPING_STORE_NAME: nama penyimpanan pemetaan identitas.