Membuat konektor identitas

Secara default, Google Cloud Search hanya mengenali identitas Google yang disimpan di Google Cloud Directory (pengguna dan grup). Konektor identitas digunakan untuk menyinkronkan identitas perusahaan Anda dengan identitas Google yang digunakan oleh Google Cloud Search.

Catatan: Selain membuat konektor identitas, Anda harus membuat sumber identitas dan menggunakan ID sumber saat membuat ACL sumber data. Untuk mengetahui informasi lebih lanjut tentang sumber identitas dan cara menggunakan ID sumber identitas dengan ACL, lihat Menyinkronkan sistem identitas yang berbeda.

Google menyediakan opsi berikut untuk mengembangkan konektor identitas:

• Identity Connector SDK. Opsi ini untuk developer yang membuat program dalam bahasa pemrograman Java. Identity Connector SDK adalah wrapper di sekitar REST API yang dapat Anda gunakan untuk membuat konektor dengan cepat. Untuk membuat konektor identitas menggunakan SDK, lihat bagian Membuat konektor identitas menggunakan Identity Connector SDK.

• REST API dan library API tingkat rendah. Opsi ini untuk developer yang mungkin tidak membuat program di Java atau yang memiliki codebase yang lebih mengakomodasi REST API atau library. Untuk membuat konektor identitas menggunakan REST API, lihat Directory API: Akun Pengguna untuk mengetahui informasi tentang cara memetakan pengguna dan Dokumentasi Cloud Identity untuk mengetahui informasi tentang grup pemetaan.

Membuat konektor identitas menggunakan Identity Connector SDK

Konektor identitas standar melakukan tugas-tugas berikut:

1. Mengonfigurasi konektor.
2. Mengambil semua pengguna dari sistem identitas perusahaan Anda dan mengirimkannya ke Google untuk disinkronkan dengan identitas Google.
3. Mengambil semua grup dari sistem identitas perusahaan Anda dan mengirimkannya ke Google untuk disinkronkan dengan identitas Google.

Menyiapkan dependensi

Anda harus menyertakan dependensi tertentu dalam file build untuk menggunakan SDK. Klik tab di bawah untuk melihat dependensi lingkungan build Anda:

Maven

<dependency>
<groupId>com.google.enterprise.cloudsearch</groupId>
<artifactId>google-cloudsearch-identity-connector-sdk</artifactId>
<version>v1-0.0.3</version>
</dependency>

Gradle

 compile group: 'com.google.enterprise.cloudsearch',
         name: 'google-cloudsearch-identity-connector-sdk',
         version: 'v1-0.0.3'

Buat konfigurasi konektor Anda

Setiap konektor memiliki file konfigurasi yang berisi parameter yang digunakan oleh konektor, seperti ID untuk repositori Anda. Parameter ditentukan sebagai pasangan nilai kunci, seperti api.sourceId=1234567890abcdef.

Google Cloud Search SDK berisi beberapa parameter konfigurasi yang disediakan Google yang digunakan oleh semua konektor. Anda harus mendeklarasikan parameter yang disediakan Google berikut ini dalam file konfigurasi Anda:

• Untuk konektor konten, Anda harus mendeklarasikan api.sourceId dan api.serviceAccountPrivateKeyFile karena parameter ini mengidentifikasi lokasi repositori dan kunci pribadi yang diperlukan untuk mengakses repositori.

Catatan: Jika file kunci pribadi Anda bukan kunci JSON, Anda juga harus mengganti api.serviceAccountId.

• Untuk konektor identitas, Anda harus mendeklarasikan api.identitySourceId karena parameter ini mengidentifikasi lokasi sumber identitas eksternal Anda. Jika menyinkronkan pengguna, Anda juga harus mendeklarasikan api.customerId sebagai ID unik untuk akun Google Workspace perusahaan Anda.

Kecuali jika Anda ingin mengganti nilai default parameter lain yang disediakan Google, Anda tidak perlu mendeklarasikannya dalam file konfigurasi Anda. Untuk mengetahui informasi tambahan tentang parameter konfigurasi yang disediakan Google, seperti cara membuat ID dan kunci tertentu, lihat Parameter konfigurasi yang disediakan Google.

