Identity Connector SDK Guide

This guide is intended for developers who are creating an identity connector using the Google Cloud Search Identity Connector SDK to map enterprise’s identities to internal Google identities used by Google Cloud Search. It contains detailed descriptions of Identity Connector SDK objects, arranged by key functionality. It also assumes you are familiar with Google Cloud Search, connector concepts, and object-oriented programming language(s) and concepts.

Accessing the connector

To access the Cloud Search Identity Connector SDK from your program, you'll use the IdentityApplication class. Every identity connector begins execution by creating an IdentityApplication instance and calling its start() method. This hands off processing to the Identity Connector SDK for making connector calls as determined by the settings that you have supplied in your configuration file for the connector.

Instantiate your application with one of the following:

  • Create a new connector instance. Use this approach if you are developing a connector from scratch, using a custom traversal implementation.
  • Create a new repository using the Google provided FullSyncIdentityConnector template class. This is the Google recommended approach.

Create a new identity connector from IdentityConnector's main()

Implement your application with a builder that passes in an instance of the current connector as a required parameter. The following code snippet shows a typical approach to initializing the SDK for a connector called MyIdentityConnector.

public class MyIdentityConnector implements IdentityConnector {
  // ...
  public static void main(String[] args)
     throws IOException, InterruptedException {

     IdentityApplication application =
         new IdentityApplication.Builder(new MyIdentityConnector(), args)
             .build();
     application.start();
   }

 // Followed by all the overridden IdentityConnector methods.
 // ...
 }

After the connector calls application.start(), the SDK gains execution control and proceeds to:

  • read the configuration file to create an IdentityService object
  • call the IdentityConnector.init() method
  • schedule traversals to fetch identity data

Using the Google provided FullSyncIdentityConnector template

Though optional, Google recommends most identity connector developers to use FullSyncIdentityConnector, a templated connector provided by the Identity Connector SDK to accelerate development. To use this provided template, pass an instance of the class during the instantiation of anIdentityApplicationinstance. Then from yourRepositorycode, build theIdentityApplicationinstance and callIdentityApplication.start(). See the following example.

public class MyRepository implements Repository {
  // ...
  public static void main(String[] args)
      throws IOException, InterruptedException {

    IdentityApplication application = new IdentityApplication.Builder(
          new FullSyncIdentityConnector(new MyRepository()), args)
           .build();
    application.start();
  }

  // Followed by all the overridden Repository methods.
  // ...
}

Of course, you could also place the main() alone in its own class to keep it separate from your IdentityConnector or Repository code.

Running the connector

Since the IdentityConnector interface extends from the Connector interface, it enables developers to implement basic connector operations resembling that of a content connector. The SDK calls on these methods during:

  • initialization (init())
  • shutdown (saveCheckpoint(), destroy())
  • scheduled traversals (traverse())

The following code snippet shows the main methods of this interface.

public interface IdentityConnector extends Connector<IdentityConnectorContext> {
  @Override
  void init(IdentityConnectorContext context) throws Exception;
}

public interface Connector {
  public void init(ConnectorContext context) throws Exception;

  public void traverse()
      throws IOException, InterruptedException;

  public void saveCheckpoint()
      throws IOException, InterruptedException;

  public void destroy();
}

Initialize the connector

The init() method enables the connector to initialize itself before accepting any requests from the SDK. The IdentityConnector interface uses the IdentityService object to perform users and groups mapping operations between an enterprise’s identity repository and Google’s identities.

Implement a traversal strategy

The traverse() method enables the connector to implement a particular traversal strategy. While executing the traverse() method, the connector interacts with the identity repository to fetch users and groups data that need to be mapped with Google identities.

If you use the provided FullSyncIdentityConnector template, the implemented traversal strategy will comprehensively sync all users and groups from the identity repository with Google’s internal identities.

Create traversal checkpoints

The saveCheckpoint() method enables the connector to start from where it left off between connector traversals. By committing incremental change tokens to the checkpoint, the connector can also recover missed changes between connector restarts. The SDK always calls the saveCheckpoint() method prior to a destroy() call.

Release traversal resources

The destroy() method enables the connector to release any resources before shutdown.

Giving the identity connector access to the SDK

The Cloud Search Identity SDK creates an IdentityConnectorContext instance to give the IdentityConnector object access to the SDK. At initialization, the IdentityApplication object calls the IdentityConnector.init() method, passing an IdentityConnectorContext object to the IdentityConnector object.

