Menyinkronkan berbagai sistem identitas

Kontrol akses di Google Cloud Search didasarkan pada akun Google pengguna. Saat mengindeks konten, semua ACL pada item harus menghasilkan ID pengguna Google atau grup (alamat email) yang valid.

Dalam banyak kasus, repositori tidak memiliki pengetahuan langsung tentang akun Google. Sebagai gantinya, pengguna dapat diwakili oleh akun lokal atau menggunakan login gabungan dengan penyedia identitas dan ID, selain alamat email pengguna, untuk mengidentifikasi setiap akun. ID ini disebut ID eksternal.

Dibuat menggunakan konsol Admin, Sumber identitas membantu menjembatani kesenjangan antara sistem identitas ini dengan:

• Menentukan bidang pengguna khusus untuk menyimpan ID eksternal. Kolom ini digunakan untuk menghasilkan ID eksternal ke akun Google.
• Menentukan namespace untuk grup keamanan yang dikelola oleh repositori atau penyedia identitas.

Gunakan sumber identitas saat:

• Repositori tidak memiliki pengetahuan tentang alamat email utama pengguna di Google Workspace atau Google Cloud Directory.
• Repositori menentukan grup untuk kontrol akses yang tidak sesuai dengan grup berbasis email di Google Workspace.

Sumber identitas meningkatkan efisiensi pengindeksan dengan memisahkan pengindeksan dari pemetaan identitas. Pemisahan ini memungkinkan Anda untuk menunda mencari pengguna saat membuat ACL dan mengindeks item.

Contoh penerapan

Gambar 1 menunjukkan contoh penerapan di mana repositori dan cloud lokal digunakan oleh suatu perusahaan. Setiap repositori menggunakan berbagai jenis ID eksternal untuk merujuk ke pengguna.

Gambar 1. Contoh deployment perusahaan dengan berbagai jenis identitas.

Repositori 1 mengidentifikasi pengguna menggunakan alamat email yang dinyatakan menggunakan SAML. Karena repositori 1 memiliki pengetahuan tentang alamat email utama pengguna di Google Workspace atau Direktori Cloud, sumber identitas tidak diperlukan.

Repositori 2 terintegrasi langsung dengan direktori lokal dan mengidentifikasi pengguna berdasarkan atribut sAMAccountName-nya. Karena repositori 2 menggunakan atribut sAMAccountName sebagai ID eksternal, sumber identitas diperlukan.

Membuat sumber identitas

Jika Anda memerlukan sumber identitas, lihat Memetakan identitas pengguna di Cloud Search.

Anda harus membuat sumber identitas sebelum membuat konektor konten karena Anda akan memerlukan ID sumber identitas tersebut untuk membuat ACL dan indeks data. Seperti yang disebutkan sebelumnya, membuat sumber identitas juga menciptakan properti pengguna khusus di Cloud Directory. Gunakan properti ini untuk mencatat ID eksternal untuk setiap pengguna di repositori Anda. Properti ini diberi nama menggunakan konvensi IDENTITY_SOURCE_ID_identity.

Tabel berikut menunjukkan dua sumber identitas, satu untuk menampung nama akun SAM (sAMAccountName) sebagai ID eksternal dan satu untuk menampung ID pengguna (uid) sebagai ID eksternal.

Sumber identitas	properti pengguna	ID Eksternal
id1	id1_identity	sAMAccountName
id2	id2_identity	uid

Buat sumber identitas untuk setiap kemungkinan ID eksternal yang digunakan untuk merujuk ke pengguna di perusahaan Anda.

Tabel berikut menunjukkan bagaimana pengguna dengan akun Google dan dua ID eksternal (id1_identity dan id2_identity) dan nilainya muncul di Cloud Directory:

pengguna	email	id1_identity	id2_identity
Ann	[e-mail]	example\ann	1001

Anda dapat mereferensikan pengguna yang sama menggunakan tiga ID yang berbeda, (Google email, sAMAccountName, dan uid) saat membentuk ACL untuk pengindeksan.

Menulis pengguna ACL

Gunakan metode getUserPrincpal() atau metode getGroupPrincipal() untuk membuat akun utama menggunakan ID eksternal yang disediakan.