Anda juga dapat menentukan parameter spesifik repositori Anda sendiri untuk digunakan dalam file konfigurasi Anda.

Catatan: Tidak ada persyaratan penamaan yang ketat untuk file properti konektor, tetapi sebaiknya simpan file menggunakan ekstensi .properties atau .config.

Teruskan file konfigurasi ke konektor

Setel properti sistem config untuk meneruskan file konfigurasi ke konektor Anda. Anda dapat menetapkan properti menggunakan argumen -D saat memulai konektor. Misalnya, perintah berikut memulai konektor dengan file konfigurasi MyConfig.properties:

java -classpath myconnector.jar;... -Dconfig=MyConfig.properties MyConnector

Jika argumen ini tidak ada, SDK akan mencoba mengakses file konfigurasi default bernama connector-config.properties.

Membuat konektor identitas sinkronisasi lengkap menggunakan class template

Identity Connector SDK berisi class template FullSyncIdentityConnector yang dapat Anda gunakan untuk menyinkronkan semua pengguna dan grup dari repositori identitas dengan identitas Google. Bagian ini menjelaskan cara menggunakan template FullSyncIdentityConnector untuk melakukan sinkronisasi penuh pengguna dan grup dari repositori identitas non-Google.

Bagian dokumen ini merujuk ke cuplikan kode dari contoh IdentityConnecorSample.java. Sampel ini membaca identitas pengguna dan grup dari dua file CSV dan menyinkronkannya dengan identitas Google.

Menerapkan titik entri konektor

Titik entri ke konektor adalah metode main(). Tugas utama metode ini adalah membuat instance class Application dan memanggil metode start() untuk menjalankan konektor.

Sebelum memanggil application.start(), gunakan class IdentityApplication.Builder untuk membuat instance template FullSyncIdentityConnector. FullSyncIdentityConnector menerima objek Repository yang metodenya akan Anda terapkan. Cuplikan kode berikut menunjukkan cara menerapkan metode main():

IdentityConnectorSample.java

Lihat di GitHub

/**
 * This sample connector uses the Cloud Search SDK template class for a full
 * sync connector. In the full sync case, the repository is responsible
 * for providing a snapshot of the complete identity mappings and
 * group rosters. This is then reconciled against the current set
 * of mappings and groups in Cloud Directory.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new CsvRepository();
  IdentityConnector connector = new FullSyncIdentityConnector(repository);
  IdentityApplication application = new IdentityApplication.Builder(connector, args).build();
  application.start();
}

Di balik layar, SDK memanggil metode initConfig() setelah metode main() konektor Anda memanggil Application.build. Metode initConfig() menjalankan tugas-tugas berikut:

1. Memanggil metode Configuation.isInitialized() untuk memastikan bahwa Configuration belum diinisialisasi.
2. Menginisialisasi objek Configuration dengan key-value pair yang disediakan Google. Setiap key-value pair disimpan dalam objek ConfigValue dalam objek Configuration.

Mengimplementasikan antarmuka Repository

Satu-satunya tujuan objek Repository adalah untuk melakukan sinkronisasi identitas repositori ke identitas Google. Saat menggunakan template, Anda hanya perlu mengganti metode tertentu dalam antarmuka Repository untuk membuat konektor identitas. Untuk FullTraversalConnector, Anda kemungkinan akan mengganti metode berikut:

• Metode init(). Untuk melakukan penyiapan dan inisialisasi repositori identitas, ganti dengan metode `init().

• Metode listUsers(). Untuk menyinkronkan semua pengguna di repositori identitas dengan pengguna Google, ganti metode listUsers().

• Metode listGroups(). Untuk menyinkronkan semua grup di repositori identitas dengan grup Google, ganti metode listGroups().

• (opsional) Metode close(). Jika Anda perlu melakukan pembersihan repositori, ganti metode close(). Metode ini dipanggil sekali selama penutupan konektor.

Mendapatkan parameter konfigurasi khusus

Sebagai bagian dari penanganan konfigurasi konektor, Anda harus mendapatkan parameter kustom dari objek Configuration. Tugas ini biasanya dilakukan dalam metode init() di class Repository.

Class Configuration memiliki beberapa metode untuk mendapatkan berbagai jenis data dari konfigurasi. Setiap metode menampilkan objek ConfigValue. Selanjutnya, Anda akan menggunakan metode get() objek ConfigValue untuk mengambil nilai sebenarnya. Cuplikan berikut menunjukkan cara mengambil nilai userMappingCsvPath dan groupMappingCsvPath dari objek Configuration:

IdentityConnectorSample.java

Lihat di GitHub

/**
 * Initializes the repository once the SDK is initialized.
 *
 * @param context Injected context, contains convenienve methods
 *                for building users & groups
 * @throws IOException if unable to initialize.
 */
@Override
public void init(RepositoryContext context) throws IOException {
  log.info("Initializing repository");
  this.context = context;
  userMappingCsvPath = Configuration.getString(
      "sample.usersFile", "users.csv").get().trim();
  groupMappingCsvPath = Configuration.getString(
      "sample.groupsFile", "groups.csv").get().trim();
}

Untuk mendapatkan dan mengurai parameter yang berisi beberapa nilai, gunakan salah satu jenis parser class Configuration untuk mengurai data menjadi potongan terpisah. Cuplikan berikut, dari konektor tutorial, menggunakan metode getMultiValue untuk mendapatkan daftar nama repositori GitHub:

GithubRepository.java

Lihat di GitHub

ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

Mendapatkan pemetaan untuk semua pengguna

Ganti listUsers() untuk mengambil pemetaan bagi semua pengguna dari repositori identitas Anda. Metode listUsers() menerima checkpoint yang mewakili identitas terakhir yang akan disinkronkan. Checkpoint tersebut dapat digunakan untuk melanjutkan sinkronisasi jika prosesnya terganggu. Untuk setiap pengguna di repositori Anda, Anda akan melakukan langkah-langkah berikut dalam metode listUsers():

1. Dapatkan pemetaan yang terdiri dari identitas Google dan identitas eksternal terkait.
2. Gabungkan pasangan ke dalam iterator yang ditampilkan oleh metode listUsers().

Mendapatkan pemetaan pengguna

Cuplikan kode berikut menunjukkan cara mengambil pemetaan identitas yang disimpan dalam file CSV:

IdentityConnectorSample.java

Lihat di GitHub

/**
 * Retrieves all user identity mappings for the identity source. For the
 * full sync connector, the repository must provide a complete snapshot
 * of the mappings. This is reconciled against the current mappings
 * in Cloud Directory. All identity mappings returned here are
 * set in Cloud Directory. Any previously mapped users that are omitted
 * are unmapped.
 *
 * The connector does not create new users. All users are assumed to
 * exist in Cloud Directory.
 *
 * @param checkpoint Saved state if paging over large result sets. Not used
 *                   for this sample.
 * @return Iterator of user identity mappings
 * @throws IOException if unable to read user identity mappings
 */
@Override
public CheckpointCloseableIterable<IdentityUser> listUsers(byte[] checkpoint)
    throws IOException {
  List<IdentityUser> users = new ArrayList<>();
  try (Reader in = new FileReader(userMappingCsvPath)) {
    // Read user mappings from CSV file
    CSVParser parser = CSVFormat.RFC4180
        .withIgnoreSurroundingSpaces()
        .withIgnoreEmptyLines()
        .withCommentMarker('#')
        .parse(in);
    for (CSVRecord record : parser.getRecords()) {
      // Each record is in form: "primary_email", "external_id"
      String primaryEmailAddress = record.get(0);
      String externalId = record.get(1);
      if (primaryEmailAddress.isEmpty() || externalId.isEmpty()) {
        // Skip any malformed mappings
        continue;
      }
      log.info(() -> String.format("Adding user %s/%s",
          primaryEmailAddress, externalId));

      // Add the identity mapping
      IdentityUser user = context.buildIdentityUser(
          primaryEmailAddress, externalId);
      users.add(user);
    }
  }
  // ...
}

