ICF 1.5.20.26

Google Apps connector

The Google Apps connector is bundled with IDM and Advanced Identity Cloud. A sample connector configuration is also included with IDM. The Google Apps connector lets you interact with Google’s web applications.

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

Google project requirements

Use of the Google Apps connector requires a properly configured Google project. The basic steps for configuring a Google project should be used as an outline, as the specific options, menus, and features may have changed.

  1. Log in to the Google Apps Developers Console and update your existing project or create a new project.

  2. Enable the following APIs for your project:

    Failure to enable the specified APIs results in the following depending on the Google Apps connector version:

    • For version 1.5.20.19 and earlier, connector requests hang indefinitely with no error message.

    • For version 1.5.20.20 and later, the connector logs an error.

  3. Set up an OAuth2 Client.

    The Google Apps connector uses OAuth2 to authorize the connection to the Google service:

    1. In the Google Apps Developers Console, select Credentials > Create Credentials > OAuth client ID.

    2. Click Configure Consent Screen, select Internal, and click Create.

    3. On the OAuth consent screen, enter an Application name; for example, RCS, and click Save.

      This name displays for all applications registered in this project.

    4. Select Credentials > Create Credentials > OAuth client ID > Web application, and enter information in the following fields:

      Authorized JavaScript origins

      The URI that clients use to access your application. The default URI is https://localhost:8443.

      The URI that you enter here must be the same you use to access RCS.
      Authorized redirect URIs

      The OAuth redirect URI, https://localhost:8443/admin/oauth.html by default.

    5. Click Create.

    6. On the OAuth client created pop-up, make a note of your Client ID and Client Secret.

  4. Add RCS to the Trusted Apps list:

    1. Log in to the Google Admin Console.

    2. From the top left menu, select Security > API Controls.

    3. Select MANAGE THIRD-PARTY APP ACCESS, click Change Access, and change the RCS app settings to Trusted.

Install the Google Apps connector

If you are looking for the Advanced Identity Cloud application for this connector, refer to:

You can download any connector from Backstage, but some are included in the default deployment for Advanced Identity Cloud, IDM, or RCS. When using an included connector, you can skip installing it and move directly to configuration.

Connector included in default deployment
Connector IDM RCS

Google Apps

Yes

No

Download the connector .jar file from Backstage.

  • If you are running the connector locally, place it in the /path/to/openidm/connectors directory, for example:

    mv ~/Downloads/googleapps-connector-1.5.20.26.jar /path/to/openidm/connectors/

  • If you are using a remote connector server (RCS), place it in the /path/to/openicf/connectors directory on the RCS.

Configure the Google Apps connector

Create a connector configuration using the IDM admin UI:

  1. From the navigation bar, click Configure > Connectors.

  2. On the Connectors page, click New Connector.

  3. On the New Connector page, type a Connector Name.

  4. From the Connector Type drop-down list, select Google Apps Connector - 1.5.20.26.

  5. Complete the Base Connector Details.

    For a list of all configuration properties, refer to Google Apps Connector Configuration

    A Sign in with Google page displays.

  6. Log in.

    After you log in, Google requests access for the project.

  7. Click Allow.

    If you click Deny, you must return to the Connector Configuration > Details tab in the admin UI, and save your changes again.

When your connector is configured correctly, the connector displays as Active in the admin UI.

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, to obtain an access token from Google. You can get 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 with IDM.

This excerpt shows a sample Google Apps connector configuration. The default location of the connector .jar file 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.5.0.0,1.6.0.0)"
},

The required configuration properties are as follows:

"configurationProperties": {
    "domain": "",
    "clientId": "",
    "clientSecret": null,
    "refreshToken": null
},
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, refer to 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, refer to the following section of RFC 6749: Refresh Tokens.

For a sample Google Apps configuration that includes OAuth 2-based entries for configurationProperties, refer to Synchronize accounts with the Google Apps connector.

Test the Google Apps connector

You can test the configuration is correct by running the following command:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/system/googleapps?_action=test"
{
  "name": "googleapps",
  "enabled": true,
  "config": "config/provisioner.openicf/googleapps",
  "connectorRef": {
    "bundleVersion": "[1.5.0.0,1.6.0.0)",
    "bundleName": "org.forgerock.openicf.connectors.googleapps-connector",
    "connectorName": "org.forgerock.openicf.connectors.googleapps.GoogleAppsConnector"
  },
  "displayName": "GoogleApps Connector",
  "objectTypes": [
    "Role",
    "OrgUnit",
    "LicenseAssignment",
    "__GROUP__",
    "__ALL__",
    "RoleAssignment",
    "Privilege",
    "__ACCOUNT__",
    "Member"
  ],
  "ok": true
}

