Identity Connector SDK Overview

This guide is intended for Google Cloud Search connector developers. It provides an introduction to the Cloud Search Identity Connector SDK, including general concepts and specific programming objects and how they interact with each other. The guide assumes that you are familiar with software development concepts and Java programming.

For information about the tasks that the G Suite administrator must perform to set up the Cloud Search identity source and account creation, see Manage third-party identity sources. For information about specific steps to develop a connector using the SDK, see the Identity Connector SDK Guide.

Introduction

The function of an identity connector is to map your enterprise's identities with internal Google identities used by Google Cloud Search. Mapping user identities is done via the Directory API, while mapping Groups identities is done via the Cloud Identity API.

Although it is possible to write a connector application using just these APIs, this can be time consuming and cumbersome. To accelerate identity connector development, Google provides the Cloud Search Identity Connector SDK (alongside the Cloud Search Content Connector SDK), which implements common connector tasks supporting the following functionalities:

  • Cloud Identity API authentication
  • Error handling and retry
  • Rate limiting of Cloud Identity API requests
  • Request validations
  • Request batching
  • Client side statistics of Cloud Identity API requests
  • Trace log for each Cloud Identity API request and response

Identity connectors address syncing of external identities from the identity source in the following scenarios:

  • Local Identities: When the identity source is a part of the content repository. For e.g., indexing Box's content into Google Cloud Search would require syncing both Box’s contents and identities, in order to properly interpret permissions applied on each item.
  • External Identities: When the identity source is external to the content repository. For example, indexing Windows FileShare data into Google Cloud Search would require syncing Windows File Share contents and Active Directory identities.
  • Mixed Identities: Content requiring a combination of both local and external identities. For example, indexing SharePoint data into Google Cloud Search would require syncing SharePoint contents, SharePoint Local Groups and Active Directory identities

A typical process for developing a connector involves using three major SDK classes of objects:

This document gives you an overview of each class of object. For additional information, including the syntax specific to each object, see the Cloud Search Identity Connector SDK Reference and associated Javadocs.

Primary objects

You can understand the SDK framework by first studying a few important classes that are grouped together as primary objects. These objects interact with each other to execute your identity connector code. Everything else in the SDK is built on top of these objects. By understanding their functions and relationship to each other, you will be able to begin basic identity connector development.

The following diagram presents the core objects that you should understand before working with the SDK.

drawing

  1. IdentityConnector.main() calls IdentityApplication.build() passing the command line "args" which typically contains the configuration file path.
  2. IdentityApplication.start() calls Configuration.initConfig() to read the configuration file, creates an IdentityService instance and creates an IdentityConnectorContext instance infused with the IdentityService instance.
  3. IdentityApplication calls IdentityConnector.init(). At this step the configuration has been initialized and the indexing service has been setup.

The following table summarizes the primary objects.

Class/Interface Summary
Identity Connector interface Performs all identity repository access and controls how identities are synced to Google.
IdentityApplication class Builds and manages internal instances, as shown in the diagram. Configuration class
IdentityService interface Manages the syncing of third party identities.IdentityConnectorContext interface

IdentityConnector interface

The interface that you, as the developer, should first focus on is the IdentityConnector. This is the foundation of the identity connector execution and primary access point of the SDK.

The program main() begins connector execution by accessing the SDK with the IdentityApplication object. During initialization, the SDK calls the connector's init() method to allow the connector to perform any connector specific pre-traversal initializations.

After initialization, the identity connector receives scheduled Connector.traverse() calls from the SDK where the connector is required to perform identity repository access and retrieval.

IdentityApplication class

The SDK's point of entry for the connector developer is the IdentityApplication object. Your connector program's main() typically builds an instance of this object by passing in a IdentityConnector instance as an argument.

The execution begins when your connector's main() calls the IdentityApplication.start() method. At this point, your connector gives execution control over to the SDK, which begins initialization by:

  1. Reading the configuration file.
  2. Creating an IdentityService object.
  3. Calling the IdentityConnector.init() method.
  4. Scheduling traversals.

Configuration class

The administrator for your connector can define your connector's behavior by creating a configuration file. The configuration file consists of parameters defined by key/value pairs. After initialization, your connector code can access these parameters by using getters from this static object.

There are standardized parameters that the SDK uses for all connectors including parameters for identifying the data source and scheduling traversals. You can also define connector-specific parameters that only your connector uses. For example, a database connector would have parameters that define the database URL and parameters for a valid user and password needed to access the repository.

IdentityService interface

The SDK creates an IdentityService instance during initialization that the connector uses to perform the actual API calls to interact Directory API and Cloud Identity API. All the methods for user and group management are contained within this object.

