Questa pagina è stata tradotta dall'API Cloud Translation.

Crea un connettore di identità

Per impostazione predefinita, Google Cloud Search riconosce solo le identità Google archiviate in Directory Google Cloud (utenti e gruppi). I connettori di identità vengono utilizzati per sincronizzare le identità della tua azienda con le identità Google utilizzate da Google Cloud Search.

Google fornisce le seguenti opzioni per lo sviluppo di connettori di identità:

L'SDK Identity Connector. Questa opzione è rivolta agli sviluppatori che programmano nel linguaggio di programmazione Java. L'SDK Identity Connector è un wrapper per l'API REST che consente di creare rapidamente i connettori. Per creare un connettore di identità utilizzando l'SDK, consulta Creare un connettore di identità utilizzando l'SDK Identity Connector.
Un'API REST di basso livello e librerie API. Queste opzioni sono destinate agli sviluppatori che potrebbero non programmare in Java o la cui base di codice è più adatta a una API REST o a una libreria. Per creare un connettore di identità utilizzando l'API REST, consulta API Directory: Account utente per informazioni sulla mappatura degli utenti e la documentazione di Cloud Identity per informazioni sulla mappatura dei gruppi.

Creare un connettore di identità utilizzando l'SDK Identity Connector

Un tipico connettore di identità esegue le seguenti attività:

Configura il connettore.
Recupera tutti gli utenti dal sistema di identità aziendale e inviali a Google per la sincronizzazione con le identità Google.
Recupera tutti i gruppi dal sistema di identità aziendale e inviali a Google per la sincronizzazione con le identità Google.

Configura le dipendenze

Per utilizzare l'SDK, devi includere determinate dipendenze nel file di compilazione. Fai clic su una scheda di seguito per visualizzare le dipendenze per il tuo ambiente di build:

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'

Crea la configurazione del connettore

Ogni connettore ha un file di configurazione contenente i parametri utilizzati dal connettore, ad esempio l'ID del repository. I parametri sono definiti come coppie chiave-valore, ad esempio api.sourceId=1234567890abcdef.

L'SDK Google Cloud Search contiene diversi parametri di configurazione forniti da Google utilizzati da tutti i connettori. Devi dichiarare i seguenti parametri forniti da Google nel file di configurazione:

Per un connettore di contenuti, devi dichiarare api.sourceId e api.serviceAccountPrivateKeyFile perché questi parametri identificano la posizione del tuo repository e la chiave privata necessaria per accedere al repository.

Per un connettore di identità, devi dichiarare api.identitySourceId poiché questo parametro identifica la posizione dell'origine dell'identità esterna. Se sincronizzi gli utenti, devi anche dichiarare api.customerId come ID univoco per l'account Google Workspace della tua azienda.

A meno che tu non voglia sostituire i valori predefiniti di altri parametri forniti da Google, non è necessario dichiararli nel file di configurazione. Per ulteriori informazioni sui parametri di configurazione forniti da Google, ad esempio su come generare determinati ID e chiavi, consulta Parametri di configurazione forniti da Google.

Puoi anche definire i tuoi parametri specifici del repository da utilizzare nel file di configurazione.

Passa il file di configurazione al connettore

Imposta la proprietà di sistema config per passare il file di configurazione al connettore. Puoi impostare la proprietà utilizzando l'argomento -D all'avvio del connettore. Ad esempio, il seguente comando avvia il connettore con il file di configurazione MyConfig.properties:

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

Se questo argomento non è presente, l'SDK tenta di accedere a un file di configurazione predefinito denominato connector-config.properties.

Creare un connettore di identità con sincronizzazione completa utilizzando una classe modello

L'SDK Identity Connector contiene una FullSyncIdentityConnector classe di modelli che puoi utilizzare per sincronizzare tutti gli utenti e i gruppi dal repository delle identità con le identità Google. Questa sezione spiega come utilizzare il modello FullSyncIdentityConnector per eseguire una sincronizzazione completa di utenti e gruppi da un repository di identità non Google.

Questa sezione della documentazione fa riferimento agli snippet di codice dell'esempio IdentityConnecorSample.java. Questo esempio legge le identità di gruppi e utenti da due file CSV e le sincronizza con le identità Google.

Implementa il punto di contatto del connettore

L'entry point di un connettore è il metodo main(). Il compito principale di questo metodo è creare un'istanza della classe Application e invocarne il metodo start() per eseguire il connettore.

Prima di chiamare application.start(), utilizza la classe IdentityApplication.Builder per creare un'istanza del modello FullSyncIdentityConnector. FullSyncIdentityConnector accetta un oggetto Repository cuyos metodi dovrai implementare. Il seguente snippet di codice mostra come implementare il metodo main():

IdentityConnectorSample.java

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

Dietro le quinte, l'SDK chiama il metodo initConfig() dopo che il metodo main() del connettore chiama Application.build. Il metodo initConfig() esegue le seguenti attività:

Chiama il metodo Configuation.isInitialized() per assicurarsi che Configuration non sia stato inizializzato.
Inizializza un oggetto Configuration con le coppie chiave-valore fornite da Google. Ogni coppia chiave-valore viene archiviata in un oggetto ConfigValue all'interno dell'oggetto Configuration.

Implementa l'interfaccia `Repository`