If the command returns "ok": true, your connector was configured correctly, and can authenticate to the Google Cloud Platform system.

Google Apps remote connector

If you want to run this connector outside of PingOne Advanced Identity Cloud or IDM, you can configure the Google Apps connector as a remote connector. Java Connectors installed remotely on a Java Connector Server function identically to those bundled locally within PingOne Advanced Identity Cloud or installed locally on IDM.

You can download the Google Apps connector from here.

Refer to Remote connectors for configuring the Google Apps remote connector.

Use 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}

Role

role

{roleId}

RoleAssignment

roleassignment

{roleAssignmentId}

Privilege

privilege

Supported user attributes

The Google Apps connector supports the following user resource attributes:

Attribute Description

addresses

An array of addresses for the user account.

agreedToTerms

Whether the user has agreed to the Terms of Service.

aliases

An array of aliases for the user account.

archived

Whether the user account is archived.

changePasswordAtNextLogin

Whether the user must change their password at next login.

creationTime

The user creation time.

customerId

An ID used to identify the customer.

customSchemas

Define custom fields for user accounts.

deletionTime

The user deletion time.

emails

This attribute is managed using other attributes (primaryEmail, __SECONDARY_EMAILS__, aliases, nonEditableAliases).

etag

The ETag of the user account. Read-only attribute.

externalIds

An array of external IDs for the user account.

hashFunction

The hash function for the user’s password.

id

The unique ID for the user. id can be used as a user request URL’s userKey.

ims

An array of instant messenger accounts for the user.

includeInGlobalAddressList

Whether to include the user in the global address list.

ipWhitelisted

Whether the user’s IP is allowlisted.

isAdmin

Whether the user is an admin.

isDelegatedAdmin

Whether the user is a delegated administrator.

isEnforcedIn2Sv

Whether the user is enforcing two-step verification.

isEnrolledIn2Sv

Whether the user is enrolled in two-step verification.

isMailboxSetup

Whether the user’s mailbox is set up.

kind

The kind of user, typically admin#directory#user. Read-only attribute.

languages

An array of the user’s language preferences.

lastLoginTime

The last time the user logged in.

name

An object containing the fullName, givenName and familyName attributes.

nonEditableAliases

An array of non-editable aliases for the user account.

organizations

An array of organizations for the user account.

orgUnitPath

The full path of the parent organization associated with the user. If the parent organization is top-level, it is represented as a forward slash (/).

password

The user’s password.

phones

An array of phone numbers for the user account.

primaryEmail

The user’s primary email address.

recoveryEmail

The user’s recovery email address.

recoveryPhone

The user’s recovery phone number.

relations

An array of relations for the user account.

__SECONDARY_EMAIL__

(Deprecated)

Do not use this attribute.

As of version 1.5.20.21, __SECONDARY_EMAIL__ is deprecated. Use the newer attribute __SECONDARY_EMAILS__. These two attributes are mutually exclusive.

__SECONDARY_EMAILS__

An array of the user’s email addresses, excluding their primary email address and all editable and non-editable aliases.

suspended

Whether the user is suspended.

suspensionReason

The reason the user account is suspended.

thumbnailPhotoUrl

The url to a user’s thumbnail photo.

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, Contains1, StartsWith, Equals

name, email, givenName, familyName, orgUnitPath, im, externalId, address, addressPoBox, addressExtended, addressStreet, addressLocality, addressRegion, addressPostalCode, addressCountry, orgName, orgTitle, orgDepartment, orgDescription, orgCostCenter

__GROUP__

Contains1, Equals

customer (Equals only), userKey (Equals only), _MEMBERS_ (Contains only)

Member

And, Equals

groupKey, memberKey (And only)

OrgUnit

StartsWith

orgUnitPath

LicenseAssignment

N/A

Role

N/A

RoleAssignment

N/A

Privilege

N/A