The IdentityService object is passed to the connector during the IdentityConnector.init() method call. Your IdentityConnector should save this instance for use later when your connector's traversal methods are called by the SDK.

IdentityConnectorContext interface

A IdentityConnectorContext object is passed to the IdentityConnector from the IdentityApplication in the IdentityConnector.init() method.

The IdentityConnector uses this instance to retrieve the SDK-created IdentityService object for use during identity traversals.

Template objects

The next set of SDK classes are grouped together as template objects. These objects are intended to reduce your connector code development to just accessing your identity source repository. The template objects interact closely with the primary objects, therefore a basic understanding of the primary objects is necessary. Though optional, template objects are recommended to be your default starting point for writing connector code.

The following diagram presents both the template objects and the primary SDK objects. As you can see, by using one of the existing SDK connector templates, your implementation of just the Repository class contains the majority of the code that you are required to write.

drawing

  1. Your connector's main() method uses the FullSyncIdentityConnector template, infuses its repository, and calls IdentityApplication.start().
  2. The IdentityApplication instance reads configuration file, calls repository initialization methods.
  3. The IdentityApplication calls the FullSyncIdentityConnector.traverse()
  4. The FullSyncIdentityConnector template calls Repository methods to fetch the identity data (users and groups).
  5. The FullSyncIdentityConnector template sends the identity users and groups to identity service which converts to API calls.

Though optional, Google recommends most identity connector developers use these SDK extension template objects where applicable to accelerate development.

The following table summarizes the template objects.

Class/Interface Summary
FullSyncIdentityConnector class Performs periodic syncs of all users and groups between third party identity repositories and Google.
Repository interface Provides all of the access functionality to your identity repository.

FullSyncIdentityConnector class

The FullSyncIdentityConnector object implements the IdentityConnector interface.

The following table provides an overview of these implementations.

Interface Method Calls
Connector Connector.init() Repository.init() method for initialization.
Connector.traverse() Repository.listUsers() and Repository.listGroups. Methods to list all users and groups from the identity repository.

Repository interface

When using the full range of template objects described in this guide, the only significant coding required of the connector developer is in the implementation of the Repository class.

The purpose of the Repository object is to perform the access and retrieval of identity data from the repository. Each of the methods return an CheckpointCloseableIterable of IdentityUser and IdentityGroup.

RepositoryContext

RepositoryContext is used to initialize the Repository object. The RepositoryContext loads identity repository information from IdentitySourceConfiguration and provides IdentityUser and IdentityGroup objects that adhere to schemas and namespaces configured for this identity source.

IdentityUser

IdentityUser is the principal object that represents the mapped user principal of a third party identity repository with Google.

The following table provides an overview of this class.

Method Description
sync() Sets the mapping information between a user principal from the identity repository with a Google identity
unmap() Removes the mapping information between a user principal from the identity repository with a Google user identity.

IdentityGroup

IdentityGroup is the group principal object that represents the mapped group principal of a third party identity repository with a Cloud Identity Groups.

The following table provides an overview of this class.

Method Description
sync() Sets the mapping and memberships between a group from the identity repository with a Google Groups. If a Cloud Identity Group does not exist, this method will create a new Cloud Identity Group for association.
unmap() Removes the mapping and memberships between a group from the identity repository with a Cloud Identity Group by deleting group.

Helper objects

Helper objects assist with identity connector development by performing specific common tasks. Google recommends using these classes wherever appropriate to save development time, even if you do not use the template objects.

The following table summarizes the helper objects.

Class/Interface Summary
UsersService class Helps manage user identity mapping between an identity source and Google.
GroupsService Helps manage group mapping between an identity source and Google.

UsersService

The UsersServiceImpl class exposes methods to help create, manage, and retrieve identity mapping between an identity source and Google.

Method Description
getUserMapping() Retrieves a `User` based on the specified userId.
updateUserMapping() Updates the user mapped attributes for a user principal from the identity repository with a Google identity
listUsers() Returns an iterator of `User`s that match the specified schema name.

GroupsService

The GroupsServiceImpl class exposes methods to help create, manage, and retrieve memberships and groups mapping between an identity source and Google.

Method Description
createGroup() Creates a Cloud Identity Group.
deleteGroup() Deletes a Cloud Identity Group based on the specified group id.
createMembership() Creates a membership for a member with the specified group id.
getMembership() Retrieves the `Membership` for the specified member id.
deleteMembership() Removes the membership of the specified member id from its associated group.
listGroups() Retrieves an iterator of Groups that corresponds to the specified namespace
listMembers() Retrieves an iterator of `Membership`s for the specified group id.

Send feedback about...

Cloud Search
Cloud Search