Identitätsconnector erstellen

Standardmäßig erkennt Google Cloud Search nur in Google Cloud Directory gespeicherte Google-Identitäten (Nutzer und Gruppen). Mit Identitätsconnectors können Sie die Identitäten Ihres Unternehmens mit den von Google Cloud Search verwendeten Google-Identitäten synchronisieren.

Google bietet folgende Optionen zum Entwickeln von Identitätsconnectors:

  • Das Identity Connector SDK. Diese Option ist für Entwickler gedacht, die in der Programmiersprache Java programmieren. Das Identity Connector SDK ist ein Wrapper um die REST API, mit dem Sie schnell Connectors erstellen können. Weitere Informationen zum Erstellen eines Identitätsconnectors mit dem SDK

  • Eine untergeordnete REST API und API-Bibliotheken. Diese Optionen sind für Entwickler gedacht, die möglicherweise nicht in Java programmieren oder deren Codebasis besser für eine REST API oder eine Bibliothek geeignet ist. Wenn Sie einen Identitätsconnector mit der REST API erstellen möchten, finden Sie unter Directory API: Nutzerkonten die Informationen zur Zuordnung von Nutzern und in der Cloud Identity-Dokumentation Informationen zum Zuordnen von Gruppen.

Mit dem Identity Connector SDK einen Identitätsconnector erstellen

Ein typischer Identitätsconnector führt die folgenden Aufgaben aus:

  1. Konfigurieren Sie den Connector.
  2. Rufen Sie alle Nutzer aus dem Identitätssystem Ihres Unternehmens ab und senden Sie sie zur Synchronisierung mit Google-Identitäten an Google.
  3. Rufen Sie alle Gruppen aus dem Identitätssystem Ihres Unternehmens ab und senden Sie sie zur Synchronisierung mit Google-Identitäten an Google.

Abhängigkeiten einrichten

Sie müssen bestimmte Abhängigkeiten in Ihre Build-Datei aufnehmen, um das SDK verwenden zu können. Klicken Sie unten auf einen Tab, um die Abhängigkeiten für Ihre Build-Umgebung aufzurufen:

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'

Connector-Konfiguration erstellen

Jeder Connector hat eine Konfigurationsdatei mit Parametern, die vom Connector verwendet werden, z. B. die ID für Ihr Repository. Parameter werden als Schlüssel/Wert-Paare definiert, z. B. api.sourceId=1234567890abcdef.

Das Google Cloud Search SDK enthält mehrere von Google bereitgestellte Konfigurationsparameter, die von allen Connectors verwendet werden. Sie müssen die folgenden von Google bereitgestellten Parameter in Ihrer Konfigurationsdatei deklarieren:

  • Für einen Inhaltsconnector benötigen Sie die Parameter api.sourceId und api.serviceAccountPrivateKeyFile, da diese den Speicherort Ihres Repositorys und des für den Zugriff auf das Repository erforderlichen privaten Schlüssels angeben.
  • Für einen Identitätsconnector benötigen Sie den Parameter api.identitySourceId, da dieser den Speicherort Ihrer externen Identitätsquelle angibt. Wenn Sie Nutzer synchronisieren, müssen Sie auch api.customerId als eindeutige ID für das Google Workspace-Konto Ihres Unternehmens deklarieren.

Wenn Sie die Standardwerte anderer von Google bereitgestellter Parameter nicht überschreiben möchten, müssen Sie diese nicht in Ihrer Konfigurationsdatei angeben. Weitere Informationen zu den von Google bereitgestellten Konfigurationsparametern, z. B. wie Sie bestimmte IDs und Schlüssel generieren, finden Sie unter Von Google bereitgestellte Konfigurationsparameter.

Sie können auch eigene Repository-spezifische Parameter zur Verwendung in Ihrer Konfigurationsdatei definieren.

Konfigurationsdatei an den Connector übergeben