1 "Contains" looks for a whole word match, in the given order. For example, an API request with _queryFilter=givenName+co+'Ana' matches users with givenName values of "Ana" and "Ana Lucia" but not "Anabelle". A multi-word query for _queryFilter=givenName+co+'Ana Lucia' would match values of "Ana Lucia Evans" and "Ana Lucia Ball" but not "Lucia Ana".

Product licenses

The Google Apps connector can query all available licenses and return details of individual product licenses.

Query all available product licenses 
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/system/googleapps/License?_queryFilter=true"
{
  "result": [
    {
      "_id": "Google-Apps/1010020027",
      "__NAME__": "Google Workspace Business Starter",
      "productId": "Google-Apps",
      "productName": "Google Workspace",
      "skuId": "1010020027",
      "skuName": "Google Workspace Business Starter"
    },
    {
      "_id": "Google-Drive-storage/Google-Drive-storage-20GB",
      "__NAME__": "Google-Drive-storage-20GB",
      "productId": "Google-Drive-storage",
      "productName": "Google-Drive-storage",
      "skuId": "Google-Drive-storage-20GB",
      "skuName": "Google-Drive-storage-20GB"
    }
  ],
  "resultCount": 2,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}
Read a product license

To read the details of a license, perform a GET request on the endpoint:

system/googleapps/License/{PRODUCT_ID}/{SKU_ID}
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/system/googleapps/License/Google-Drive-storage/Google-Drive-storage-20GB"
{
  "_id": "Google-Drive-storage/Google-Drive-storage-20GB",
  "__NAME__": "Google-Drive-storage-20GB",
  "productId": "Google-Drive-storage",
  "productName": "Google-Drive-storage",
  "skuId": "Google-Drive-storage-20GB",
  "skuName": "Google-Drive-storage-20GB"
}

OpenICF Interfaces Implemented by the GoogleApps Connector

The GoogleApps Connector implements the following OpenICF interfaces. For additional details, see ICF 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 Encrypted(1) Required(2)

domain

String

null

Yes

Internet domain name. See https://support.google.com/a/answer/177483?hl=en.

clientId

String

null

Yes

Client identifier issued to the client during the registration process.

clientSecret

GuardedString

null

Yes

Yes

Client secret issued to the client during the registration process.

refreshToken

GuardedString

null

Yes

Yes

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

Yes

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

proxyPort

int

8080

Yes

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

validateCertificate

boolean

true

Yes

Specifies whether the validation of the server certificate from the locally stored truststore is enabled. (defaults to true).

usersMaxResults

int

100

No

Maximum number of Users to return. Acceptable values are 1 to 500, inclusive.

groupsMaxResults

int

200

No

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

membersMaxResults

int

200

No

Maximum number of Members to return. Acceptable values are greater than 1.

listProductMaxResults

long

100

No

Maximum number of Licenses to return. Acceptable values are 1 to 1000, inclusive.

listProductAndSkuMaxResults

long

100

No

Maximum number of Licenses to return. Acceptable values are 1 to 1000, inclusive.

availableLicenses

String[]

['101005/1010050001', '101001/1010010001', '101031/1010310010', '101034/1010340002', '101038/1010380002', '101034/1010340001', '101038/1010380003', '101034/1010340004', '101034/1010340003', '101034/1010340006', 'Google-Apps/Google-Apps-For-Business', '101034/1010340005', 'Google-Vault/Google-Vault', 'Google-Apps/1010020031', 'Google-Apps/1010020030', 'Google-Apps/1010060003', 'Google-Apps/1010060005', 'Google-Apps/Google-Apps-Unlimited', 'Google-Apps/1010020029', 'Google-Apps/Google-Apps-Lite', '101031/1010310003', '101033/1010330002', '101033/1010330004', 'Google-Apps/Google-Apps-For-Education', '101031/1010310002', '101033/1010330003', 'Google-Apps/1010020026', '101031/1010310007', 'Google-Apps/1010020025', '101031/1010310008', 'Google-Apps/1010020028', 'Google-Apps/Google-Apps-For-Postini', '101031/1010310005', 'Google-Apps/1010020027', '101031/1010310006', '101031/1010310009', 'Google-Vault/Google-Vault-Former-Employee', '101038/1010370001', 'Google-Apps/1010020020', 'Google-Apps/1010060001']

No

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

No

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

roleAssignmentMaxResults

int

100

No

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

(1) Whether the property value is considered confidential, and is therefore encrypted in IDM.

(2) A list of operations in this column indicates that the property is required for those operations.