L'unico scopo dell'oggetto Repository è eseguire il sincronizzazione delle identità del repository con le identità Google. Quando utilizzi un modello, devi solo sostituire determinati metodi all'interno dell'interfaccia Repository per creare un connettore di identità. Per FullTraversalConnector, probabilmente sostituirai i seguenti metodi:

Il metodo init(). Per eseguire la configurazione e l'inizializzazione del repository delle identità, sostituisci il metodo "init()".
Il metodo listUsers(). Per sincronizzare tutti gli utenti nel repository delle identità con gli utenti Google, sostituisci il metodo listUsers().
Il metodo listGroups(). Per sincronizzare tutti i gruppi nel repository delle identità con Google Gruppi, override il metodo listGroups().
(Facoltativo) Il metodo close(). Se devi eseguire la pulizia del repository, sostituisci il metodo close(). Questo metodo viene chiamato una volta durante l'arresto del connettore.

Ottenere i parametri di configurazione personalizzati

Nell'ambito della gestione della configurazione del connettore, dovrai recuperare eventuali parametri personalizzati dall'oggetto Configuration. Questa operazione viene in genere eseguita in un metodo init() della classe Repository.

La classe Configuration ha diversi metodi per ottenere tipi di dati diversi da una configurazione. Ogni metodo restituisce un oggetto ConfigValue. Dovrai quindi utilizzare il metodo get() dell'oggetto ConfigValue per recuperare il valore effettivo. Lo snippet seguente mostra come recuperare il valore userMappingCsvPath e groupMappingCsvPath da un oggetto Configuration:

IdentityConnectorSample.java

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

Per ottenere e analizzare un parametro contenente più valori, utilizza uno degli analizzatori di tipo della classe Configuration per analizzare i dati in blocchi distinti. Il seguente snippet, dal connettore del tutorial, utilizza il metodo getMultiValue per ottenere un elenco di nomi di repository GitHub:

GithubRepository.java

Visualizza su GitHub

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

Ottenere la mappatura per tutti gli utenti

Sostituisci listUsers() per recuperare la mappatura per tutti gli utenti dal tuo repository delle identità. Il metodo listUsers() accetta un checkpoint che rappresenta l'ultima identità da sincronizzare. Il checkpoint può essere utilizzato per riprendere la sincronizzazione se il processo viene interrotto. Per ogni utente nel tuo repository, esegui questi passaggi nel metodo listUsers():

Ottieni una mappatura composta dall'identità Google e dall'identità esterna associata.
Impacchetta la coppia in un iteratore restituito dal metodo listUsers().

Ottenere una mappatura utente

Il seguente snippet di codice mostra come recuperare le mappature delle identità memorizzate in un file CSV:

IdentityConnectorSample.java

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

Imballare una mappatura utente in un iteratore

Il metodo listUsers() restituisce un Iterator, nello specifico un CheckpointCloseableIterable, di IdentityUser oggetti. Puoi utilizzare la classe CheckpointClosableIterableImpl.Builder per creare e restituire un iteratore. Il seguente snippet di codice mostra come impacchettare ogni mappatura in un elenco e creare l'iteratore da quell'elenco:

IdentityConnectorSample.java

Visualizza su GitHub

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

Crea un gruppo

Sostituisci listGroups() per recuperare tutti i gruppi e i relativi membri dal tuo repository di identità. Il metodo listGroups() accetta un checkpoint che rappresenta l'ultima identità da sincronizzare. Il checkpoint può essere utilizzato per riprendere la sincronizzazione se il processo viene interrotto. Per ogni utente nel tuo repository, esegui questi passaggi nel metodo listGroups():

Ottieni il gruppo e i relativi membri.
Raggruppa ogni gruppo e i relativi membri in un iteratore restituito dal metodo listGroups().

Recupera l'identità del gruppo

Il seguente snippet di codice mostra come recuperare i gruppi e i membri memorizzati in un file CSV:

IdentityConnectorSample.java

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

}

Raggruppa il gruppo e i membri in un iteratore

Il metodo listGroups() restituisce un Iterator, nello specifico un CheckpointCloseableIterable, di IdentityGroup oggetti. Puoi utilizzare la classe CheckpointClosableIterableImpl.Builder per creare e restituire un iteratore. Il seguente snippet di codice mostra come impacchettare ogni gruppo e i relativi membri in un elenco e creare l'iteratore da quell'elenco:

IdentityConnectorSample.java

Visualizza su GitHub

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

Passaggi successivi

Ecco alcuni passaggi successivi che puoi intraprendere:

(Facoltativo) Implementa il metodo close() per rilasciare le risorse prima dell'arresto.
(Facoltativo) Crea un connettore di contenuti utilizzando l'SDK Content Connector.

Crea un connettore di identità

Creare un connettore di identità utilizzando l'SDK Identity Connector

Configura le dipendenze

Maven

Gradle

Crea la configurazione del connettore

Passa il file di configurazione al connettore

Creare un connettore di identità con sincronizzazione completa utilizzando una classe modello

Implementa il punto di contatto del connettore

Implementa l'interfaccia Repository

Ottenere i parametri di configurazione personalizzati

Ottenere la mappatura per tutti gli utenti

Ottenere una mappatura utente

Imballare una mappatura utente in un iteratore

Crea un gruppo

Recupera l'identità del gruppo

Raggruppa il gruppo e i membri in un iteratore

Passaggi successivi

Implementa l'interfaccia `Repository`