Legen Sie das Systemattribut config so fest, dass die Konfigurationsdatei an den Connector übergeben wird. Sie können das Attribut beim Starten des Connectors mit dem Argument -D festlegen. Mit dem folgenden Befehl wird der Connector beispielsweise mit der Konfigurationsdatei MyConfig.properties gestartet:

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

Wenn dieses Argument fehlt, versucht das SDK, auf eine Standardkonfigurationsdatei mit dem Namen connector-config.properties zuzugreifen.

Mithilfe einer Vorlagenklasse einen Identitätsconnector für eine vollständige Synchronisierung erstellen

Das Identity Connector SDK enthält die Vorlagenklasse FullSyncIdentityConnector, mit der Sie alle Nutzer und Gruppen aus dem Identitätsrepository mit Google-Identitäten synchronisieren können. In diesem Abschnitt wird erläutert, wie Sie mit der Vorlage FullSyncIdentityConnector eine vollständige Synchronisierung von Nutzern und Gruppen aus einem Identitäts-Repository durchführen, das nicht von Google stammt.

Dieser Abschnitt bezieht sich auf Code-Snippets aus dem Beispiel IdentityConnecorSample.java. In diesem Beispiel werden Nutzer- und Gruppenidentitäten aus zwei CSV-Dateien gelesen und mit Google-Identitäten synchronisiert.

Einstiegspunkt des Connectors implementieren

Der Einstiegspunkt für einen Connector ist die Methode main(). Die Hauptaufgabe dieser Methode besteht darin, eine Instanz der Klasse Application zu erstellen und deren Methode start() aufzurufen, um den Connector auszuführen.

Verwenden Sie vor dem Aufrufen von application.start() die Klasse IdentityApplication.Builder, um die Vorlage FullSyncIdentityConnector zu instanziieren. Für FullSyncIdentityConnector wird ein Repository-Objekt akzeptiert, dessen Methoden Sie implementieren. Das folgende Code-Snippet zeigt, wie die Methode main() implementiert wird:

