Utwórz łącznik tożsamości

Domyślnie Google Cloud Search rozpoznaje tylko tożsamości Google przechowywane w katalogu Google Cloud (użytkownicy i grupy). Połączenia tożsamości służą do synchronizowania tożsamości Twojej firmy z tożsamościami Google używanymi przez Google Cloud Search.

Google udostępnia te opcje tworzenia łączników tożsamości:

  • Pakiet SDK łącznika tożsamości. Ta opcja jest przeznaczona dla programistów, którzy programują w języku Java. Pakiet SDK oprogramowania sprzęgającego tożsamości to opakowanie interfejsu API REST, które umożliwia szybkie tworzenie oprogramowania sprzęgającego. Aby utworzyć łącznik tożsamości za pomocą pakietu SDK, zapoznaj się z artykułem Tworzenie łącznika tożsamości za pomocą pakietu SDK Identity Connector.

  • interfejs API REST niskiego poziomu i biblioteki API; Te opcje są przeznaczone dla programistów, którzy nie programują w języku Java lub których kod źródłowy lepiej współpracuje z interfejsem REST API lub biblioteką. Aby utworzyć oprogramowanie sprzęgające tożsamości za pomocą interfejsu API REST, zapoznaj się z artykułem Directory API: User Accounts (interfejs Directory API: konta użytkowników) zawierającym informacje o mapowaniu użytkowników oraz dokumentacją Cloud Identity (dokumentacja Cloud Identity) zawierającą informacje o mapowaniu grup.

Tworzenie łącznika tożsamości za pomocą pakietu SDK łącznika tożsamości

Typowy łącznik tożsamości wykonuje te zadania:

  1. Skonfiguruj oprogramowanie sprzęgające.
  2. Pobierz wszystkich użytkowników z systemu tożsamości korporacyjnej i prześlij ich do Google w celu zsynchronizowania z tożsamościami Google.
  3. Pobierz wszystkie grupy z systemu tożsamości korporacyjnej i wyślij je do Google w celu zsynchronizowania ich z tożsamościami Google.

Konfigurowanie zależności

Aby korzystać z pakietu SDK, musisz uwzględnić w pliku kompilacji określone zależności. Aby wyświetlić zależności środowiska kompilacji:

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'

Tworzenie konfiguracji oprogramowania sprzęgającego

Każdy łącznik ma plik konfiguracji zawierający parametry używane przez łącznik, takie jak identyfikator repozytorium. Parametry są definiowane jako pary klucz-wartość, np. api.sourceId=1234567890abcdef.

Pakiet SDK Google Cloud Search zawiera kilka parametrów konfiguracji dostarczonych przez Google, które są używane przez wszystkie oprogramowania sprzęgające. W pliku konfiguracyjnym musisz zadeklarować te parametry dostarczane przez Google:

  • W przypadku łącznika treści musisz zadeklarować parametry api.sourceId i api.serviceAccountPrivateKeyFile, ponieważ wskazują one lokalizację repozytorium i klucz prywatny potrzebny do uzyskania dostępu do repozytorium.
  • W przypadku łącznika tożsamości musisz zadeklarować parametr api.identitySourceId, ponieważ wskazuje on lokalizację zewnętrznego źródła tożsamości. Jeśli synchronizujesz użytkowników, musisz też zadeklarować api.customerId jako unikalny identyfikator konta Google Workspace Twojej firmy.

O ile nie chcesz zastąpić domyślnych wartości innych parametrów dostarczanych przez Google, nie musisz ich deklarować w pliku konfiguracyjnym. Więcej informacji o parametrach konfiguracji udostępnianych przez Google, np. o generowaniu określonych identyfikatorów i kluczy, znajdziesz w artykule Parametry konfiguracji udostępniane przez Google.

Możesz też zdefiniować własne parametry repozytorium, które będą używane w pliku konfiguracyjnym.

Przekazywanie pliku konfiguracji do oprogramowania sprzęgającego

Ustaw właściwość systemową config, aby przekazać plik konfiguracji do łącznika. Właściwość tę możesz ustawić, używając argumentu -D podczas uruchamiania łącznika. Na przykład to polecenie uruchamia łącznik za pomocą pliku konfiguracji MyConfig.properties:

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

Jeśli ten argument jest nieobecny, pakiet SDK próbuje uzyskać dostęp do domyślnego pliku konfiguracji o nazwie connector-config.properties.

Tworzenie pełnego łącznika tożsamości z użyciem klasy szablonu

Pakiet SDK łącznika tożsamości zawiera klasę szablonu FullSyncIdentityConnector, której możesz użyć do zsynchronizowania wszystkich użytkowników i grup z repozytorium tożsamości z tożsamościami Google. Z tej sekcji dowiesz się, jak użyć szablonu FullSyncIdentityConnector do pełnej synchronizacji użytkowników i grup z repozytorium tożsamości spoza Google.

Ta sekcja dokumentów odnosi się do fragmentów kodu z przykładu IdentityConnecorSample.java. Ten przykład odczytuje tożsamości użytkowników i grup z 2 plików CSV i zsynchronizuje je z tożsamościami Google.

Implementowanie punktu wejścia oprogramowania sprzęgającego

Punkt wejścia do łącznika to metoda main(). Głównym zadaniem tej metody jest utworzenie instancji klasy Application i wywołanie jej metody start(), aby uruchomić oprogramowanie sprzęgające.

