Synchronize accounts with the Google Apps connector

The Google Apps Connector lets you interact with Google’s web applications.

This sample shows how to create users and groups on an external Google system and how to synchronize those accounts with the IDM managed user repository. The sample requires a Google Apps account.

Prepare the sample

To set up IDM to connect to your Google Apps account, you must have a Google Apps project that authorizes consent for IDM.

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 lower, connector requests hang indefinitely with no error message.
For version 1.5.20.20 and higher, the connector logs an error.

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, IDM, 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 URI you use to access IDM. If you enter https://localhost:8443 here, but use http://localhost:8080 to access IDM, the sample will not work.
  
  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.
Add IDM 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 IDM app settings to Trusted.

Configure the Google Apps connector

This procedure uses the admin UI to configure the Google Apps connector.

Start IDM with the Google Apps sample configuration:

cd /path/to/openidm/
./startup.sh -p samples/sync-with-google
Executing ./startup.sh...
Using OPENIDM_HOME:   /path/to/openidm
Using PROJECT_HOME:   /path/to/openidm/samples/sync-with-google/
Using OPENIDM_OPTS:   -Xmx2048m -Xms2048m
Using LOGGING_CONFIG: -Djava.util.logging.config.file=/path/to/openidm/conf/logging.properties
Using boot properties at /path/to/openidm/resolver/boot.properties
-> OpenIDM ready

Log in to the admin UI at the URL https://localhost:8443/admin as the default administrative user (openidm-admin) with password openidm-admin.

This URL reflects the host on which IDM is installed, and must be the same as the Authorized JavaScript origin URI that you set in your Google app.
Select Configure > Connectors, and click the Google Apps connector.
On the Details tab, enable the connector.
In the Base Connector Details area, enter the Client ID and Client Secret that you obtained in the previous section.
Click Save.

IDM redirects you to a Sign in with Google page.
Log in.

After you log in, Google requests that you allow access from your project; in this case, IDM.
Click Allow.

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

After you allow access, you are redirected to the Connectors page in the admin UI, where the Google Apps Connector should now be Active.

Run the sample

This procedure uses create, read, update, and delete (CRUD) operations on the Google resource, to verify that the connector is working as expected. The procedure uses a combination of REST commands, to manage objects on the Google system, and the admin UI, to reconcile users from the Google system to the manage user repository.

The sample configuration has one mapping from the Google system to the managed user repository.

The commands shown here assume that your domain is example.com. Adjust the examples to match your domain.

Create a user entry on your Google resource, over REST.

When you create resources for Google, the equals (=) character cannot be used in any attribute value.

The following command creates an entry for user Sam Carter:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "__NAME__": "samcarter@example.com",
  "__PASSWORD__"  : "password",
  "givenName" : "Sam",
  "familyName": "Carter",
  "agreedToTerms": true,
  "changePasswordAtNextLogin" : false
}' \
"http://localhost:8080/openidm/system/google/__ACCOUNT__?_action=create"

Which returns:

{
  "_id": "103567435255251233551",
  "_rev": "\"iwpzoDgSq9BJw-XzORg0bILYPVc/LWHPMXXG8M0cjQAPITM95Y636cM\"",
  "orgUnitPath": "/",
  "isAdmin": false,
  "fullName": "Sam Carter",
  "customerId": "C02rsqddz",
  "relations": null,
  "nonEditableAliases": null,
  "suspensionReason": null,
  "includeInGlobalAddressList": true,
  "givenName": "Sam",
  "addresses": null,
  "isDelegatedAdmin": false,
  "changePasswordAtNextLogin": false,
  "isMailboxSetup": true,
  "__NAME__": "samcarter@example.com",
  "agreedToTerms": true,
  "externalIds": null,
  "ipWhitelisted": false,
  "aliases": null,
  "lastLoginTime": [
    "1970-01-01T00:00:00.000Z"
  ],
  "organizations": null,
  "suspended": false,
  "deletionTime": null,
  "familyName": "Carter",
  "ims": null,
  "creationTime": [
    "2016-02-02T12:52:30.000Z"
  ],
  "thumbnailPhotoUrl": null,
  "emails": [
    {
      "address": "samcarter@example.com",
      "primary": true
    }
  ],
  "phones": null
}

Note the _id of the new user (103567435255251233551 in this example). You will need this ID for the update commands in this section.

Reconcile the Google resource with the managed user repository.

This step should create the new user, Sam Carter (and any other users in your Google resource) in the managed user repository.
1. In the admin UI, select Configure > Mappings.
2. Click on the sourceGoogle__ACCOUNT___managedUser mapping, and click Reconcile.
3. Select Manage > User and verify that the user Sam Carter has been created in the repository.

Update Sam Carter’s phone number in your Google resource by sending a PUT request with the updated data, and specifying the user _id in the request:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PUT \
--header "If-Match: *" \
--data '{
  "__NAME__": "samcarter@example.com",
  "givenName" : "Sam",
  "familyName": "Carter",
  "agreedToTerms": true,
  "changePasswordAtNextLogin" : false,
  "phones" : [
    {
      "value": "1234567890",
      "type": "home"
    },
    {
      "value": "0987654321",
      "type": "work"
    }
  ]
}' \
"http://localhost:8080/openidm/system/google/__ACCOUNT__/103567435255251233551"
{
  "_id": "103567435255251233551",
  "_rev": "\"iwpzoDgSq9BJw-XzORg0bILYPVc/vfSJgHt-STUUto4lM_4ESO9izR4\"",
  ...
  "emails": [
    {
      "address": "samcarter@example.com",
      "primary": true
    }
  ],
  "phones": [
    {
      "value": "1234567890",
      "type": "home"
    },
    {
      "value": "0987654321",
      "type": "work"
    }
  ]
}

