Utwórz łącznik tożsamości

Domyślnie Google Cloud Search rozpoznaje tylko tożsamości Google zapisane w Google Cloud Directory (użytkowników i grupach). Oprogramowanie sprzęgające tożsamości służy do synchronizowania tożsamości Twojej firmy z tożsamościami Google używanymi przez Google Cloud Search.

Google udostępnia następujące opcje tworzenia oprogramowania sprzęgającego tożsamości:

  • Identity Connector SDK. Ta opcja jest przeznaczona dla programistów programujących w języku Java. Identity Connector SDK to otoka interfejsu API REST, która umożliwia szybkie tworzenie oprogramowania sprzęgającego. Aby utworzyć oprogramowanie sprzęgające tożsamości za pomocą pakietu SDK, zapoznaj się z sekcją Tworzenie oprogramowania sprzęgającego tożsamości przy użyciu pakietu SDK Identity Connector.

  • interfejsu API typu REST i bibliotek API niskiego poziomu; Te opcje są przeznaczone dla programistów, którzy mogą nie programować w języku Java lub takich, których baza kodu lepiej obsługuje interfejs API REST lub bibliotekę. Aby utworzyć oprogramowanie sprzęgające tożsamości za pomocą interfejsu API typu REST, zapoznaj się z artykułem Directory API: User Accounts (Katalog API: konta użytkowników), który zawiera informacje o mapowaniu kont użytkowników, oraz dokumentacją Cloud Identity zawierającą informacje na temat grup mapowania.

Utwórz oprogramowanie sprzęgające tożsamości przy użyciu pakietu SDK Identity Connector

Typowe oprogramowanie sprzęgające tożsamości wykonuje te zadania:

  1. Skonfiguruj oprogramowanie sprzęgające.
  2. Pobieraj wszystkich użytkowników z firmowego systemu tożsamości i wysyłaj ich do Google w celu zsynchronizowania ich z tożsamościami Google.
  3. Pobierz wszystkie grupy z firmowego systemu tożsamości i wyślij je do Google, aby zsynchronizować je z tożsamościami Google.

Skonfiguruj zależności

Aby korzystać z pakietu SDK, musisz umieścić w pliku kompilacji pewne zależności. Kliknij kartę poniżej, aby wyświetlić zależności swojego ś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żde oprogramowanie sprzęgające ma plik konfiguracji zawierający parametry używane przez oprogramowanie sprzęgające, takie jak identyfikator repozytorium. Parametry są definiowane jako pary klucz-wartość, np. api.sourceId=1234567890abcdef.

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

  • W przypadku oprogramowania sprzęgającego treści musisz zadeklarować api.sourceId i api.serviceAccountPrivateKeyFile, ponieważ te parametry identyfikują lokalizację repozytorium i klucz prywatny niezbędny do uzyskania dostępu do repozytorium.
  • W przypadku oprogramowania sprzęgającego tożsamości musisz zadeklarować api.identitySourceId, ponieważ ten parametr identyfikuje 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 swojej firmy.

Jeśli nie chcesz zastąpić domyślnych wartości innych parametrów dostarczonych przez Google, nie musisz ich deklarować w pliku konfiguracji. Więcej informacji o parametrach konfiguracyjnych dostarczonych przez Google, np. o sposobie generowania określonych identyfikatorów i kluczy, znajdziesz w sekcji Parametry konfiguracji dostarczone przez Google.

Możesz też zdefiniować własne parametry repozytorium do użycia w pliku konfiguracji.

Przekaż plik konfiguracji do oprogramowania sprzęgającego

Ustaw właściwość systemową config, aby przekazywać plik konfiguracji do oprogramowania sprzęgającego. Możesz ustawić właściwość za pomocą argumentu -D podczas uruchamiania oprogramowania sprzęgającego. Na przykład to polecenie uruchamia oprogramowanie sprzęgające od pliku konfiguracji MyConfig.properties:

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

Jeśli nie ma tego argumentu, pakiet SDK próbuje uzyskać dostęp do domyślnego pliku konfiguracji o nazwie connector-config.properties.

Tworzenie pełnego oprogramowania sprzęgającego tożsamości synchronizacji za pomocą klasy szablonu

Pakiet SDK Identity Connector zawiera klasę szablonu FullSyncIdentityConnector, której możesz używać do synchronizacji wszystkich użytkowników i grup z repozytorium tożsamości z tożsamościami Google. Ta sekcja wyjaśnia, jak za pomocą szablonu FullSyncIdentityConnector przeprowadzić pełną synchronizację użytkowników i grup z repozytorium tożsamości spoza Google.

W tej sekcji dokumentacji opisujemy fragmenty kodu z przykładowego pliku IdentityConnecorSample.java. Ten przykład odczytuje tożsamości użytkowników i grup z 2 plików CSV oraz synchronizuje je z tożsamościami Google.