Menggabungkan pemetaan pengguna menjadi iterator

Metode listUsers() menampilkan Iterator, khususnya CheckpointCloseableIterable, dari objek IdentityUser. Anda dapat menggunakan class CheckpointClosableIterableImpl.Builder untuk membuat dan menampilkan iterator. Cuplikan kode berikut menunjukkan cara menggabungkan setiap pemetaan ke dalam daftar build asal iterator tersebut:

IdentityConnectorSample.java

Lihat di GitHub

CheckpointCloseableIterable<IdentityUser> iterator =
  new CheckpointCloseableIterableImpl.Builder<IdentityUser>(users)
      .setHasMore(false)
      .setCheckpoint((byte[])null)
      .build();

Mendapatkan grup

Ganti listGroups() untuk mengambil semua grup dan anggotanya dari repositori identitas Anda. Metode listGroups() menerima checkpoint yang mewakili identitas terakhir yang akan disinkronkan. Checkpoint tersebut dapat digunakan untuk melanjutkan sinkronisasi jika prosesnya terganggu. Untuk setiap pengguna di repositori Anda, Anda akan melakukan langkah-langkah ini dalam metode listGroups():

1. Mendapatkan grup dan anggotanya.
2. Gabungkan setiap grup dan anggotanya ke dalam iterator yang ditampilkan oleh metode listGroups().

Mendapatkan identitas grup

Cuplikan kode berikut menunjukkan cara mengambil grup dan anggota yang disimpan dalam file CSV:

IdentityConnectorSample.java

Lihat di GitHub

/**
 * Retrieves all group rosters for the identity source. For the
 * full sync connector, the repository must provide a complete snapshot
 * of the rosters. This is reconciled against the current rosters
 * in Cloud Directory. All groups and members  returned here are
 * set in Cloud Directory. Any previously created groups or members
 * that are omitted are removed.
 *
 * @param checkpoint Saved state if paging over large result sets. Not used
 *                   for this sample.
 * @return Iterator of group rosters
 * @throws IOException if unable to read groups
 */    @Override
public CheckpointCloseableIterable<IdentityGroup> listGroups(byte[] checkpoint)
    throws IOException {
  List<IdentityGroup> groups = new ArrayList<>();
  try (Reader in = new FileReader(groupMappingCsvPath)) {
    // Read group rosters from CSV
    CSVParser parser = CSVFormat.RFC4180
        .withIgnoreSurroundingSpaces()
        .withIgnoreEmptyLines()
        .withCommentMarker('#')
        .parse(in);
    for (CSVRecord record : parser.getRecords()) {
      // Each record is in form: "group_id", "member"[, ..., "memberN"]
      String groupName = record.get(0);
      log.info(() -> String.format("Adding group %s", groupName));
      // Parse the remaining columns as group memberships
      Supplier<Set<Membership>> members = new MembershipsSupplier(record);
      IdentityGroup group = context.buildIdentityGroup(groupName, members);
      groups.add(group);
    }
  }
  // ...

}

Menggabungkan grup dan anggota ke dalam iterator

Metode listGroups() menampilkan Iterator, khususnya CheckpointCloseableIterable, dari objek IdentityGroup. Anda dapat menggunakan class CheckpointClosableIterableImpl.Builder untuk membuat dan menampilkan iterator. Cuplikan kode berikut menunjukkan cara menggabungkan setiap grup dan anggotanya ke dalam sebuah daftar dan membuat iterator dari daftar tersebut:

IdentityConnectorSample.java

Lihat di GitHub

CheckpointCloseableIterable<IdentityGroup> iterator =
   new CheckpointCloseableIterableImpl.Builder<IdentityGroup>(groups)
      .setHasMore(false)
      .setCheckpoint((byte[])null)
      .build();

Langkah Berikutnya

Berikut beberapa langkah yang dapat Anda ambil:

• (opsional) Terapkan metode close() untuk melepaskan resource sebelum penghentian.
• (opsional) Buat konektor konten menggunakan Content Connector SDK.