Read Sam Carter’s entry from your Google resource by including his _id in the URL:

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/google/__ACCOUNT__/103567435255251233551"
{
  "_id": "103567435255251233551",
  "__NAME__": "samcarter@example.com",
  ...
  "phones": [
    {
      "value": "1234567890",
      "type": "home"
    },
    {
      "value": "0987654321",
      "type": "work"
    }
  ]
}

Create a group entry on your Google resource:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "__NAME__": "testGroup@example.com",
  "__DESCRIPTION__": "Group used for google-connector sample.",
  "name": "TestGroup"
}' \
"http://localhost:8080/openidm/system/google/__GROUP__?_action=create"
{
  "_id": "00meukdy40gpg98",
  "_rev": "\"iwpzoDgSq9BJw-XzORg0bILYPVc/LLhHx2plMJPKeY1-h6eX_OVDi4c\"",
  "adminCreated": true,
  "__NAME__": "testgroup@example.com",
  "aliases": null,
  "nonEditableAliases": null,
  "__DESCRIPTION__": "Group used for google-connector sample.",
  "name": "TestGroup",
  "directMembersCount": 0
}

Add Sam Carter to the test group you have just created. Include the Member endpoint, and Sam Carter’s _id in the URL. Specify the _id of the group you created as the value of the groupKey in the JSON payload:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
-H 'If-Match: "iwpzoDgSq9BJw-XzORg0bILYPVc/LLhHx2plMJPKeY1-h6eX_OVDi4c"' \
--request PUT \
--data '{
  "__MEMBERS__": [
    {
      "role": "MEMBER",
      "email": "samcarter@example.com"
    }
  ]
}' \
"http://localhost:8080/openidm/system/google/__GROUP__/00meukdy40gpg98"
{
  "_id": "00meukdy40gpg98/samcarter@example.com",
  "_rev": "iwpzoDgSq9BJw-XzORg0bILYPVc/CPNpkRnowkGWRvNQvUK9ev6gQ90",
  "__NAME__": "00meukdy40gpg98/samcarter@example.com",
  "role": "MEMBER",
  "email": "samcarter@example.com",
  "type": "USER",
  "groupKey": "103567435255251233551"
}

Read the group entry by specifying the group _id in the request URL. Notice that the group has one member ("directMembersCount": 1):

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/google/__GROUP__/00meukdy40gpg98"
{
  "_id": "00meukdy40gpg98",
  "_rev": "iwpzoDgSq9BJw-XzORg0bILYPVc/chUdq5m5_cycV2G4sdl7ZKAF75A",
  "adminCreated": true,
  "__NAME__": "testgroup@example.com",
  "aliases": null,
  "nonEditableAliases": [
    "testGroup@example.test-google-a.com"
  ],
  "__DESCRIPTION__": "Group used for google-connector sample.",
  "name": "TestGroup",
  "directMembersCount": 1
}

Delete the group entry:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"http://localhost:8080/openidm/system/google/__GROUP__/00meukdy40gpg98"
{
  "_id": "00meukdy40gpg98",
  "_rev": "iwpzoDgSq9BJw-XzORg0bILYPVc/chUdq5m5_cycV2G4sdl7ZKAF75A",
  "adminCreated": true,
  "__NAME__": "testgroup@example.com",
  "aliases": null,
  "nonEditableAliases": [
    "testGroup@example.com.test-google-a.com"
  ],
  "__DESCRIPTION__": "Group used for google-connector sample.",
  "name": "TestGroup",
  "directMembersCount": 1
}

The delete request returns the complete group object.

Delete Sam Carter, to return your Google resource to its original state:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request DELETE \
"http://localhost:8080/openidm/system/google/__ACCOUNT__/103567435255251233551"
{
  "_id": "103567435255251233551",
  "_rev": "iwpzoDgSq9BJw-XzORg0bILYPVc/ah6xBLujMAHieSWSisPa1CV6T3Q",
  "orgUnitPath": "/",
  "isAdmin": false,
  "fullName": "Sam Carter",
  "customerId": "C02rsqddz",
  "relations": null,
  "nonEditableAliases": [
    "samcarter@example.com.test-google-a.com"
  ],
  "suspensionReason": null,
  "includeInGlobalAddressList": true,
  "givenName": "Sam",
  "addresses": null,
  "isDelegatedAdmin": false,
  "changePasswordAtNextLogin": false,
  "isMailboxSetup": true,
  "__NAME__": "samcarter@example.com",
  "agreedToTerms": true,
  "externalIds": null,
  "ipWhitelisted": false,
  "aliases": null,
  "lastLoginTime": [
    "1970-01-01T00:00:00.000Z"
  ],
  "organizations": null,
  "suspended": false,
  "deletionTime": null,
  "familyName": "Carter",
  "ims": null,
  "creationTime": [
    "2016-02-02T12:52:30.000Z"
  ],
  "thumbnailPhotoUrl": null,
  "emails": [
    {
      "address": "samcarter@example.com",
      "primary": true
    }
  ],
  "phones": [
    {
      "value": "1234567890",
      "type": "home"
    },
    {
      "value": "0987654321",
      "type": "work"
    }
  ]
}

In this sample, you used the Google Apps connector to add and delete user and group objects in your Google application and to reconcile users from your Google application to the managed user repository. You can expand on this sample by customizing the connector configuration to provide additional synchronization functionality between IDM and your Google applications. For more information on configuring connectors, refer to Google Apps connector.

PingIDM 7.5.0

Synchronize accounts with the Google Apps connector

Prepare the sample

Configure the Google Apps connector

Run the sample