Contoh berikut menunjukkan cara mengambil izin file. Izin ini termasuk nama setiap pengguna yang memiliki akses ke file.

FilePermissionSample.java

Lihat di GitHub

/**
 * Sample for mapping permissions from a source repository to Cloud Search
 * ACLs. In this example, POSIX file permissions are used a the source
 * permissions.
 *
 * @return Acl
 * @throws IOException if unable to read file permissions
 */
static Acl mapPosixFilePermissionToCloudSearchAcl(Path pathToFile) throws IOException {
  // Id of the identity source for external user/group IDs. Shown here,
  // but may be omitted in the SDK as it is automatically applied
  // based on the `api.identitySourceId` configuration parameter.
  String identitySourceId = "abcdef12345";

  // Retrieve the file system permissions for the item being indexed.
  PosixFileAttributeView attributeView = Files.getFileAttributeView(
      pathToFile,
      PosixFileAttributeView.class,
      LinkOption.NOFOLLOW_LINKS);

  if (attributeView == null) {
    // Can't read, return empty ACl
    return new Acl.Builder().build();
  }

  PosixFileAttributes attrs = attributeView.readAttributes();
  // ...
}

Cuplikan kode berikut menunjukkan cara membuat akun utama yang merupakan pemilik menggunakan ID eksternal (externalUserName) yang disimpan dalam atribut.

FilePermissionSample.java

Lihat di GitHub

// Owner, for search quality.
// Note that for principals the name is not the primary
// email address in Cloud Directory, but the local ID defined
// by the OS. Users and groups must be referred to by their
// external ID and mapped via an identity source.
List<Principal> owners = Collections.singletonList(
    Acl.getUserPrincipal(attrs.owner().getName(), identitySourceId)
);

Akhirnya, cuplikan kode berikut ini menunjukkan cara membuat akun utama yang merupakan pembaca file.

FilePermissionSample.java

Lihat di GitHub

// List of users to grant access to
List<Principal> readers = new ArrayList<>();

// Add owner, group, others to readers list if permissions
// exist. For this example, other is mapped to everyone
// in the organization.
Set<PosixFilePermission> permissions = attrs.permissions();
if (permissions.contains(PosixFilePermission.OWNER_READ)) {
  readers.add(Acl.getUserPrincipal(attrs.owner().getName(), identitySourceId));
}
if (permissions.contains(PosixFilePermission.GROUP_READ)) {
  String externalGroupName = attrs.group().getName();
  Principal group = Acl.getGroupPrincipal(externalGroupName, identitySourceId);
  readers.add(group);
}
if (permissions.contains(PosixFilePermission.OTHERS_READ)) {
  Principal everyone = Acl.getCustomerPrincipal();
  readers.add(everyone);
}

Setelah Anda memiliki daftar pembaca dan pemilik, Anda dapat membuat ACL:

FilePermissionSample.java

Lihat di GitHub

// Build the Cloud Search ACL. Note that inheritance of permissions
// from parents is omitted. See `setInheritFrom()` and `setInheritanceType()`
// methods on the builder if required by your implementation.
Acl acl = new Acl.Builder()
    .setReaders(readers)
    .setOwners(owners)
    .build();

REST API yang mendasarinya menggunakan pola identitysources/IDENTITY_SOURCE_ID/users/EXTERNAL_ID untuk ID saat membuat akun utama. Dengan merujuk kembali ke tabel sebelumnya, jika Anda membuat ACL dengan id1_identity milik Ann (SAMAccountName), ID tersebut akan menghasilkan:

identitysources/id1_identity/users/example/ann

Seluruh ID ini disebut ID pengguna intermediate karena memberikan jembatan antara ID eksternal dan ID Google yang disimpan dengan Cloud Directory.

Untuk informasi lebih lanjut tentang pemodelan ACL yang digunakan untuk repositori, lihat ACL.

Grup peta

Sumber identitas juga berfungsi sebagai namespace untuk grup yang digunakan dalam ACL. Anda dapat menggunakan fitur namespace ini untuk membuat dan memetakan grup yang digunakan hanya untuk tujuan keamanan atau bersifat lokal untuk repositori.

Gunakan Cloud Identity Groups API untuk membuat grup dan mengelola keanggotaan. Untuk mengaitkan grup dengan sumber identitas, gunakan nama resource sumber identitas sebagai namespace grup.

