Identitätsconnector erstellen

Standardmäßig werden von Google Cloud Search nur Google-Identitäten erkannt, die im Google Cloud-Verzeichnis gespeichert sind, also Nutzer und Gruppen. Mithilfe von Identitätsconnectors können Sie die Identitäten in Ihrem Unternehmen mit den Google-Identitäten synchronisieren, die von Google Cloud Search verwendet werden.

Google bietet Ihnen die folgenden Möglichkeiten, Identitätsconnectors zu entwickeln:

  • Das Identity Connector SDK. Diese Option eignet sich für Java-Entwickler. Dieses SDK ist ein Wrapper für die REST API, mit dem Sie Connectors schnell erstellen können. Wie Sie mit dem SDK einen Identitätsconnector erstellen und verwenden, erfahren Sie im Abschnitt Mit dem Identity Connector SDK einen Identitätsconnector erstellen.

  • Eine Low-Level-REST API und API-Bibliotheken: Diese Optionen sind für Entwickler gedacht, die nicht mit Java programmieren oder für deren Codebasis eine REST API oder eine Bibliothek besser geeignet ist. Wenn Sie mithilfe der REST API einen Identitätsconnector erstellen möchten, sollten Sie den Directory API-Leitfaden zu Nutzerkonten und die Dokumentation zu Cloud Identity lesen. Darin erhalten Sie mehr Informationen zur Zuordnung von Nutzern und 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 an Google, um sie mit Google-Identitäten zu synchronisieren.
  3. Rufen Sie alle Gruppen aus dem Identitätssystem Ihres Unternehmens ab und senden Sie sie an Google, um sie mit Google-Identitäten zu synchronisieren.

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 sich die Abhängigkeiten für Ihre Build-Umgebung anzusehen:

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'

Connectorkonfiguration erstellen

Jeder Connector hat eine Konfigurationsdatei mit Parametern, die von ihm verwendet werden, u. a. 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. Davon müssen Sie folgende 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 nötigen 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 api.customerId auch 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 sie auch 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 in diesem Artikel.

Sie können auch eigene Repository-spezifische Parameter für Ihre Konfigurationsdatei definieren.

Konfigurationsdatei an den Connector übergeben

Legen Sie das Systemattribut config fest, um die Konfigurationsdatei an Ihren Connector zu übergeben. Dazu verwenden Sie beim Starten des Connectors das Argument -D. Im folgenden Beispiel wird der Connector gestartet und die Konfigurationsdatei MyConfig.properties verwendet:

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.

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

Im Identity Connector SDK ist die Vorlagenklasse FullSyncIdentityConnector enthalten, 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 die Vorlage FullSyncIdentityConnector verwenden, um eine vollständige Synchronisierung von Nutzern und Gruppen aus einem Identitätsrepository durchzufü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(). Sie dient hauptsächlich dazu, eine Instanz der Klasse Application zu erstellen und die Methode start() aufzurufen, um den Connector auszuführen.

Verwenden Sie die Klasse IdentityApplication.Builder, um die Vorlage FullSyncIdentityConnector zu instanziieren, bevor Sie application.start() aufrufen. Für FullSyncIdentityConnector wird ein Repository-Objekt akzeptiert, dessen Methoden Sie implementieren. Das folgende Code-Snippet zeigt das für die Methode main():

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, wird die Methode initConfig() vom SDK im Hintergrund aufgerufen. Die Methode initConfig() führt die folgenden Aufgaben aus:

  1. Die Methode Configuation.isInitialized() wird aufgerufen, um zu prüfen, ob Configuration noch nicht initialisiert wurde.
  2. Ein Configuration-Objekt wird mithilfe der von Google bereitgestellten Schlüssel/Wert-Paare initialisiert. Jedes dieser Paare 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 innerhalb der Repository-Oberfläche überschreiben, um einen Identitätsconnector zu erstellen. Für einen FullTraversalConnector überschreiben Sie die folgenden Methoden:

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

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

  • Die Methode listGroups(). Wenn Sie alle Gruppen im Identitätsrepository mit Google-Gruppen 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(). Sie wird einmal beim Herunterfahren des Connectors aufgerufen.

Benutzerdefinierte Konfigurationsparameter abrufen

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

Die Klasse Configuration bietet Ihnen 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. Im folgenden Snippet sehen Sie, wie die Werte von userMappingCsvPath und groupMappingCsvPath des Configuration-Objekts 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();
}

Wenn Sie einen Parameter abrufen und parsen möchten, der mehrere Werte enthält, verwenden Sie einen Typ-Parser der Klasse Configuration, um die Daten in einzelne Blöcke zu parsen. Das folgende Snippet aus dem Connectorbeispiel des Tutorials zeigt, wie Sie mithilfe der Methode getMultiValue eine Liste mit Namen von GitHub-Repositories erhalten:

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ätsrepository abzurufen. An die Methode listUsers() kann ein Prüfpunkt übergeben werden, der die letzte zu synchronisierende Identität darstellt. Damit lässt sich die Synchronisierung nach einer möglichen Unterbrechung wieder aufnehmen. Führen Sie in der Methode listUsers() die folgenden Schritte für jeden Nutzer in Ihrem Repository durch:

  1. Eine Zuordnung abrufen, die aus der Google-Identität und der dazugehörigen externen Identität besteht
  2. Fügen Sie dieses Paar einem Iterator hinzu, der von der Methode listUsers() zurückgegeben wird.

Nutzerzuordnungen abrufen

Im folgenden Code-Snippet sehen Sie, wie die in einer CSV-Datei gespeicherten Identitätszuordnungen 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 Iterator packen

Die Methode listUsers() gibt Iterator zurück, genau genommen ein CheckpointCloseableIterable von IdentityUser-Objekten. Zum Erstellen und Zurückgeben eines Iterators können Sie die Klasse CheckpointClosableIterableImpl.Builder verwenden. Im folgenden Code-Snippet sehen Sie, wie die einzelnen Zuordnungen in eine Liste gepackt werden, um daraus 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. An die Methode listGroups() kann ein Prüfpunkt übergeben werden, der die letzte zu synchronisierende Identität darstellt. Damit lässt sich die Synchronisierung nach einer möglichen Unterbrechung wieder aufnehmen. Führen Sie in der Methode listGroups() die folgenden Schritte für jeden Nutzer in Ihrem Repository durch:

  1. Rufen Sie die Gruppe und ihre Mitglieder ab.
  2. Fügen Sie einem Iterator, der von der Methode listGroups() zurückgegeben wird, alle Gruppen samt Mitglieder hinzu.

Gruppenidentität abrufen

Im folgenden Code-Snippet sehen Sie, 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);
    }
  }
  // ...

}

Gruppen samt Mitgliedern in einen Iterator packen

Die Methode listGroups() gibt Iterator zurück, genau genommen ein CheckpointCloseableIterable von IdentityGroup-Objekten. Zum Erstellen und Zurückgeben eines Iterators können Sie die Klasse CheckpointClosableIterableImpl.Builder verwenden. Im folgenden Code-Snippet sehen Sie, wie jede einzelne Gruppe samt Mitglieder in eine Liste gepackt wird und wie daraus dann der Iterator erstellt wird:

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:

  • Optional: Methode close() implementieren, damit vor dem Herunterfahren alle Ressourcen wieder freigegeben werden
  • Optional: Mit dem Content Connector SDK Inhaltsconnectors erstellen