Google Apps Connector

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

IDM bundles a Google Apps connector, along with a sample connector configuration. The Google Apps connector enables you to interact with Google's web applications.

The Google Apps connector is subject to the API Limits and Quotas that are imposed by Google. The connector also adheres to the implementation guidelines set out by Google for implementing exponential backoff.

Configuring the Google Apps Connector

The Google Apps connector uses OAuth2 to authorize the connection to the Google service. To use this authorization mechanism, you must supply a clientId and clientSecret in order to obtain an access token from Google. You can obtain the clientId and clientKey from the Google Developers Console after you have configured your Web Application.

A sample Google Apps connector configuration file is provided in samples/example-configurations/provisioners/provisioner.openicf-google.json

The following is an excerpt of the provisioner configuration file. This example shows an excerpt of the provisioner configuration. The default location of the connector .jar is openidm/connectors. Therefore the value of the connectorHostRef property must be "#LOCAL":

{
    "connectorHostRef": "#LOCAL",
    "connectorName": "org.forgerock.openicf.connectors.googleapps.GoogleAppsConnector",
    "bundleName": "org.forgerock.openicf.connectors.googleapps-connector",
    "bundleVersion": "[1.4.0.0,2.0.0.0)"
},

The following excerpt shows the required configuration properties:

"configurationProperties": {
    "domain": "",
    "clientId": "",
    "clientSecret": null,
    "refreshToken": null
},

These configuration properties are fairly straightforward:

domain: Set to the domain name for OAuth 2-based authorization.
clientId: A client identifier, as issued by the OAuth 2 authorization server. For more information, see the following section of RFC 6749: Client Identifier.
clientSecret: Sometimes also known as the client password. OAuth 2 authorization servers can support the use of clientId and clientSecret credentials, as noted in the following section of RFC 6749: Client Password.
refreshToken: A client can use an OAuth 2 refresh token to continue accessing resources. For more information, see the following section of RFC 6749: Refresh Tokens.

For a sample Google Apps configuration that includes OAuth 2-based entries for configurationProperties, see Synchronize Accounts With the Google Apps Connector.

OpenICF Interfaces Implemented by the GoogleApps Connector

The GoogleApps Connector implements the following OpenICF interfaces.

Create

Creates an object and its uid.

Delete

Deletes an object, referenced by its uid.

Schema

Describes the object types, operations, and options that the connector supports.

Script on Connector

Enables an application to run a script in the context of the connector. Any script that runs on the connector has the following characteristics:

The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
The script has access to a connector variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration.
The script has access to any script-arguments passed in by the application.

Search

Searches the target resource for all objects that match the specified object class and filter.

Test

Tests the connector configuration. Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.

This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).

You can invoke the test operation before a connector configuration has been validated.

Update

Updates (modifies or replaces) objects on a target resource.

GoogleApps Connector Configuration

The GoogleApps Connector has the following configurable properties.

Basic Configuration Properties

Property	Type	Default
`domain`	`String`	`null`
Internet domain name. See https://support.google.com/a/answer/177483?hl=en

`clientId`	`String`	`null`
Client identifier issued to the client during the registration process.

`clientSecret`	`GuardedString`	`null`
Client secret issued to the client during the registration process.

`refreshToken`	`GuardedString`	`null`
The refresh token allows you to get a new access token that is good for another hour. Refresh tokens never expire, they can only be revoked by the user or programatically by your app.

`proxyHost`	`String`	`null`
Defines an HTTP proxy host to use with the connection (example: "myproxy.home.com").

`proxyPort`	`int`	`8080`
Defines an HTTP proxy port to use with the connection (defaults to 8080).

`validateCertificate`	`boolean`	`true`
Validate the server certificate from the local truststore (defaults to true).

`usersMaxResults`	`int`	`100`
Maximum number of Users to return. Acceptable values are 1 to 500, inclusive.

`groupsMaxResults`	`int`	`200`
Maximum number of Groups to return. Acceptable values are 1 to 200, inclusive.

`membersMaxResults`	`int`	`200`
Maximum number of Members to return. Acceptable values are greater than 1

`listProductMaxResults`	`long`	`100`
Maximum number of Licenses to return. Acceptable values are 1 to 1000, inclusive.

`listProductAndSkuMaxResults`	`long`	`100`
Maximum number of Licenses to return. Acceptable values are 1 to 1000, inclusive.

`availableLicenses`	`String[]`	`[]`
All Google Licenses that will be queried when requesting licenses assigned to a user. The format of the license is ProductId/SkuId (e.g. Google-Apps/101002002)

`roleMaxResults`	`int`	`100`
Maximum number of Licenses to return. Acceptable values are 1 to 100, inclusive.

`roleAssignmentMaxResults`	`int`	`100`
Maximum number of Licenses to return. Acceptable values are 1 to 100, inclusive.

^[a] Indicates whether the property value is considered confidential, and therefore encrypted in OpenIDM. ^[b] A list of operations in this column indicates that the property is required for those operations.

Using the Google Apps Connector With a Proxy Server

If the IDM server is hosted behind a firewall and requests to the Google Apps server are routed through a proxy, you must specify the proxy host and port in the connector configuration so that the connector can pass this information to the lower Google API.

To specify the proxy server details, set the proxyHost, proxyPort and validateCertificate properties in the connector configuration. For example:

"configurationProperties": {
    ...
    "proxyHost": "myproxy.home.com",
    "proxyPort": 8080,
    "validateCertificate": true,
    ...
}

The validateCertificate property indicates whether the proxy server should validate the server certificate from the local truststore.

Supported Resource Types

The Google Apps connector uses the Google Enterprise License Manager and Directory APIs to perform CRUD operations against resources within a Google Apps domain.

The following table lists the resource types that are supported by the Google Apps connector:

Supported Resource Types With the Google Apps Connector

ICF Native Type	Google Resource Type	Naming Attribute
__ACCOUNT__	user	primaryEmail
__GROUP__	group	email
Member	member	{groupKey}/email
OrgUnit	orgUnit	{parentOrgUnitPath}/__NAME__
LicenseAssignment	licenseAssignment	{productId}/sku/{skuId}/user/{primaryEmail}

Functional Limitations

The Google Apps connector is subject to the following functional limitations:

In an UPDATE request, the old object (before the update) is returned in the request result. This behavior differs from that for other connectors, where the updated object is returned.
Although the update is processed correctly, there is a significant delay from Google, and IDM sends its GET request to return the object before the update has taken effect. This behavior has no impact on the success of the update.
The connector does not implement the ICF Sync operation so you cannot use the connector for liveSync of supported Google Apps resources to IDM managed objects.
The connector does not implement the Authenticate operation so you cannot use the connector to perform pass-through authentication between IDM and a Google Apps domain. You can also not use this connector to perform password Change operations (as opposed to password Reset) because the connector cannot authenticate on behalf of the end user.
Support for Filters when performing Search operations is limited to those attributes described in "Supported Search Filters".
Google Apps creates a new User Alias each time the primaryEmail address associated with the User object is modified. You cannot delete User Aliases with the Google Apps connector so you must manage Aliases directly from within the Google Apps console.
For PATCH requests, a connector can potentially add, remove, or replace an attribute value. The Google Apps connector does not implement the add or remove operations, so a PATCH request always replaces the entire attribute value with the new value.

Supported Search Filters

The Google Apps connector supports filtered searches against Google Apps resources. However, limitations imposed by the APIs provided by the Google Apps Admin SDK prevent filtering of resource types based on arbitrary attributes and values.

The following filter operators and attributes are supported for Search operations with the Google Apps connector:

Supported Operators and Filter Attributes With Google Apps Searches

Object Type	Operators	Attributes
__ACCOUNT__	And, Contains, StartsWith, Equals	primaryEmail
__GROUP__	Contains, Equals	email
Member	Equals	{groupKey}/email
OrgUnit	StartsWith	{parentOrgUnitPath}/__NAME__
LicenseAssignment	Equals	{productId}/sku/{skuId}/user/{primaryEmail}