Zanim wywołasz funkcję application.start(), użyj klasy IdentityApplication.Builder, aby utworzyć instancję szablonu FullSyncIdentityConnector. Funkcja FullSyncIdentityConnector przyjmuje obiekt Repository, którego metody zaimplementujesz. Ten fragment kodu pokazuje, jak zastosować metodę 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();
}

W tle pakiet SDK wywołuje metodę initConfig() po wywołaniu metody main() w kontekście połączenia Application.build. Metoda initConfig() wykonuje te zadania:

  1. Wywołuje metodę Configuation.isInitialized(), aby sprawdzić, czy nie została zainicjowana zmienna Configuration.
  2. Inicjuje obiekt Configuration za pomocą par klucz-wartość dostarczonych przez Google. Każda para klucz-wartość jest przechowywana w obiekcie ConfigValue w obiekcie Configuration.

Zaimplementuj interfejs Repository.

Jedynym celem obiektu Repository jest zsynchronizowanie tożsamości repozytorium z tożsamościami Google. Aby utworzyć łącznik tożsamości, wystarczy zastąpić w interfejsie Repository tylko niektóre metody. W przypadku FullTraversalConnector najprawdopodobniej zastąpisz te metody:

  • metoda init(). Aby przeprowadzić konfigurację i inicjalizację repozytorium tożsamości, zastąpij metodę init().

  • metoda listUsers(). Aby zsynchronizować wszystkich użytkowników w repozytorium tożsamości z użytkownikami Google, zastąpij metodę listUsers().

  • metoda listGroups(). Aby zsynchronizować wszystkie grupy w repozytorium tożsamości z Google Groups, zastąpij metodę listGroups().

  • (opcjonalnie) metoda close(). Jeśli musisz wyczyścić repozytorium, zastąpij metodę close(). Ta metoda jest wywoływana raz podczas zamykania łącznika.

Pobieranie parametrów konfiguracji niestandardowej

W ramach obsługi konfiguracji łącznika musisz pobrać wszystkie parametry niestandardowe z obiektu Configuration. Zwykle jest to wykonywane w metodach klasy Repository init().

Klasa Configuration udostępnia kilka metod służących do uzyskiwania różnych typów danych z konfiguracji. Każda metoda zwraca obiekt ConfigValue. Następnie użyjesz metody get() obiektu ConfigValue, aby pobrać rzeczywistą wartość. Ten fragment kodu pokazuje, jak pobrać wartości userMappingCsvPath i groupMappingCsvPath z obiektu Configuration:

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();
}

Aby pobrać i przeanalizować parametr zawierający kilka wartości, użyj jednego z analizatorów typu klasy Configuration, aby przeanalizować dane na oddzielne fragmenty. Ten fragment kodu z konektora w samouczku używa metody getMultiValue do uzyskiwania listy nazw repozytoriów GitHub:

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

Pobieranie mapowania dla wszystkich użytkowników

Zastąp: listUsers() , aby pobrać mapowanie wszystkich użytkowników z repozytorium tożsamości. Metoda listUsers() przyjmuje punkt kontrolny reprezentujący ostatnią zsynchronizowaną tożsamość. W przypadku przerwania procesu synchronizacji możesz użyć punktu kontrolnego, aby wznowić synchronizację. W przypadku każdego użytkownika w repozytorium wykonaj te czynności w metodzie listUsers():

  1. Uzyskaj mapowanie tożsamości Google i powiązanej z nią tożsamości zewnętrznej.
  2. Prześlij parę do licznika zwracanego przez metodę listUsers().

Pobieranie mapowania użytkownika

Ten fragment kodu pokazuje, jak pobierać mapowania tożsamości zapisane w pliku CSV:

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

Pakowanie mapowania użytkownika w iterator

Metoda listUsers() zwraca obiekt Iterator, a w szczególności CheckpointCloseableIterable obiektów IdentityUser. Aby utworzyć i zwrócić iterator, możesz użyć klasy CheckpointClosableIterableImpl.Builder. Ten fragment kodu pokazuje, jak zapakować każde mapowanie do listy, aby utworzyć dla niej iterator:

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

Utwórz grupę

Zastąpij parametr listGroups(), aby pobrać wszystkie grupy i ich członków z repozytorium tożsamości. Metoda listGroups() przyjmuje punkt kontrolny reprezentujący ostatnią tożsamość do zsynchronizowania. W przypadku przerwania procesu możesz użyć punktu kontrolnego, aby wznowić synchronizację. W przypadku każdego użytkownika w repozytorium wykonaj te czynności w metodzie listGroups():

  1. Pobierz grupę i jej członków.
  2. Spakuj każdą grupę i jej członków do licznika zwracanego przez metodę listGroups().

Pobieranie tożsamości grupy

Ten fragment kodu pokazuje, jak pobierać grupy i ich członków z pliku CSV:

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

}

Spakuj grupę i jej członków do iteratora.

Metoda listGroups() zwraca obiekt Iterator, a w szczególności CheckpointCloseableIterable obiektów IdentityGroup. Aby utworzyć i zwrócić iterator, możesz użyć klasy CheckpointClosableIterableImpl.Builder. Ten fragment kodu pokazuje, jak zapakować każdą grupę i jej elementy do listy oraz utworzyć na jej podstawie iterator:

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

Następne kroki

Oto kilka kolejnych kroków, które możesz wykonać:

  • (opcjonalnie) Zaimplementuj metodę close(), aby zwolnić wszystkie zasoby przed wyłączeniem.
  • (Opcjonalnie) Utwórz łącznik treści za pomocą pakietu SDK Content Connector.