The IdentityConnectorContext interface provides the IdentityConnector communication access to Google Directory and Cloud Identity APIs by exposing the IdentityService object.

Access the IdentityService object

The IdentityConnector interface uses the IdentityConnectorContext object to retrieve the IdentityService object created by the SDK. This object is used later during identity traversals and mapping. The IdentityConnector object should save a reference to the IdentityService object.

public interface IdentityConnectorContext extends ConnectorContext {
    IdentityService getIdentityService();

Giving the identity connector access to the Google Directory and Cloud Identity APIs

The getIdentityService()method of the IdentityConnectorContext interface provides the IdentityConnector a channel to communicate with the Google Directory and Cloud Identity APIs.

Configuring Identity Connectors

The configuration file defines an identity connector behavior. The parsing of configuration values for identity connectors is identical as the method for content connectors. See Parsing configuration file parameters] for more details.

For identity connectors, the configuration parameters to pay attention to are: api.identitySourceId api.customerId api.serviceAccountPrivateKeyFile

Communicating with Google Directory and Cloud Identity APIs

The SDK performs all communication between your connector and Google Directory and Cloud Identity APIs using an IdentityServiceImpl instance of the IdentityService interface. The IdentityService interface extends the GroupsService and UsersService interfaces

The following code snippet shows the methods of the GroupsService and UsersService interfaces.

interface UsersService extends Service {
  ListenableFuture<User> getUserMapping(String userId) throws IOException;

 ListenableFuture<User> updateUserMapping(
     String userId,
     String schemaName,
     String attributeName, Optional<String> value)
     throws IOException;

Iterable<User> listUsers(String schemaName) throws IOException;
}

interface GroupsService extends Service {
  ListenableFuture<Operation> createGroup(Group group) throws IOException;

  ListenableFuture<Group> getGroup(String groupId) throws IOException;

  ListenableFuture<Operation> deleteGroup(String groupId) throws IOException;

  ListenableFuture<Operation> createMembership(String groupId, Membership member)
      throws IOException;

  ListenableFuture<Membership> getMembership(String memberId) throws IOException;

  ListenableFuture<Operation> deleteMembership(String memberId) throws IOException;

  Iterable<Group> listGroups(String groupNamespace) throws IOException;

  Iterable<Membership> listMembers(String groupId) throws IOException;
}

Mapping a third party user using UsersService

To map a user, use updateUserMapping(). This method allows you to associate a user identity from the identity repository to Google.

Mapping a third party group using GroupsService

To map a group from the identity repository to Google, use the methods from the GroupsService interface. If an associated Google group does not yet exist, use createGroup() to create the group, and createMembership() to add members to the group.

Using Identity Connector templates

The FullSyncIdentityConnector template works with the rest of the SDK to perform a full sync from the identity repository. By using this provided identity connector template, you can spend the majority of your development effort on the access functionality of your identity repository the Repository interface.

The following code snippet shows the methods that are implemented.

public class FullSyncIdentityConnector implements IdentityConnector {
  // From Connector
  @Override
  void init(ConnectorContext context) throws Exception;

  @Override
  void traverse() throws IOException, InterruptedException;

  @Override
  void destroy();
}

The following table shows which Repository interface methods are called when using this connector template.

Method Summary
Repository.init() Called once by FullSyncIdentityConnector.init() during initialization to enable the Repository to perform any set-up functions.
Repository.listUsers() Called to retrieve all users from the identity repository.
Repository.listGroups() Called to retrieve all groups from the identity repository.
Repository.close() Called once by FullSyncIdentityConnector.destroy() during connector shutdown to allow the Repository to perform any data repository cleanup functions.

Encapsulating all repository access functionality

If you use the Cloud Search Identity SDK traversal template to the full effect, the majority of your efforts are focused on accessing the specific identity repository. The Repository interface encapsulates all the specific repository access functionality that is required of the connector.

The following code snippet shows the Repository interface methods.

public interface Repository {
   void init(RepositoryContext context) throws IOException;

    CheckpointCloseableIterable<IdentityUser> listUsers(byte[] checkpoint) throws IOException;

    CheckpointCloseableIterable<IdentityGroup> listGroups(byte[] checkpoint) throws IOException;
     void close();
}

Send feedback about...

Cloud Search
Cloud Search