IdentityConnectorSample.java
/**
 * 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();
}

Nachdem Application.build von der Methode main() des Connectors aufgerufen wurde, ruft das SDK im Hintergrund die Methode initConfig() auf. Die Methode initConfig() führt die folgenden Aufgaben aus:

  1. Durch Aufrufen der Methode Configuation.isInitialized() wird dafür gesorgt, dass Configuration noch nicht initialisiert wurde.
  2. Ein Configuration-Objekt wird mit den von Google bereitgestellten Schlüssel/Wert-Paaren initialisiert. Jedes Schlüssel/Wert-Paar wird in einem ConfigValue-Objekt innerhalb des Configuration-Objekts gespeichert.

Repository-Schnittstelle implementieren

Die einzige Aufgabe des Repository-Objekts besteht darin, die Repository-Identitäten mit den Google-Identitäten zu synchronisieren. Wenn Sie eine Vorlage verwenden, müssen Sie nur bestimmte Methoden in der Repository-Schnittstelle überschreiben, um einen Identitätsconnector zu erstellen. Für FullTraversalConnector überschreiben Sie wahrscheinlich die folgenden Methoden:

  • Die Methode init(). Wenn Sie ein Identitäts-Repository einrichten und initialisieren möchten, überschreiben Sie die Methode „init()“.

  • Die Methode listUsers(). Wenn Sie alle Nutzer im Identitäts-Repository mit Google-Nutzern synchronisieren möchten, überschreiben Sie die Methode listUsers().

  • Die Methode listGroups(). Wenn Sie alle Gruppen im Identitäts-Repository mit Google Groups synchronisieren möchten, überschreiben Sie die Methode listGroups().

  • Optional: Die Methode close(). Wenn Sie eine Repository-Bereinigung ausführen müssen, überschreiben Sie die Methode close(). Diese Methode wird beim Herunterfahren des Connectors einmal aufgerufen.

Benutzerdefinierte Konfigurationsparameter abrufen

Im Rahmen der Konfiguration des Connectors müssen Sie alle benutzerdefinierten Parameter aus dem Configuration-Objekt abrufen. Diese Aufgabe wird normalerweise in der Methode init() einer Repository-Klasse ausgeführt.

Die Klasse Configuration bietet mehrere Methoden, unterschiedliche Datentypen aus einer Konfiguration abzurufen. Bei jeder Methode wird ein ConfigValue-Objekt zurückgegeben. Anschließend verwenden Sie die Methode get() des ConfigValue-Objekts, um den tatsächlichen Wert abzurufen. Das folgende Snippet zeigt, wie die Werte userMappingCsvPath und groupMappingCsvPath aus einem Configuration-Objekt abgerufen werden:

IdentityConnectorSample.java
/**
 * 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();
}

Verwenden Sie zum Abrufen und Parsen eines Parameters, der mehrere Werte enthält, einen der Typparser der Configuration-Klasse, um die Daten in einzelne Blöcke zu parsen. Das folgende Snippet aus dem Connector für die Anleitung verwendet die Methode getMultiValue, um eine Liste der Namen von GitHub-Repositories abzurufen:

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

Zuordnung für alle Nutzer abrufen

Überschreiben Sie listUsers(), um die Zuordnung für alle Nutzer aus Ihrem Identitäts-Repository abzurufen. Die Methode listUsers() akzeptiert einen Prüfpunkt, der die letzte zu synchronisierende Identität darstellt. Mit diesem Checkpoint kann die Synchronisierung nach einer Unterbrechung fortgesetzt werden. Führen Sie in der Methode listUsers() die folgenden Schritte für jeden Nutzer in Ihrem Repository aus:

  1. Rufen Sie eine Zuordnung ab, die aus der Google-Identität und der zugehörigen externen Identität besteht.
  2. Verpacken Sie das Paar in einen Iteration, die von der Methode listUsers() zurückgegeben wird.

Nutzerzuordnung abrufen

Das folgende Code-Snippet zeigt, wie die in einer CSV-Datei gespeicherten Identitätszuweisungen abgerufen werden:

IdentityConnectorSample.java
/**
 * 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);
    }
  }
  // ...
}

Nutzerzuordnung in einen Iteration packen

Die Methode listUsers() gibt ein Iterator zurück, genauer gesagt ein CheckpointCloseableIterable von IdentityUser-Objekten. Mit der Klasse CheckpointClosableIterableImpl.Builder können Sie einen Iterator erstellen und zurückgeben. Das folgende Code-Snippet zeigt, wie die einzelnen Zuordnungen in eine Liste verpackt werden, um aus dieser Liste den Iterator zu erstellen:

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

Gruppe abrufen

Überschreiben Sie listGroups(), um alle Gruppen und deren Mitglieder aus Ihrem Identitätsrepository abzurufen. Die Methode listGroups() akzeptiert einen Prüfpunkt, der die letzte zu synchronisierende Identität darstellt. Mit dem Checkpoint kann die Synchronisierung nach einer möglichen Unterbrechung fortgesetzt werden. Führen Sie in der Methode listGroups() die folgenden Schritte für jeden Nutzer in Ihrem Repository aus:

  1. Gruppe und ihre Mitglieder abrufen
  2. Verpacken Sie alle Gruppen und Mitglieder einem Iterator, der von der Methode listGroups() zurückgegeben wird.

Gruppenidentität abrufen

Das folgende Code-Snippet zeigt, wie die in einer CSV-Datei gespeicherten Gruppen und Mitglieder abgerufen werden:

IdentityConnectorSample.java
/**
 * 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);
    }
  }
  // ...

}

Gruppe und Mitglieder in einen Iteration packen

Die Methode listGroups() gibt ein Iterator zurück, genauer gesagt ein CheckpointCloseableIterable von IdentityGroup-Objekten. Mit der Klasse CheckpointClosableIterableImpl.Builder können Sie einen Iterator erstellen und zurückgeben. Das folgende Code-Snippet zeigt, wie Sie jede Gruppe und jedes Mitglied in einer Liste verpacken und den Iterator aus dieser Liste erstellen:

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

Nächste Schritte

Als Nächstes könnten Sie Folgendes tun: