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.
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.
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.
IdentityApplication.build()passing the command line "args" which typically contains the configuration file path.
Configuration.initConfig()to read the configuration file, creates an
IdentityServiceinstance and creates an
IdentityConnectorContextinstance infused with the
IdentityConnector.init(). At this step the configuration has been initialized and the indexing service has been setup.
The following table summarizes the primary objects.
|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|
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.
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.
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:
- Reading the configuration file.
- Creating an
- Calling the
- Scheduling traversals.
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.
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.
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.
IdentityConnector uses this instance to retrieve the SDK-created
IdentityService object for use during identity
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.
- Your connector's
main()method uses the FullSyncIdentityConnector template, infuses its repository, and calls
IdentityApplicationinstance reads configuration file, calls repository initialization methods.
Repositorymethods to fetch the identity data (users and groups).
FullSyncIdentityConnectortemplate 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.
||Performs periodic syncs of all users and groups between third party identity repositories and Google.|
||Provides all of the access functionality to your identity repository.|
FullSyncIdentityConnector object implements the
The following table provides an overview of these implementations.
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
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
IdentityUser and IdentityGroup.
RepositoryContext is used to initialize the
Repository object. The
RepositoryContext loads identity repository information from
IdentitySourceConfiguration and provides
objects that adhere to schemas and namespaces configured for this identity
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.
||Sets the mapping information between a user principal from the identity repository with a Google identity|
||Removes the mapping information between a user principal from the identity repository with a Google user identity.|
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.
||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.|
||Removes the mapping and memberships between a group from the identity repository with a Cloud Identity Group by deleting group.|
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.
||Helps manage user identity mapping between an identity source and Google.|
||Helps manage group mapping between an identity source and Google.|
UsersServiceImpl class exposes methods to help create, manage, and
retrieve identity mapping between an identity source and Google.
||Retrieves a `User` based on the specified userId.|
||Updates the user mapped attributes for a user principal from the identity repository with a Google identity|
||Returns an iterator of `User`s that match the specified schema name.|
GroupsServiceImpl class exposes methods to help create, manage, and
retrieve memberships and groups mapping between an identity source and Google.
||Creates a Cloud Identity Group.|
||Deletes a Cloud Identity Group based on the specified group id.|
||Creates a membership for a member with the specified group id.|
||Retrieves the `Membership` for the specified member id.|
||Removes the membership of the specified member id from its associated group.|
||Retrieves an iterator of Groups that corresponds to the specified namespace|
||Retrieves an iterator of `Membership`s for the specified group id.|