/*
 * Copyright 2014-2017 ForgeRock AS. All Rights Reserved
 *
 * Use of this code requires a commercial software license with ForgeRock AS.
 * or with one of its affiliates. All use shall be exclusively subject
 * to such license between the licensee and ForgeRock AS.
 */

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

 This sample demonstrates the creation of users and groups on an external Google system, using
 OpenIDM's REST interface. The sample requires that you have a Google Apps account. Obtaining a
 Google Apps account is described in the Google documentation at
 https://support.google.com/a/answer/53926?hl=en.

 -------------------------------------------------------------------------------------------------
                                          Before You Start
 -------------------------------------------------------------------------------------------------

  To set up OpenIDM to connect to your Google Apps account, you must have a Google Apps project (or
  create a new project) that authorizes consent for OpenIDM.

  1. Log in to the Google Apps Developers Console (at https://console.developers.google.com/start)
     and update your project or create a new project for OpenIDM.

  2. Enable the following APIs for your OpenIDM project:
     - Admin SDK API
     - Enterprise License Manager API

  3. Set up an OAuth2 Client ID.

     The Google Apps connector uses OAuth2 to authorize the connection to the Google service. Set up
     an OAuth2 Client ID as follows:

     - In the Google Apps Developers Console, select Credentials > New Credentials > OAuth Client ID.
     - Click Configure Consent Screen and enter a Product Name.
       This is the name that will be shown for all applications registered in this project.
       For the purposes of this example, we use the Product Name OpenIDM.
       Click Save.
     - Select Credentials > OAuth Client ID > Web application.
       Under Authorized redirect URIs, enter the callback URL (the URL at which your clients will
       access your application). The default OpenIDM callback URL is
       https://localhost:8443/admin/oauth.html. Click Create to set up the callback URL.
       Click Create again to set up the client ID.
     - This step generates an OAuth Client ID and Client. Copy and paste these values into a text file
       as you will need them when you configure the Google Apps connector.

  -------------------------------------------------------------------------------------------------
                                   Configuring the Google Apps Connector
  -------------------------------------------------------------------------------------------------

  This procedure uses the OpenIDM Admin UI to set up the Google Apps connector.

  1. To configure the connector, start OpenIDM with the Google Apps sample configuration:

     $ cd /path/to/openidm
     $ ./startup.sh -p samples/google-connector

  2. 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 OpenIDM is installed and corresponds to the callback URL that
     you specified in the previous section. The URL must be included in the list of Authorized redirect
     URIs for your project.

  3. Select Configure > Connectors and click on the Google Apps connector.

  4. On the Details tab, set the Enabled field to True.

  5. Enter the Oauth2 Client ID and Client Secret that you obtained in the previous section.

  6. Click Save Connector Changes.
  
  7. You are redirected to Google's Login page.

     When you have logged in, Google requests that you allow access from your project, in this case,
     OpenIDM. Click Allow.

     If you click Deny here, you will need to return to the Connector Configuration > Details tab in
     the Admin UI and save your changes again.

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

  -------------------------------------------------------------------------------------------------
                                     Running the Google Apps Sample
  -------------------------------------------------------------------------------------------------

  This procedure uses create, read, update, and delete (CRUD) operations to 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 manage reconciliation from the Google
  system to the manage user repository.

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

  All of the commands shown here assume that your domain is example.com. Adjust the examples to manage
  your domain.

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

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

     The following command creates an entry for user Sam Carter:

     $  curl \
     --cacert self-signed.crt \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --header "Content-Type: application/json" \
     --request POST \
     --data '{
      "__NAME__": "samcarter@example.com",
      "__PASSWORD__"  : "password",
      "givenName" : "Sam",
      "familyName": "Carter",
      "agreedToTerms": true,
      "changePasswordAtNextLogin" : false
     }' \
     "https://localhost:8443/openidm/system/google/__ACCOUNT__?_action=create"

     {
       "_id": "103567435255251233551",
       "_rev": "\"iwpzoDgSq9BJw-XzORg0bILYPVc/LWHPMXXG8M0cjQAPITM95Y636cM\"",
     ...
     }

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

  2. 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 OpenIDM managed user repository.

     To run reconciliation follow these steps:
     - In the Admin UI, select Configure > Mappings.
     - Click on the sourceGoogle__ACCOUNT___managedUser mapping, and click Reconcile Now.
     - Select Manage > User and verify that the user Sam Carter has been created in the repository.

  3. 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 \
      --cacert self-signed.crt \
      --header "X-OpenIDM-Username: openidm-admin" \
      --header "X-OpenIDM-Password: openidm-admin" \
      --header "Content-Type: application/json" \
      --request PUT \
      --header "If-Match : *" \
      --data '{
       "__NAME__": "samcarter@example.com",
       "__PASSWORD__"  : "password",
       "givenName" : "Sam",
       "familyName": "Carter",
       "agreedToTerms": true,
       "changePasswordAtNextLogin" : false,
       "phones" :
        [
         {
          "value": "1234567890",
          "type": "home"
         },
         {
          "value": "0987654321",
          "type":"work"
         }
        ]
       }' \
      "https://localhost:8443/openidm/system/google/__ACCOUNT__/103567435255251233551"

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

     $ curl \
      --cacert self-signed.crt \
      --header "X-OpenIDM-Username: openidm-admin" \
      --header "X-OpenIDM-Password: openidm-admin" \
      --request GET \
      "https://localhost:8443/openidm/system/google/__ACCOUNT__/103567435255251233551"

  5. Create a group entry on your Google resource:

     $ curl \
      --cacert self-signed.crt \
      --header "X-OpenIDM-Username: openidm-admin" \
      --header "X-OpenIDM-Password: openidm-admin" \
      --header "Content-Type: application/json" \
      --request POST \
      --data '{
       "__NAME__": "testGroup@example.com",
       "__DESCRIPTION__": "Group used for google-connector sample.",
       "name": "TestGroup"
      }' \
      "https://localhost:8443/openidm/system/google/__GROUP__?_action=create"

     {
       "_id": "00meukdy40gpg98",
       ...
     }

  6. 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 \
      --cacert self-signed.crt \
      --header "X-OpenIDM-Username: openidm-admin" \
      --header "X-OpenIDM-Password: openidm-admin" \
      --header "Content-Type: application/json" \
      --request PUT \
      --data '{
       "groupKey" : "00meukdy40gpg98",
       "role": "MEMBER",
       "__NAME__": "samcarter@example.com",
       "email": "samcarter@example.com",
       "type": "MEMBER"
      }' \
      "https://localhost:8443/openidm/system/google/Member/103567435255251233551"

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

     $ curl \
      --cacert self-signed.crt \
      --header "X-OpenIDM-Username: openidm-admin" \
      --header "X-OpenIDM-Password: openidm-admin" \
      --request GET \
      "https://localhost:8443/openidm/system/google/__GROUP__/00meukdy40gpg98"

     {
       "_id": "00meukdy40gpg98",
       ...
       "directMembersCount": 1
     }

  8. Delete the group entry:

     $ curl \
      --cacert self-signed.crt \
      --header "X-OpenIDM-Username: openidm-admin" \
      --header "X-OpenIDM-Password: openidm-admin" \
      --request DELETE \
      "https://localhost:8443/openidm/system/google/__GROUP__/00meukdy40gpg98"

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

     $ curl \
      --cacert self-signed.crt \
      --header "X-OpenIDM-Username: openidm-admin" \
      --header "X-OpenIDM-Password: openidm-admin" \
      --request DELETE \
      "https://localhost:8443/openidm/system/google/__ACCOUNT__/103567435255251233551"