Wdróż punkt wejścia oprogramowania sprzęgającego

Punktem wejścia do oprogramowania sprzęgającego jest metoda main(). Głównym zadaniem tej metody jest utworzenie instancji klasy Application i wywołanie jej metody start() w celu uruchomienia oprogramowania sprzęgającego.

Przed wywołaniem application.start() użyj klasy IdentityApplication.Builder do utworzenia instancji szablonu FullSyncIdentityConnector. FullSyncIdentityConnector akceptuje obiekt Repository, którego metody zaimplementujesz. Ten fragment kodu pokazuje, jak wdrożyć 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() oprogramowania sprzęgającego Application.build. Metoda initConfig() wykonuje te zadania:

  1. Wywołuje metodę Configuation.isInitialized(), aby mieć pewność, że element Configuration nie został zainicjowany.
  2. Inicjuje obiekt Configuration za pomocą par klucz-wartość udostępnionych przez Google. Każda para klucz-wartość jest przechowywana w obiekcie ConfigValue w obiekcie Configuration.

Implementowanie interfejsu Repository

Jedynym przeznaczeniem obiektu Repository jest synchronizowanie tożsamości repozytoriów z tożsamościami Google. Podczas korzystania z szablonu wystarczy zastąpić tylko niektóre metody w interfejsie Repository, aby utworzyć łącznik tożsamości. W przypadku FullTraversalConnector prawdopodobnie zastąpisz te metody:

  • Metoda init(). Aby skonfigurować lub zainicjować dowolne repozytorium tożsamości, zastąp metodę `init().

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

  • Metoda listGroups(). Aby zsynchronizować wszystkie grupy w repozytorium tożsamości z Grupami dyskusyjnymi Google, zastąp metodę listGroups().

  • (opcjonalnie) Metoda close(). Jeśli musisz wyczyścić repozytorium, zastąp metodę close(). Ta metoda jest wywoływana raz podczas wyłączania oprogramowania sprzęgającego.

Pobierz niestandardowe parametry konfiguracji

W ramach obsługi konfiguracji oprogramowania sprzęgającego musisz uzyskać z obiektu Configuration wszelkie parametry niestandardowe. To zadanie jest zwykle wykonywane w metodzie init() klasy Repository.

Klasa Configuration ma kilka metod pobierania różnych typów danych z konfiguracji. Każda metoda zwraca obiekt ConfigValue. Następnie użyj 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 parserów typu Configuration w celu przeanalizowania danych na osobne fragmenty. Ten fragment kodu z oprogramowania sprzęgającego samouczka korzysta z metody getMultiValue, aby uzyskać listę nazw repozytoriów GitHub:

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

Pobierz mapowanie dla wszystkich użytkowników

Zastąp listUsers(), aby pobrać mapowanie wszystkich użytkowników z repozytorium tożsamości. Metoda listUsers() akceptuje punkt kontrolny reprezentujący ostatnią tożsamość do zsynchronizowania. Możesz go użyć do wznowienia synchronizacji, jeśli proces zostanie przerwany. W przypadku każdego użytkownika w repozytorium wykonasz te czynności w metodzie listUsers():

  1. Pobierz mapowanie obejmujące tożsamość Google i powiązaną tożsamość zewnętrzną.
  2. Spakuj parę do iteratora zwracanego przez metodę listUsers().

Pobieranie mapowania użytkownika

Ten fragment kodu pokazuje, jak pobrać 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 element Iterator, a konkretnie CheckpointCloseableIterable, spośród obiektów IdentityUser. Klasy CheckpointClosableIterableImpl.Builder możesz użyć do utworzenia i zwrócenia iteratora. Ten fragment kodu pokazuje, jak umieścić poszczególne mapowania w listę i utworzyć z niej iterator:

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

Utwórz grupę

Zastąp listGroups(), aby pobrać wszystkie grupy i ich członków z repozytorium tożsamości. Metoda listGroups() akceptuje punkt kontrolny reprezentujący ostatnią tożsamość do synchronizacji. Punkt kontroli może zostać użyty do wznowienia synchronizacji w przypadku przerwania procesu. W przypadku każdego użytkownika w repozytorium wykonasz te czynności w metodzie listGroups():

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

Pobieranie tożsamości grupy

Ten fragment kodu pokazuje, jak pobrać grupy i członków zapisane w 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);
    }
  }
  // ...

}

Pakowanie grupy i członków w iterator

Metoda listGroups() zwraca element Iterator, a konkretnie CheckpointCloseableIterable, spośród obiektów IdentityGroup. Klasy CheckpointClosableIterableImpl.Builder możesz użyć do utworzenia i zwrócenia iteratora. Poniższy fragment kodu pokazuje, jak umieścić poszczególne grupy i członków na listę oraz jak na jej podstawie utworzyć iterator:

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

Dalsze kroki

Oto kilka dalszych kroków, które możesz podjąć: