Cross Reference: /forgerock/openidm-v4/openidm-zip/src/main/resources/samples/google-connector/

README/**
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 2014 ForgeRock AS. All rights reserved.
 *
 * The contents of this file are subject to the terms
 * of the Common Development and Distribution License
 * (the License). You may not use this file except in
 * compliance with the License.
 *
 * You can obtain a copy of the License at
 * http://forgerock.org/license/CDDLv1.0.html
 * See the License for the specific language governing
 * permission and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL
 * Header Notice in each file and include the License file
 * at http://forgerock.org/license/CDDLv1.0.html
 * If applicable, add the following below the CDDL Header,
 * with the fields enclosed by brackets [] replaced by
 * your own identifying information:
 * "Portions Copyrighted [year] [name of copyright owner]"
 */

 -------------------------------------------------------------------------------------------------
                                    GoogleApps Connector Sample
 -------------------------------------------------------------------------------------------------

 This sample will provide an example of creating a user and group. It will show how to add a user
 to the group that you have created. The design of this sample is to demonstrate that the googleapps
 connector can be used within OpenIDM. In addition, it will explain getting a refresh token from
 google. You can use the sample configuration to get you started on your own set of implementation
 requirements.

 -------------------------------------------------------------------------------------------------
                                Getting a Refresh Token From Google
 -------------------------------------------------------------------------------------------------

 Before we begin to use the googleapps-connector, we will need to obtain a refresh token from google.
 You will need a google apps account so that you can obtain a client_secret.json file which will have
 the refresh token the googleapps-connector will use. For this sample we will demonstrate one way to
 get a refresh token.

 1) Verify in your google admin console that both of the following APIs are enabled
    a. Admin SDK API
    b. Enterprise License Manager API

 2) Acquire a client_secrets.json file. For this sample, we are going to use the OAuth 2.0
 Installed Application flow. You can reference the link below for more information.

    https://developers.google.com/maps-engine/documentation/oauth/installedapplication

 3) Download the google-api-services-admin-directory-rev41-java-1.19.0.zip

  a) Unzip google-api-services-admin-directory-rev41-java-1.19.0.zip
    $ unzip google-api-services-admin-directory-rev41-java-1.19.0.zip
  b) Copy the googleapps-connector-1.4.0.0.jar to the admin dir
    $ cp googleapps-connector-1.4.0.0.jar admin/
  c) cd into admin and execute the following command
    $ cd admin/
    $ java -jar googleapps-connector-1.4.0.0-SNAPSHOT.jar /path/to/client_secrets.json

    It will generate this:
    $ java -jar googleapps-connector-1.4.0.0-SNAPSHOT.jar client_secrets.json
    Please open the following address in your browser:
      https://accounts.google.com/o/oauth2/auth?
        access_type=offline
        &approval_prompt=force
        &client_id=YOUR_CLIENT_ID
        &redirect_uri=urn:ietf:wg:oauth:2.0:oob
        &response_type=code
        &scope=https://www.googleapis.com/auth/admin.directory.group%20
        https://www.googleapis.com/auth/admin.directory.orgunit%20
        https://www.googleapis.com/auth/admin.directory.user%20
        https://www.googleapis.com/auth/apps.licensing

        Attempting to open that address in the default browser now...
        Please enter code:

    d) This will open up a browser, where you will have to accept consent. Once you accept consent you
     will be given a code that you need to paste back in the terminal where you ran that command
     from. This will result in a response that has the following:

        {
          "clientId" : "example-client-Id.apps.googleusercontent.com",
          "clientSecret" : "generated-sample-token",
          "refreshToken" : "generated-refresh-token"
        }

 ------------------------------------------------------------------------------------------------------
                                Running the GoogleApps Connector Sample
 ------------------------------------------------------------------------------------------------------

 Before we start the sample, we have to set the domain, clientId, clientSecret, and refreshToken in our
 provisioner.openicf-google.json.

 1) Edit openidm/samples/google-connector/conf/provisioner.openicf-google.json
    ...
    "configurationProperties": {
        "domain": "YOUR_DOMAIN",
        "clientId": "YOUR_CLIENT_ID",
        "clientSecret": "YOUR_CLIENT_SECRET",
        "refreshToken": "YOUR_CLIENT_REFRESH_TOKEN"
    },
    ...

    Once those properties are set, the connector needs to be enabled by switching the following property
    from "false" to "true" :

    ...
    "name": "google",
    "enabled": true,
    ...


 2) To run the sample, start OpenIDM with the configuration for google-connector:
    $ cd /path/to/openidm
    $ ./startup.sh -p samples/google-connector

 3) For reassurance, lets go ahead and get the status of the google connector.

    $ curl  --header "X-OpenIDM-Username: openidm-admin"
            --header "X-OpenIDM-Password: openidm-admin"
            --header "Content-Type: application/json"
            --request POST
            "http://localhost:8080/openidm/system/google?_action=test"

    Response should be:
    {
        "name":"google",
        "enabled":true,
        "config":"config/provisioner.openicf/google",
        "connectorRef":
        {
            "connectorName":"org.forgerock.openicf.connectors.googleapps.GoogleAppsConnector",
            "bundleName":"org.forgerock.openicf.connectors.googleapps-connector",
            "bundleVersion":"1.4.0.0-SNAPSHOT"
        },
        "ok":true
    }

 At this point, we should have a googleApps connector ready to do some REST requests!

 ------------------------------------------------------------------------------------------------------
                            CREATE,READ, UPDATE, DELETE, and QUERY Requests
 ------------------------------------------------------------------------------------------------------

 1) Create a user:
    Request:
        $ curl  --header "X-OpenIDM-Username: openidm-admin"
                --header "X-OpenIDM-Password: openidm-admin"
                --header "Content-Type: application/json"
                --request POST "http://localhost:8080/openidm/system/google/__ACCOUNT__?_action=create"
                --data
                "{
                  "__NAME__": "samcarter@yourdomain.com",
                  "__PASSWORD__"  : "password",
                  "givenName" : "Sam",
                  "familyName": "Carter",
                  "agreedToTerms": true,
                  "changePasswordAtNextLogin" : false
                }"
    Response:
        {
            "phones":null,
            "givenName":"Sam",
            "familyName":"Carter",
            "thumbnailPhotoUrl":null,
            "addresses":null,
            "__NAME__":"samcarter@yourdomain.com",
            "changePasswordAtNextLogin":false,
            "suspensionReason":null,
            "aliases":null,
            "customerId":"Cwev45or",
            "isDelegatedAdmin":false,
            "lastLoginTime":["1970-01-01T00:00:00.000Z"],
            "agreedToTerms":true,
            "deletionTime":null,
            "isAdmin":false,
            "creationTime":["2014-09-23T18:54:19.000Z"],
            "ims":null,
            "organizations":null,
            "ipWhitelisted":false,
            "fullName":"Sam Carter",
            "includeInGlobalAddressList":true,
            "isMailboxSetup":false,
            "externalIds":null,
            "suspended":false,
            "nonEditableAliases":null,
            "orgUnitPath":"/",
            "relations":null,
            "emails":
                [
                    {
                        "address":"samcarter@yourdomain.com",
                        "primary":true
                    }
                ],
            "_id":"101643010677712061243",
            "_rev":"\"SHoRIPAZisvsSqsLJr3m3XS9Uw4/RfZOwrjqrpRsO6PCGNfEp2H00Ds\""
        }

 Note the complex data structure for the "emails" attribute. Google uses complex data structure for some attributes
 like email, addresses, phone numbers, etc., which will also appear in some of the queries and result sets below.


 2) Lets go ahead and UPDATE the User before we READ, using the _id from step 1.
    Request:
        $ curl  --header "X-OpenIDM-Username: openidm-admin"
                --header "X-OpenIDM-Password: openidm-admin"
                --header "Content-Type: application/json"
                --request PUT "http://localhost:8080/openidm/system/google/__ACCOUNT__/101643010677712061243"
                --data
                '{
                  "__NAME__": "samcarter@yourdomain.com",
                  "__PASSWORD__"  : "password",
                  "givenName" : "Sam",
                  "familyName": "Carter",
                  "agreedToTerms": true,
                  "changePasswordAtNextLogin" : false
                  "phones" :
                    [
                        {
                            "value": "1234567890",
                            "type": "home"
                        },
                        {
                            "value": "0987654321",
                            "type":"work"
                        }
                    ]
                }'
    Response:
        You should have received the object that was updated with the new phone numbers. We will
        verify this in Step 3, where we will make a read on that particular ID.

 3) READ the user created in Step 2.
    Request:
        $ curl  --header "X-OpenIDM-Username: openidm-admin"
                --header "X-OpenIDM-Password: openidm-admin"
                --header "Content-Type: application/json"
                --header "If-None-Match" : "*"
                --request GET "http://localhost:8080/openidm/system/google/__ACCOUNT__/101643010677712061243"

    Response:
        {
            "phones":
                [
                    {"value":"1234567890","type":"home"},
                    {"value":"0987654321","type":"work"}
                ],
            "givenName":"Sam",
            "familyName":"Carter",
            "thumbnailPhotoUrl":null,
            "addresses":null,
            "__NAME__":"samcarter@yourdomain.com",
            "changePasswordAtNextLogin":false,
            "suspensionReason":null,
            "aliases":null,
            "customerId":"Cwev45or",
            "isDelegatedAdmin":false,
            "lastLoginTime":["1970-01-01T00:00:00.000Z"],
            "agreedToTerms":true,
            "deletionTime":null,
            "isAdmin":false,
            "creationTime":["2014-09-23T18:54:19.000Z"],
            "ims":null,
            "organizations":null,
            "ipWhitelisted":false,
            "fullName":"Sam Carter",
            "includeInGlobalAddressList":true,
            "isMailboxSetup":false,
            "externalIds":null,
            "suspended":false,
            "nonEditableAliases":null,
            "orgUnitPath":"/",
            "relations":null,
            "emails":
                [
                    {
                        "address":"samcarter@yourdomain.com",
                        "primary":true
                    }
                ],
            "_id":"101643010677712061243",
            "_rev":"\"SHoRIPAZisvsSqsLJr3m3XS9Uw4/RfZOwrjqrpRsO6PCGNfEp2H00Ds\""
        }

 Note again the complex data structure for "emails" and "phones".

 4) Lets CREATE a group that we can stick the user we created above in.
    Request:
        $ curl  --header "X-OpenIDM-Username: openidm-admin"
                --header "X-OpenIDM-Password: openidm-admin"
                --header "Content-Type: application/json"
                --request POST "http://localhost:8080/openidm/system/google/__GROUP__?_action=create"
                --data
                '{
                   "__NAME__": "googleAppsTestGroup@yourdomain.com",
                   "__DESCRIPTION__": "Group used for google-connector sample.",
                   "name": "TestGroup"
                 }'
    Response:
        {
            "__DESCRIPTION__": "Group used for google-connector sample.",
            "directMembersCount": 0,
            "nonEditableAliases": null,
            "aliases": null,
            "adminCreated": true,
            "name": "TestGroup",
            "__NAME__": "googleappstestgroup@yourdomain.com",
            "_id": "03oy7u291s3qw1i",
            "_rev": "\"SHoRIPAZisvsSqsLJr3m3XS9Uw4/8JZsrHGxtdaH4sF8vgzLiPmPqFs\""
        }

 5) Adding the user samcarter@yourdomain.com to the TestGroup we created above.
     You will need the _id created in step 1 to pass in as part of the request URL, 101643010677712061243.
    Request:
        $ curl  --header "X-OpenIDM-Username: openidm-admin"
                --header "X-OpenIDM-Password: openidm-admin"
                --header "Content-Type: application/json"
                --request PUT "http://localhost:8080/openidm/system/google/Member/101643010677712061243"
                --data
                '{
                  "groupKey" : "03oy7u291s3qw1i",
                  "role": "MEMBER",
                  "__NAME__": "samcarter@yourdomain.com",
                  "email": "samcarter@yourdomain.com",
                  "type": "MEMBER"
                }'
    Response:
        {
            "role": "MEMBER",
            "type": "USER",
            "email": "samcarter@yourdomain.com",
            "__NAME__": "03oy7u291s3qw1i/samcarter@yourdomain.com",
            "groupKey": "109384837631312225274",
            "_id": "014ykbeg40r6x06/samcarter@yourdomain.com",
            "_rev": "\"SHoRIPAZisvsSqsLJr3m3XS9Uw4/GiZLiMKb3U62M58IabSzPKAVIOE\""
        }

 6) READ the group information now that we have added the user to the group.
    Request:
        $ curl  --header "X-OpenIDM-Username: openidm-admin"
                --header "X-OpenIDM-Password: openidm-admin"
                --header "Content-Type: application/json"
                --request GET "http://localhost:8080/openidm/system/google/__GROUP__/03oy7u291s3qw1i"
    Response:
        {
          "__DESCRIPTION__": "Group used for google-connector sample.",
          "directMembersCount": 1,
          "nonEditableAliases": [
              "googleAppsTestGroup@yourdomain.com.test-google-a.com"
          ],
          "aliases": null,
          "adminCreated": true,
          "name": "TestGroup",
          "__NAME__": "googleappstestgroup@yourdomain.com",
          "_id": "03oy7u291s3qw1i",
          "_rev": "\"SHoRIPAZisvsSqsLJr3m3XS9Uw4/WcZC54etzuPtruE7uByf9NQ82Ow\""
        }

 7) DELETE the group we created earlier.
    Request:
        $ curl  --header "X-OpenIDM-Username: openidm-admin"
                --header "X-OpenIDM-Password: openidm-admin"
                --header "Content-Type: application/json"
                --request DELETE "http://localhost:8080/openidm/system/google/__GROUP__/03oy7u291s3qw1i"
    Response:
        {
            "_id": "03oy7u291s3qw1i"
        }

 8) Delete the user created in this sample
    Request:
        $ curl  --header "X-OpenIDM-Username: openidm-admin"
                --header "X-OpenIDM-Password: openidm-admin"
                --header "Content-Type: application/json"
                --request DELETE "http://localhost:8080/openidm/system/google/__ACCOUNT__/101643010677712061243"
    Response:
       {
           "_id":"101643010677712061243"
       }

 ------------------------------------------------------------------------------------------------------
                            Reconciling Google Users to Managed Users
 ------------------------------------------------------------------------------------------------------

 A sync.json is included with this sample which maps some user attributes from Google to Managed User entries.
 To trigger a reconciliation with this mapping, simply issue the following command

    Request :
        $ curl  --header "X-OpenIDM-Username: openidm-admin"
                --header "X-OpenIDM-Password: openidm-admin"
                --header "Content-Type: application/json"
                --request POST "http://localhost:8080/openidm/recon?_action=recon&mapping=sourceGoogle__ACCOUNT___managedUser"

    Response :
        {"_id":"efefd951-9153-46f6-9446-894805d85173","state":"ACTIVE"}

  A quick look at the reconciliation entry will tell us what happened during the reconciliation process :

    Request :
        $ curl  --header "X-OpenIDM-Username: openidm-admin"
                --header "X-OpenIDM-Password: openidm-admin"
                --header "Content-Type: application/json"
                --request GET "http://localhost:8080/openidm/recon/efefd951-9153-46f6-9446-894805d85173"


    Response :

        {
          "_id" : "efefd951-9153-46f6-9446-894805d85173",
          "mapping" : "sourceGoogle__ACCOUNT___managedUser",
          "state" : "SUCCESS",
          "stage" : "COMPLETED_SUCCESS",
          "stageDescription" : "reconciliation completed.",
          "progress" : {
            "source" : {
              "existing" : {
                "processed" : 9,
                "total" : "9"
              }
            },
            "target" : {
              "existing" : {
                "processed" : 8,
                "total" : "8"
              },
              "created" : 0
            },
            "links" : {
              "existing" : {
                "processed" : 8,
                "total" : "8"
              },
              "created" : 0
            }
          },
          "situationSummary" : {
            "SOURCE_IGNORED" : 1,
            "MISSING" : 0,
            "FOUND" : 0,
            "AMBIGUOUS" : 0,
            "UNQUALIFIED" : 0,
            "CONFIRMED" : 8,
            "SOURCE_MISSING" : 0,
            "ABSENT" : 0,
            "TARGET_IGNORED" : 0,
            "UNASSIGNED" : 0,
            "FOUND_ALREADY_LINKED" : 0
          },
          "statusSummary" : {
            "FAILURE" : 0,
            "SUCCESS" : 9
          },
          "parameters" : {
            "object" : {
              "sourceQuery" : {
                "resourceName" : "system/google/__ACCOUNT__",
                "_queryId" : "query-all-ids"
              },
              "targetQuery" : {
                "resourceName" : "managed/user",
                "_queryId" : "query-all-ids"
              }
            },
            "pointer" : {
              "empty" : true
            },
            "transformers" : [ ],
            "set" : false,
            "collection" : false,
            "map" : true,
            "string" : false,
            "wrappedObject" : {
              "sourceQuery" : {
                "resourceName" : "system/google/__ACCOUNT__",
                "_queryId" : "query-all-ids"
              },
              "targetQuery" : {
                "_queryId" : "query-all-ids",
                "resourceName" : "managed/user"
              }
            },
            "list" : false,
            "number" : false,
            "boolean" : false,
            "null" : false
          },
          "started" : "2014-10-31T14:16:34.721Z",
          "ended" : "2014-10-31T14:16:35.509Z",
          "duration" : 788
        }
Name	Date	Size
..	2015-12-09 23:39:20	41
conf	2015-12-09 23:39:20	3
README	2014-11-03 16:24:12	19.3 KiB