Cuplikan kode berikut ini menunjukkan cara membuat grup menggunakan Cloud Identity Groups API:

CreateGroupCommand.java

Lihat di GitHub

String namespace = "identitysources/" + idSource;
Group group = new Group()
    .setGroupKey(new EntityKey().setNamespace(namespace).setId(groupId))
    .setDescription("Demo group")
    .setDisplayName(groupName)
    .setLabels(Collections.singletonMap("system/groups/external", ""))
    .setParent(namespace);
try {
  CloudIdentity service = Utils.buildCloudIdentityService();
  Operation createOperation = service.groups().create(group).execute();

  if (createOperation.getDone()) {
    // Note: The response contains the data for a Group object, but as
    // individual fields. To convert to a Group instance, either populate
    // the fields individually or serialize & deserialize to/from JSON.
    //
    // Example:
    // String json = service.getJsonFactory().toString(response);
    // Group createdGroup =  service.getObjectParser()
    //     .parseAndClose(new StringReader(json), Group.class);
    System.out.printf("Group: %s\n",
        createOperation.getResponse().toString());
  } else {
    // Handle case where operation not yet complete, poll for
    // completion. API is currently synchronous and all operations return
    // as completed.
    // ...
  }
} catch (Exception e) {
  System.err.printf("Unable to create group: %s", e.getMessage());
  e.printStackTrace(System.err);
}

Membuat ACL grup

Untuk membuat ACL grup, gunakan metode getGroupPrincipal() untuk membuat akun utama grup menggunakan ID eksternal yang disediakan. Kemudian, buat ACL menggunakan class Acl.Builder sebagai berikut:

FilePermissionSample.java

Lihat di GitHub

if (permissions.contains(PosixFilePermission.GROUP_READ)) {
  String externalGroupName = attrs.group().getName();
  Principal group = Acl.getGroupPrincipal(externalGroupName, identitySourceId);
  readers.add(group);
}

Konektor identitas

Meskipun Anda dapat menggunakan ID non-Google eksternal untuk membuat ACL dan mengindeks item, pengguna tidak dapat melihat item dalam penelusuran sampai ID eksternal mereka menghasilkan ID Google di Cloud Directory. Ada tiga cara untuk memastikan bahwa Cloud Directory mengetahui ID Google dan ID eksternal untuk pengguna:

• Perbarui secara manual setiap profil pengguna individu melalui konsol Admin. Proses ini hanya disarankan untuk pengujian dan pembuatan prototipe menggunakan beberapa profil pengguna.
• Petakan ID eksternal ke ID Google menggunakan Directory API. Proses ini direkomendasikan bagi pengguna yang tidak dapat menggunakan Identity Connector SDK.
• Buat konektor identitas menggunakan Identity Connector SDK. SDK ini menyederhanakan penggunaan Directory API untuk memetakan ID.

Konektor identitas adalah program yang digunakan untuk memetakan ID eksternal dari identitas perusahaan (pengguna dan grup) ke identitas internal Google yang digunakan oleh Google Cloud Search. Jika Anda harus membuat sumber identitas, Anda harus membuat konektor identitas.

Google Cloud Directory Sync (GCDS) adalah contoh konektor identitas. Konektor identitas ini memetakan informasi pengguna dan grup dari Active Directory Microsoft ke Cloud Directory bersama dengan atribut pengguna yang dapat mewakili identitas mereka di sistem lain.

Sinkronkan identitas menggunakan REST API

Gunakan metode update untuk menyinkronkan identitas menggunakan REST API.

Memetakan ulang identitas

Setelah memetakan ulang identitas item ke identitas lain, Anda harus mengindeks ulang item agar identitas baru dapat ditahan. Misalnya,

• jika Anda mencoba menghapus pemetaan dari pengguna atau memetakan ulang pemetaan tersebut ke pengguna lain, pemetaan asalnya akan tetap dipertahankan hingga Anda mengindeks ulang.
• Jika Anda menghapus grup yang dipetakan yang ada di ACL item, lalu membuat grup baru dengan groupKey yang sama, grup baru tidak akan memberikan akses ke item tersebut hingga item tersebut diindeks ulang.