2 Deploying the Google Apps Connector

The procedure to deploy the connector is divided across three stages namely preinstallation, installation, and postinstallation.

The following topics provide details on these stages:

Note:

Some of the procedures described in this chapter must be performed on the target system. To perform these procedures, you must use a Google Apps account with administrator privileges.

2.1 Preinstallation

Preinstallation involves copying third-party libraries to the computer hosting Oracle Identity Manager. It also involves registering the connector with Google Apps for accessing user management APIs and creating a target system account for the connector.

The following topics provide details on these preinstallation procedures:

2.1.1 Downloading and Copying Google Apps Third-Party Libraries

Perform the following steps to download and copy Google Apps third-party libraries:

  1. Download Google Apps third-party libraries as following:

    1. Visit the following URL:

      https://developers.google.com/

    2. In the API Guides, Reference, and Client Libs region, click client libraries.
    3. On the Directory API: Client Libraries page, in the "Client library" column of the table, click Google APIs Client Library for Java.
    4. Save the ZIP file to a temporary location. This file contains the following third-party libraries:
      1. google-api-client-1.18.0-rc.jar
      2. google-api-services-admin-directory_v1-VERSION.jar
      3. In this file name, VERSION is the latest version of the JAR file available in the ZIP file. For example, google-api-services-admin-directory_v1-rev35-1.18.0-rc.jar.

      4. google-api-services-groupssettings-v1-[version].jar

        In this file name, VERSION is the latest version of this JAR file that is available in the ZIP file. For example, google-api-services-groupssettings-v1-rev43-1.17.0-rc.jar.

        If this file is not available, then visit the following URL and click Download the Groups Settings API v1 Client Library for Java to obtain the ZIP file that contains this JAR.

        https://developers.google.com/api-client-library/java/apis/groupssettings/v1

      5. google-http-client-1.18.0-rc.jar
      6. google-http-client-jackson2-1.18.0-rc.jar
      7. google-oauth-client-1.18.0-rc.jar
      8. httpclient-4.0.1.jar
      9. httpcore-4.0.1.jar
      10. jackson-core-2.1.3.jar

    Note:

    If the specified versions of the JAR files listed in this step are not available, then you can obtain them by visiting the following URL and then searching for and downloading the JAR files in the Downloads tab:

    https://code.google.com/p/google-api-java-client

  2. Copy the downloaded third-party libraries as follows:

    1. Create a directory named googleapps-RELEASE_NUMBER under the following directory.

      OIM_HOME/server/ConnectorDefaultDirectory/targetsystems-lib/

      For example, if you are using release 11.1.1.7.0 of this connector, then create a directory named googleapps-11.1.1.7.0 in the OIM_HOME/server/ConnectorDefaultDirectory/targetsystems-lib/ directory.

    2. Copy the third-party libraries downloaded in Step 1 to the OIM_HOME/server/ConnectorDefaultDirectory/targetsystems-lib/googleapp-RELEASE_NUMBER directory.

2.1.2 Preinstallation on the Target System

This section provides a high-level summary about the preinstallation tasks to be performed on the target system.

The preinstallation process involves performing the following tasks:

Note:

The detailed instructions for performing each of these preinstallation tasks are available in the Google Cloud Platform Documentation at https://cloud.google.com/docs/

  1. Create a project and register your client application with the Google Apps Cloud platform in the Google Developers Console.
  2. Activate the associated API services such as adding custom information, enable billing, and page monitoring services, for your client application. While activating the associated API services ensure that the statuses of the Admin SDK and Group Settings APIs are set to ON.
  3. Create a service account and enable your client application to access the activated APIs. Additionally, create a Client ID, Public/Private key pair, and password for the earlier created service account. After the service account creation, note down the Client ID, Public/Private key pair and password information. This information is required while adding scopes and also while configuring the IT resource parameters.
  4. Add scopes and authorize the registered client application.
  5. Create a user account on the target system. The connector uses this account to connect to the target system during each connector operation. Post account creation, assign the Groups Admin and User Management Admin admin roles to the newly created account.
  6. Enable access to various Google administrative APIs available in the Google Apps Business Domain. The administrative API allows you to manage user accounts and synchronizes Google Apps user accounts with your own user account
  7. Enable external user access to groups in Google Apps. Perform this step only if you want external users to access groups in Google Apps.

2.2 Installation

You must install the connector in Oracle Identity Manager. If necessary, you can also deploy the connector in a Connector Server.

Installation information is divided across the following sections:

2.2.1 Understanding Installation of the Google Apps Connector

Depending on where you want to run the connector code (bundle), the connector provides installation options:

The following are the installation options:

2.2.2 Installing the Connector in Oracle Identity Manager

Perform this procedure to install the Google Apps connector in Oracle Identity Manager.

Note:

In this guide, the term Connector Installer has been used to refer to the Install Connectors feature of the Administrative and User Console.

To run the Connector Installer:

  1. Copy the contents of the connector installation media into the following directory:

    OIM_HOME/server/ConnectorDefaultDirectory

  2. If you have not already done so, create a directory in OIM_HOME/ConnectorDefaultDirectory/targetsystems-lib with the same name as the installer package. For example:

    OIM_HOME/server/ConnectorDefaultDirectory/targetsystems-lib/googleapps-11.1.1.7.0

    Copy the third-party libraries to this directory. See Downloading and Copying Google Apps Third-Party Libraries.

  3. If you are using Oracle Identity Manager release 11.1.1.x:
    1. Log in to Oracle Identity Manager Administrative and User Console by using the user account described in Creating the User Account for Installing Connectors of Oracle Fusion Middleware Administering Oracle Identity Manager.
    2. On the Welcome to Identity Manager Advanced Administration page, in the System Management region, click Manage Connector.
  4. If you are using Oracle Identity Manager release 11.1.2.x or later:
    1. Log in to Oracle Identity System Administration by using the user account described in Creating the User Account for Installing Connectors of Oracle Fusion Middleware Administering Oracle Identity Manager.
    2. In the left pane, under System Management, click Manage Connector.
  5. In the Manage Connector page, click Install.
  6. From the Connector List list, select GoogleApps Connector RELEASE NUMBER. This list displays the names and release numbers of connectors whose installation files you copy into the default connector installation directory:

    OIM_HOME/server/ConnectorDefaultDirectory

    If you have copied the installation files into a different directory, then:

    1. In the Alternative Directory field, enter the full path and name of that directory.
    2. To repopulate the list of connectors in the Connector List list, click Refresh.
    3. From the Connector List list, select GoogleApps Connector RELEASE NUMBER.
  7. Click Load.
  8. To start the installation process, click Continue.

    The following tasks are performed in sequence:

    1. Configuration of connector libraries
    2. Import of the connector XML files (by using the Deployment Manager)
    3. Compilation of adapters

    On successful completion of a task, a check mark is displayed for the task. If a task fails, then an X mark and a message stating the reason for failure are displayed. If a task fails, then make the required correction and perform one of the following steps:

    Figure 2-1 Installation Status

    Description of Figure 2-1 follows
    Description of "Figure 2-1 Installation Status"

    • Retry the installation by clicking Retry.

    • Cancel the installation and begin again from Step 3.

  9. If all three tasks of the connector installation process are successful, then a message indicating successful installation is displayed.

    In addition, a list of the steps that you must perform after the installation is displayed. These steps are as follows:

    1. Ensuring that the prerequisites for using the connector are addressed

      Note:

      At this stage, run the PurgeCache utility to load the server cache with content from the connector resource bundle in order to view the list of prerequisites. See Clearing Content Related to Connector Resource Bundles from the Server Cache for information about running the PurgeCache utility.

      There are no prerequisites for some predefined connectors.

    2. Configuring the IT resource for the connector.

      Record the name of the IT resource displayed on this page. The procedure to configure the IT resource is described later in this guide.

    3. Configuring the scheduled tasks that are created when you installed the connector

      Record the names of the scheduled tasks displayed on this page. The procedure to configure these scheduled tasks is described later in this guide.

    When you run the Connector Installer, it copies the connector files and external code files to destination directories on the Oracle Identity Manager host computer. These files are listed in Table A-1

2.2.3 Deploying the Connector Bundle in a Connector Server

You can deploy the Google Apps connector bundle into the Java Connector Server by performing the procedure mentioned here.

See Also:

Using an Identity Connector Server in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager for information about installing and configuring connector server and running the connector server

If you want to deploy the Google Apps connector bundle into the Java Connector Server, then follow these steps:

  1. Stop the Java Connector Server.

    Note:

    You can download the necessary Java Connector Server from the Oracle Technology Network web page.

  2. Copy the Google Apps connector bundle into the Java Connector Server CONNECTOR_SERVER_HOME\bundles directory.
  3. Copy Google Apps third-party libraries to the CONNECTOR_SERVER_HOME\lib directory. See Downloading and Copying Google Apps Third-Party Libraries for more information about the third-party libraries.
  4. Start the Java Connector Server.

2.3 Postinstallation

Postinstallation for the connector involves configuring Oracle Identity Manager, enabling logging to track information about all connector events, and configuring SSL. It also involves performing some optional configurations such as enabling request-based provisioning and localizing the user interface.

Postinstallation steps are divided across the following sections:

2.3.1 Configuring Oracle Identity Manager 11.1.2.x or Later

If you are using Oracle Identity Manager release 11.1.2.x or later, you must create additional metadata such as a UI form and an application instance. In addition, you must run entitlement and catalog synchronization jobs.

These procedures are described in the following sections:

2.3.1.1 Creating and Activating a Sandbox

Create and activate a sandbox as follows. For detailed instructions, see Managing Sandboxes in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager.

  1. On the upper navigation bar, click Sandboxes. The Manage Sandboxes page is displayed.
  2. On the toolbar, click Create Sandbox. The Create Sandbox dialog box is displayed.
  3. In the Sandbox Name field, enter a name for the sandbox. This is a mandatory field.
  4. In the Sandbox Description field, enter a description of the sandbox. This is an optional field.
  5. Click Save and Close. A message is displayed with the sandbox name and creation label.
  6. Click OK. The sandbox is displayed in the Available Sandboxes section of the Manage Sandboxes page.
  7. Select the sandbox that you created.
  8. From the table showing the available sandboxes in the Manage Sandboxes page, select the newly created sandbox that you want to activate.
  9. On the toolbar, click Activate Sandbox.

    The sandbox is activated.

2.3.1.2 Creating a New UI Form

Create a new UI form as follows. For detailed instructions, see Managing Forms in Oracle Fusion Middleware Administering Oracle Identity Manager.

  1. In the left pane, under Configuration, click Form Designer.
  2. Under Search Results, click Create.
  3. Select the resource type for which you want to create the form.
  4. Enter a form name and click Create.

2.3.1.3 Creating an Application Instance

Create an application instance as follows. For detailed instructions, see Managing Application Instances in Oracle Fusion Middleware Administering Oracle Identity Manager.

  1. In the System Administration page, under Configuration in the left pane, click Application Instances.
  2. Under Search Results, click Create.
  3. Enter appropriate values for the fields displayed on the Attributes form and click Save.
  4. In the Form drop-down list, select the newly created form and click Apply.
  5. Publish the application instance for a particular organization.

Note:

If you are using access policy-based provisioning, then specify the Active Directory connector application instance as the value for the Parent AppInstance attribute.

2.3.1.4 Publishing a Sandbox

To publish the sandbox that you created in Creating and Activating a Sandbox:

  1. Close all the open tabs and pages.
  2. In the upper right corner of the page, click the Sandboxes link. The Manage Sandboxes page is displayed.
  3. From the table showing the available sandboxes in the Manage Sandboxes page, select the sandbox that you created in Creating and Activating a Sandbox.
  4. On the toolbar, click Publish Sandbox. A message is displayed asking for confirmation.
  5. Click Yes to confirm. The sandbox is published and the customizations it contained are merged with the main line.

2.3.1.5 Harvesting Entitlements and Sync Catalog

You can populate Entitlement schema from child process form table, and harvest roles, application instances, and entitlements into catalog. You can also load catalog metadata.

To harvest entitlements and sync catalog:

  1. Run the scheduled jobs for lookup field synchronization listed in –-----.
  2. Run the Entitlement List scheduled job to populate Entitlement Assignment schema from child process form table. See Predefined Scheduled Tasks in Oracle Fusion Middleware Administering Oracle Identity Manager for more information about this scheduled job.
  3. Run the Catalog Synchronization Job scheduled job. See for more information about this scheduled job. See Predefined Scheduled Tasks in Oracle Fusion Middleware Administering Oracle Identity Manager for more information about this scheduled job.

2.3.1.6 Updating an Existing Application Instance with a New Form

For any changes you do in the Form Designer, you must create a new UI form and update the changes in an application instance.

To update an existing application instance with a new form:

  1. Create a sandbox and activate it as described in Creating and Activating a Sandbox.
  2. Create a new UI form for the resource as described in Creating a New UI Form.
  3. Open the existing application instance.
  4. In the Form field, select the new UI form that you created.
  5. Save the application instance.
  6. Publish the sandbox as described in Publishing a Sandbox.

2.3.2 Enabling Request-Based Provisioning

In request-based provisioning, an end user creates a request for a resource or entitlement by using the Administrative and User Console.

Note:

Perform the procedure described in this section only if you are using Oracle Identity Manager release 11.1.1.x.

In request-based provisioning, an end user creates a request for a resource or entitlement by using the Administrative and User Console. Administrators or other users cannot create requests for a particular user. Requests can be viewed and approved by approvers designated in Oracle Identity Manager.

Note:

The direct provisioning feature of the connector is automatically disabled when you enable request-based provisioning. Therefore, do not enable request-based provisioning if you want to use the direct provisioning.

To enable request-based provisioning, perform the following procedures:

2.3.2.1 Importing Request Datasets

There are two ways of importing request datasets:

Note:

Request Datasets imported either into MDS or by using Deployment Manager are same.

2.3.2.1.1 Importing Request Datasets Using MDS Import Utility

To import a request dataset definition into the MDS:

  1. Copy the predefined request datasets from the installation media to any directory on the Oracle Identity Manager host computer. The following is the list of predefined request datasets available in the dataset directory on the installation media:

    • ProvisionResource_GoogleAppsUser.xml

    • ModifyProvisionedResource_GoogleAppsUser.xml

    It is recommended that you create a directory structure as follows:

    /custom/connector/RESOURCE_NAME

    For example:

    E:\MyDatasets\custom\connector\GoogleApps

    Note:

    Until you complete the procedure to configure request-based provisioning, ensure that there are no other files or directories inside the parent directory in which you create the directory structure. In the preceding example, ensure that there are no other files or directories inside the E:\MyDatasets directory.

    The directory structure to which you copy the predefined request dataset files is the MDS location into which this file is imported after you run the Oracle Identity Manager MDS Import utility.

  2. Ensure that you have set the environment for running the MDS Import utility. See Setting up the Environment for MDS Utilities in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager for detailed information about setting up the environment for MDS utilities.

    Note:

    While setting up the properties in the weblogic.properties file, ensure that the value of the metadata_from_loc property is the parent directory of the /custom/connector/RESOURCE_NAME directory. For example, while performing Step 1 of this procedure, if you copy the files to the E:\MyDatasets\custom\connector\GoogleApps directory, then set the value of the metada_from_loc property to E:\MyDatasets.

  3. In a command window, change to the OIM_HOME/server/bin directory.
  4. Run one of the following commands:

    • On Microsoft Windows

      weblogicImportMetadata.bat

    • On UNIX

      weblogicImportMetadata.sh
  5. When prompted, enter values for the following:

    • Please enter your username [weblogic]

      Enter the username used to log in to the Oracle WebLogic Server

      Sample value: WL_User

    • Please enter your password [weblogic]

      Enter the password used to log in to the Oracle WebLogic Server

    • Please enter your server URL [t3://localhost:7001]

      Enter the URL of the application server in the following format:

      t3://HOST_NAME_IP_ADDRESS:PORT

      In this format, replace:

      HOST_NAME_IP_ADDRESS with the host name or IP address of the computer on which Oracle Identity Manager is installed.

      PORT with the port on which Oracle Identity Manager is listening.

    The request dataset is imported into the MDS.

2.3.2.1.2 Importing Request Datasets Using Deployment Manager

The request datasets (predefined or generated) can also be imported using Deployment Manager (DM), which are stored in xml/GoogleApps-Datasets.xml.

To import a request dataset definition using Deployment Manager:

  1. Log in to Oracle Identity Manager Administrative and User Console.
  2. Go to Advanced Administration.
  3. Click Import Deployment Manager File.
  4. Navigate to GoogleApps-Datasets.xml file and click Add to add it for import. The datasets available for import will be displayed.
  5. Click Import. A message with the successful import of the datasets is displayed.

2.3.2.2 Enabling the Auto Save Form Feature

To enable the Auto Save Form feature:

  1. Log in to the Design Console.
  2. Expand Process Management, and then double-click Process Definition.
  3. Search for and open the GoogleApps User process definition.
  4. Select the Auto Save Form check box.
  5. Click Save.

2.3.2.3 Running the PurgeCache Utility

Run the PurgeCache utility to clear content belonging to the Metadata category from the server cache. See Clearing Content Related to Connector Resource Bundles from the Server Cache for instructions.

The procedure to enable request-based provisioning ends with this step.

2.3.3 Changing to the Required Input Locale

Changing to the required input locale (language and country setting) involves installing the required fonts and setting the required input locale.

You may require the assistance of the system administrator to change to the required input locale.

2.3.4 Clearing Content Related to Connector Resource Bundles from the Server Cache

When you deploy the connector, the resource bundles are copied from the resources directory on the installation media into the Oracle Identity Manager database.

Whenever you add a new resource bundle to the connectorResources directory or make a change in an existing resource bundle, you must clear content related to connector resource bundles from the server cache.

To clear content related to connector resource bundles from the server cache:

  1. In a command window, switch to the OIM_HOME/server/bin directory.
  2. Enter one of the following commands:

    Note:

    • You can use the PurgeCache utility to purge the cache for any content category. Run PurgeCache.bat CATEGORY_NAME on Microsoft Windows or PurgeCache.sh CATEGORY_NAME on UNIX. The CATEGORY_NAME argument represents the name of the content category that must be purged.

      For example, the following commands purge Metadata entries from the server cache:

      PurgeCache.bat MetaData

      PurgeCache.sh MetaData

    • Before running the PurgeCache utility, ensure the WL_HOME and JAVA_HOME environment variables are set.

    On Microsoft Windows: PurgeCache.bat All

    On UNIX: PurgeCache.sh All

    When prompted, enter the user name and password of an account belonging to the SYSTEM ADMINISTRATORS group. In addition, you are prompted to enter the service URL in the following format:

    t3://OIM_HOST_NAME:OIM_PORT_NUMBER

    In this format:

    • Replace OIM_HOST_NAME with the host name or IP address of the Oracle Identity Manager host computer.

    • Replace OIM_PORT_NUMBER with the port on which Oracle Identity Manager is listening.

2.3.5 Managing Logging

Oracle Identity Governance uses Oracle Java Diagnostic Logging (OJDL) for recording all types of events pertaining to the connector. OJDL is based on java.util.logger.

The following topics provide detailed information about logging:

2.3.5.1 Understanding Log Levels

Note:

In an Oracle Identity Manager cluster, perform this procedure on each node of the cluster. Then, restart each node.

When you enable logging, Oracle Identity Manager automatically stores in a log file information about events that occur during the course of provisioning and reconciliation operations.

To specify the type of event for which you want logging to take place, you can set the log level to one of the following:

  • SEVERE.intValue()+100

    This level enables logging of information about fatal errors.

  • SEVERE

    This level enables logging of information about errors that might allow Oracle Identity Manager to continue running.

  • WARNING

    This level enables logging of information about potentially harmful situations.

  • INFO

    This level enables logging of messages that highlight the progress of the application.

  • CONFIG

    This level enables logging of information about fine-grained events that are useful for debugging.

  • FINE, FINER, FINEST

    These levels enable logging of information about fine-grained events, where FINEST logs information about all events.

These message types are mapped to ODL message type and level combinations as shown in Table 2-1.

Table 2-1 Log Levels and ODL Message Type:Level Combinations

Java Level ODL Message Type:Level

SEVERE.intValue()+100

INCIDENT_ERROR:1

SEVERE

ERROR:1

WARNING

WARNING:1

INFO

NOTIFICATION:1

CONFIG

NOTIFICATION:16

FINE

TRACE:1

FINER

TRACE:16

FINEST

TRACE:32

The configuration file for OJDL is logging.xml, which is located at the following path:

DOMAIN_HOME/config/fmwconfig/servers/OIM_SERVER/logging.xml

Here, DOMAIN_HOME and OIM_SEVER are the domain name and server name specified during the installation of Oracle Identity Manager.

2.3.5.2 Enabling Logging

Perform this procedure to enable logging in Oracle WebLogic Server.

  1. Edit the logging.xml file as follows:
    1. Add the following blocks in the file: 
      <log_handler name='googleapps-handler' level='[LOG_LEVEL]' class='oracle.core.ojdl.logging.ODLHandlerFactory'>
<property name='logreader:' value='off'/>
     <property name='path' value='[FILE_NAME]'/>
     <property name='format' value='ODL-Text'/>
     <property name='useThreadName' value='true'/>
     <property name='locale' value='en'/>
     <property name='maxFileSize' value='5242880'/>
     <property name='maxLogSize' value='52428800'/>
     <property name='encoding' value='UTF-8'/>
   </log_handler>

      <logger name="ORG.IDENTITYCONNECTORS.GOOGLEAPPS" level="[LOG_LEVEL]" useParentHandlers="false">
     <handler name="googleapps-handler"/>
     <handler name="console-handler"/>
   </logger>
    2. Replace both occurrences of [LOG_LEVEL] with the ODL message type and level combination that you require. Table 2-1 lists the supported message type and level combinations.

      Similarly, replace [FILE_NAME] with the full path and name of the log file in which you want log messages to be recorded.

      The following blocks show sample values for [LOG_LEVEL] and [FILE_NAME]:

      <log_handler name='googleapps-handler' level='NOTIFICATION:1' class='oracle.core.ojdl.logging.ODLHandlerFactory'>
<property name='logreader:' value='off'/>
     <property name='path' value='F:\MyMachine\middleware\user_projects\domains\base_domain1\servers\oim_server1\logs\oim_server1-diagnostic-1.log'/>
     <property name='format' value='ODL-Text'/>
     <property name='useThreadName' value='true'/>
     <property name='locale' value='en'/>
     <property name='maxFileSize' value='5242880'/>
     <property name='maxLogSize' value='52428800'/>
     <property name='encoding' value='UTF-8'/>
   </log_handler>

      <logger name="ORG.IDENTITYCONNECTORS.GOOGLEAPPS" level="NOTIFICATION:1" useParentHandlers="false">
     <handler name="googleapps-handler"/>
     <handler name="console-handler"/>
   </logger>

      With these sample values, when you use Oracle Identity Manager, all messages generated for this connector that are of a log level equal to or higher than the NOTIFICATION:1 level are recorded in the specified file.

  2. Save and close the file.
  3. Set the following environment variable to redirect the server logs to a file:

    • For Microsoft Windows:

      set WLS_REDIRECT_LOG=FILENAME

    • For UNIX:

      export WLS_REDIRECT_LOG=FILENAME

    Replace FILENAME with the location and name of the file to which you want to redirect the output.

  4. Restart the application server.

2.3.6 Configuring the IT Resource for the Target System

The GoogleApps IT resource is automatically created when you run the Connector Installer. You must specify values for the parameters of the IT resource.

The following section describes the parameters of the IT resource:

To specify values for the parameters of the IT resource:

  1. If you are using Oracle Identity Manager release 11.1.1.x, then:
    1. Log in to the Administrative and User Console.
    2. On the Welcome page, click Advanced in the upper-right corner of the page.
    3. On the Welcome to Oracle Identity Manager Advanced Administration page, in the Configuration region, click Manage IT Resource.
  2. If you are using Oracle Identity Manager release 11.1.2.x or later, then:
    1. Log in to Identity System Administration.
    2. Create and activate a sandbox. For detailed instructions on creating and activating a sandbox, see Managing Sandboxes in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Manager.
    3. In the left pane, under Configuration, click IT Resource.
  3. In the IT Resource Name field on the Manage IT Resource page, enter GoogleApps and then click Search.
  4. Click Edit for the IT resource.
  5. From the list at the top of the page, select Details and Parameters.
  6. Specify values for the parameters of the IT resource. Table 2-2 describes each parameter.

    Note:

    Entries in this table are sorted in alphabetical order of parameter names.

    Table 2-2 Parameters of the IT Resource

    Parameter Description

    applicationName

    Name of the project that was created as part of registering the client application.

    Configuration Lookup

    Name of the lookup definition that stores configuration information used during reconciliation and provisioning.

    Default value: Lookup.Configuration.GoogleApps

    Connector Server Name

    If you are using Google Apps Connector together with Java Connector Server, then provide the name of Connector Server IT Resource here.

    domainName

    Domain name of your Google Apps domain.

    Sample value: mydomain.com

    proxyHost

    The proxy host name. This is useful when a connector is to be used in the network protected by the web proxy. You can check with your network administrator for more information about proxy configuration.

    proxyPassword

    The proxy password. This is useful when a connector is to be used in the network protected by the web proxy. You can check with your network administrator for more information about proxy configuration.

    proxyPort

    The proxy port number. This is useful when a connector is to be used in the network protected by the web proxy. You can check with your network administrator for more information about proxy configuration.

    proxyUsername

    The proxy user name. This is useful when a connector is to be used in the network protected by the web proxy. You can check with your network administrator for more information about proxy configuration.

    scopes

    The scope of your client application.

    Default value: "https://www.googleapis.com/auth/admin.directory.user","https://www.googleapis.com/auth/admin.directory.group","https://www.googleapis.com/auth/admin.directory.group.member","https://www.googleapis.com/auth/apps.groups.settings"

    serviceAccountId

    The email address of the service account created.

    serviceAccountPrivateKey

    Name and complete path to the directory containing the private key. This is the same location to which the private key was saved earlier as described in Preinstallation on the Target System.

    Sample value: /scratch/34567890sdfghjk.p12

    serviceAccountUser

    Name of the account used to log in to the client application. Enter the user name of account that you created.

    Sample value: admin@mydomain.com
  7. To save the values, click Update.

2.3.7 Creating the IT Resource for the Connector Server

Perform the procedure described in this section only if you have deployed the connector bundle remotely in a Connector Server.

Note:

Before you deploy the connector bundle remotely in a Connector Server, you must deploy the connector in Oracle Identity Manager by performing the procedures described in Installation.

To create the IT resource for the Connector Server:

  1. Depending on the Oracle Identity Manager release you are using, perform one of the following steps:
    • For Oracle Identity Manager release 11.1.1.x: Log in to the Administrative and User Console.
    • For Oracle Identity Manager release 11.1.2.x or later: Log in to Identity System Administration.
  2. If you are using Oracle Identity Manager release 11.1.1.x, then:
    1. On the Welcome page, click Advanced in the upper-right corner of the page.
    2. On the Welcome to Oracle Identity Manager Advanced Administration page, in the Configuration region, click Manage IT Resource.
  3. If you are using Oracle Identity Manager release 11.1.2.x or later, then in the left pane, under Configuration, click IT Resource.
  4. On the Step 1: Provide IT Resource Information page, perform the following steps:

    • IT Resource Name: Enter a name for the IT resource.

    • IT Resource Type: Select Connector Server from the IT Resource Type list.

    • Remote Manager: Do not enter a value in this field.

  5. Click Continue. Figure 2-2 shows the IT resource values added on the Create IT Resource page.

    Figure 2-2 Step 1: Provide IT Resource Information

    Description of Figure 2-2 follows
    Description of "Figure 2-2 Step 1: Provide IT Resource Information"
  6. On the Step 2: Specify IT Resource Parameter Values page, specify values for the parameters of the IT resource and then click Continue. Figure 2-3 shows the Step 2: Specify IT Resource Parameter Values page.

    Figure 2-3 Step 2: Specify IT Resource Parameter Values

    Description of Figure 2-3 follows
    Description of "Figure 2-3 Step 2: Specify IT Resource Parameter Values"

    Table 2-3 provides information about the parameters of the IT resource.

    Table 2-3 Parameters of the IT Resource for the Connector Server

    Parameter Description

    Host

    Enter the host name or IP address of the computer hosting the connector server.

    Sample value: RManager

    Key

    Enter the key for the Java connector server.

    Port

    Enter the number of the port at which the connector server is listening.

    Default value: 8759

    Timeout

    Enter an integer value which specifies the number of milliseconds after which the connection between the connector server and Oracle Identity Manager times out.

    Sample value: 300

    UseSSL

    Enter true to specify that you will configure SSL between Oracle Identity Manager and the Connector Server. Otherwise, enter false.

    Default value: false

    Note: It is recommended that you configure SSL to secure communication with the connector server. To configure SSL, see Configuring SSL for Java Connector Server in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Governance.
  7. On the Step 3: Set Access Permission to IT Resource page, the SYSTEM ADMINISTRATORS group is displayed by default in the list of groups that have Read, Write, and Delete permissions on the IT resource that you are creating.

    Note:

    This step is optional.

    If you want to assign groups to the IT resource and set access permissions for the groups, then:

    1. Click Assign Group.
    2. For the groups that you want to assign to the IT resource, select Assign and the access permissions that you want to set. For example, if you want to assign the ALL USERS group and set the Read and Write permissions to this group, then you must select the respective check boxes in the row, as well as the Assign check box, for this group.
    3. Click Assign.
  8. On the Step 3: Set Access Permission to IT Resource page, if you want to modify the access permissions of groups assigned to the IT resource, then:

    Note:

    • This step is optional.

    • You cannot modify the access permissions of the SYSTEM ADMINISTRATORS group. You can modify the access permissions of only other groups that you assign to the IT resource.

    1. Click Update Permissions.
    2. Depending on whether you want to set or remove specific access permissions for groups displayed on this page, select or deselect the corresponding check boxes.
    3. Click Update.
  9. On the Step 3: Set Access Permission to IT Resource page, if you want to unassign a group from the IT resource, then:

    Note:

    • This step is optional.

    • You cannot unassign the SYSTEM ADMINISTRATORS group. You can unassign only other groups that you assign to the IT resource.

    1. Select the Unassign check box for the group that you want to unassign.
    2. Click Unassign.
  10. Click Continue. Figure 2-4 shows the Step 3: Set Access Permission to IT Resource page.

    Figure 2-4 Step 3: Set Access Permission to IT Resource

    Description of Figure 2-4 follows
    Description of "Figure 2-4 Step 3: Set Access Permission to IT Resource"
  11. On the Step 4: Verify IT Resource Details page, review the information that you provided on the first, second, and third pages. If you want to make changes in the data entered on any page, click Back to revisit the page and then make the required changes.
  12. To proceed with the creation of the IT resource, click Continue. Figure 2-5 shows Step 4: Verify IT Resource Details page.

    Figure 2-5 Step 4: Verify IT Resource Details

    Description of Figure 2-5 follows
    Description of "Figure 2-5 Step 4: Verify IT Resource Details"
  13. The Step 5: IT Resource Connection Result page displays the results of a connectivity test that is run using the IT resource information. If the test is successful, then click Continue. If the test fails, then you can perform one of the following steps:

    • Click Back to revisit the previous pages and then make corrections in the IT resource creation information.

    • Click Cancel to stop the procedure, and then begin from the first step onward.

    Figure 2-6 shows the Step 5: IT Resource Connection Result page.

    Figure 2-6 Step 5: IT Resource Connection Result

    Description of Figure 2-6 follows
    Description of "Figure 2-6 Step 5: IT Resource Connection Result"
  14. Click Finish. Figure 2-7 shows the IT Resource Created Page.

    Figure 2-7 Step 6: IT Resource Created

    Description of Figure 2-7 follows
    Description of "Figure 2-7 Step 6: IT Resource Created"

2.3.8 Localizing Field Labels in UI Forms

You can localize UI form field labels by using the resource bundle corresponding to the language you want to use. The resource bundles are available in the connector installation media.

Note:

Perform the procedure described in this section only if you are using Oracle Identity Manager release 11.1.2.x or later and you want to localize UI form field labels.

To localize field label that you add to in UI forms:
  1. Log in to Oracle Enterprise Manager.
  2. In the left pane, expand Application Deployments and then select oracle.iam.console.identity.sysadmin.ear.
  3. In the right pane, from the Application Deployment list, select MDS Configuration.
  4. On the MDS Configuration page, click Export and save the archive (oracle.iam.console.identity.sysadmin.ear_V2.0_metadata.zip) to the local computer.
  5. Extract the contents of the archive, and open one of the following files in a text editor:

    • For Oracle Identity Manager 11g Release 2 PS2 (11.1.2.2.0):

      SAVED_LOCATION\xliffBundles\oracle\iam\ui\runtime\BizEditorBundle_en.xlf

    • For releases prior to Oracle Identity Manager 11g Release 2 PS2 (11.1.2.2.0):

      SAVED_LOCATION\xliffBundles\oracle\iam\ui\runtime\BizEditorBundle.xlf

  6. Edit the BizEditorBundle.xlf file in the following manner:
    1. Search for the following text: 
      <file source-language="en"  
original="/xliffBundles/oracle/iam/ui/runtime/BizEditorBundle.xlf"
datatype="x-oracle-adf">
    2. Replace with the following text: 
      <file source-language="en" target-language="LANG_CODE"
original="/xliffBundles/oracle/iam/ui/runtime/BizEditorBundle.xlf"
datatype="x-oracle-adf">
    3. Search for the application instance code. This procedure shows a sample edit for Oracle Database application instance. The original code is: 
      <trans-unit id="${adfBundle['oracle.adf.businesseditor.model.util.BaseRuntimeResourceBundle']['persdef.sessiondef.oracle.iam.ui.runtime.form.model.user.entity.userEO.UD_AD_USERNAME__c_description']}">
<source>Username</source>
</target>
</trans-unit>
<trans-unit id="sessiondef.oracle.iam.ui.runtime.form.model.googleapps.entity.googleappsEO.UD_GA_USR_ACCOUNT_NAME__c">
<source>Username</source>
</target>
</trans-unit>
    4. Open the resource file from the connector package, for example GoogleApps_ja.properties, and get the value of the attribute from the file, for example, global.udf.UD_GA_USR_ACCOUNT_NAME=\u30A2\u30AB\u30A6\u30F3\u30C8\u540D.
    5. Replace the original code shown in Step 6.c with the following: 
      <trans-unit id="${adfBundle['oracle.adf.businesseditor.model.util.BaseRuntimeResourceBundle']['persdef.sessiondef.oracle.iam.ui.runtime.form.model.user.entity.userEO.UD_GA_USR_ACCOUNT_NAME__c_description']}">
<source>Account Name</source>
<target>u30A2\u30AB\u30A6\u30F3\u30C8\u540D</target>
</trans-unit>
<trans-unit id="sessiondef.oracle.iam.ui.runtime.form.model.googleapps.entity.googleappsEO.UD_GA_USR_ACCOUNT_NAME__c_LABEL">
<source>Account Name</source>
<target>\u30A2\u30AB\u30A6\u30F3\u30C8\u540D</target>
</trans-unit>
    6. Repeat steps 6.a through 6.d. for all attributes of the process form.
    7. Save the file as BizEditorBundle_LANG_CODE.xlf. In this file name, replace LANG_CODE with the code of the language to which you are localizing.

      Sample file name: BizEditorBundle_ja.xlf.

  7. Repackage the ZIP file and import it into MDS.

    See Also:

    Deploying and Undeploying Customizations in Oracle Fusion Middleware Developing and Customizing Applications for Oracle Identity Governance for more information about exporting and importing metadata files

  8. Log out of and log in to Oracle Identity Governance.

2.4 Upgrading the Connector

If you have already deployed the Google Apps Connector versions 11.1.1.5.0 or 11.1.1.6.0, then you can upgrade the connector to version 11.1.1.7.0. The following sections discuss the procedure to upgrade the connector:

The following sections discuss the procedure to upgrade the connector:

Note:

Before you perform the upgrade procedure:

  • It is strongly recommended that you create a backup of the Oracle Identity Manager database and the connector JARs before you perform an upgrade operation. Refer to the database documentation for information about creating a backup.
  • Upgrade the Google Apps connector.
  • As a best practice, first perform the upgrade procedure in a test environment.

2.4.1 Preupgrade Steps

Preupgrade steps for the connector involves performing a reconciliation run to fetch records from the target system, defining the source connector in Oracle Identity Manager, creating copies of the connector if you want to configure it for multiple installations of the target system, and disabling all the scheduled jobs.

Perform the following preupgrade steps:

  1. Perform a reconciliation run to fetch all latest updates to Oracle Identity Manager.
  2. Perform the preupgrade procedure documented in Managing Connector Lifecycle in Oracle Fusion Middleware Administering Oracle Identity Manager.
  3. Define the source connector (an earlier release of the connector that must be upgraded) in Oracle Identity Manager. You define the source connector to update the Deployment Manager XML file with all customization changes made to the connector. See Managing Connector Lifecycle in Oracle Fusion Middleware Administering Oracle Identity Manager for more information.

2.4.2 Upgrade Steps

This is a summary of the procedure to upgrade the connector for both staging and production environments.

Depending on the environment in which you are upgrading the connector, perform one of the following steps:

  • Staging Environment

    Perform the upgrade procedure by using the wizard mode.

    Note:

    Do not upgrade IT resource type definition. In order to retain the default setting, you must map the IT resource definition to "None".

  • Production Environment

    Perform the upgrade procedure by using the silent mode.

See Managing Connector Lifecycle in Oracle Fusion Middleware Administering Oracle Identity Manager for detailed information about the wizard and silent modes.

2.4.3 Postupgrade Steps

Postupgrade steps involve uploading new connector jars, running the Form Version Control (FVC) utility to manage data changes on a form, running the PostUpgradeScript.sql script to upgrade the IT resource, configuring the upgraded IT resource of the source connector, and so on.

Perform the following procedure:

  1. Perform the postupgrade procedure documented in Managing Connector Lifecycle of Oracle Fusion Middleware Administering Oracle Identity Manager.
  2. Update Oracle Identity Manager database with Google Apps connector version 11.1.1.7.0 ICF bundle JAR file, org.identityconnectors.googleapps-1.2.1.jar by following the procedure mentioned in Downloading and Copying Google Apps Third-Party Libraries.
  3. If the connector is deployed on a Connector Server, then perform the procedure mentioned below:
    1. Stop the Connector Server.
    2. Replace the org.identityconnectors.googleapps-1.2.1.jar file with the Google Apps 11.1.1.7.0 connector bundle.

      Note:

      If the Google Apps third party JARs are kept in an ICF bundle, then follow steps 3.a and 3.b of this procedure.

    3. Start the Connector Server.
  4. If the connector is not deployed on a Connector Server, then perform the procedure mentioned below on Oracle Identity Manager:
    1. Delete the existing ICF Bundle org.identityconnectors.googleapps-1.2.1.jar from the Oracle Identity Manager database using the Delete JARs utility using option-4 which is the designated option for the ICF bundle.

      When you run the Delete JARs utility, you are prompted to enter the login credentials of the Oracle Identity Manager administrator, URL of the Oracle Identity Manager host computer, context factory value, type of JAR file being deleted, and the name of the JAR file to be removed. To delete the ICF bundle jar file, specify 4 as the value of the JAR type.

    2. Copy the ICF Bundle org.identityconnectors.googleapps-1.2.1.jar from the installation media to a local temporary folder. Create a lib folder in the local temporary folder created and copy the Google Apps third-party JARs in the lib folder.

      Perform the JAR file update on the ICF Bundle org.identityconnectors.googleapps-1.2.1.jar using the same "lib" folder.

      For example, jar uvf org.identityconnectors.googleapps-1.2.1.jar lib

    3. Run the Oracle Identity Manager Upload JARs utility to post the ICF bundle org.identityconnectors.googleapps-1.2.1.jar file to the Oracle Identity Manager database.

      When you run the utility, you are prompted to enter the login credentials of the Oracle Identity Manager administrator, URL of the Oracle Identity Manager host computer, context factory value, type of JAR file being uploaded, and the location from which the JAR file is to be uploaded. To upload the ICF bundle jar file, specify 4 as the value of the JAR type.

  5. Run the Form Version Control (FVC) utility with the following fvc.properties for the UD_GA_USR parent form: 
    ResourceObject;GoogleApps User
FormName;UD_GA_USR
FromVersion;<FILL_OLD_VERSION>
ToVersion;<FILL_NEW_VERSION>

    Perform this step for child forms UD_GA_GROUP and UD_GA_NICK with their appropriate From Version and To Version values.

  6. Perform the procedures mentioned in Preinstallation on the Target System and Configuring the IT Resource for the Target System.
  7. Remove the mappings from the provisioning attribute map lookup definition, Lookup.GoogleApps.UM.ProvAttrMap and reconciliation attribute map lookup definition, Lookup.GoogleApps.UM.ReconAttrMap.

    • Provisioning attribute mappings:

      Sample 1:

      Code Key: UD_GA_NICK~Nick Name

      Decode: nicknames

      Sample 2:

      Code Key: Mail Quota

      Decode: quota

    • Reconciliation attribute mappings:

      Sample 1:

      Code Key: Nick Names~Nick Name

      Decode: nicknames

      Sample 2:

      Code Key: Mail Quota

      Decode: quota

  8. Open the file upgrade/PostUpgradeScriptGoogleApps.sql from the installation media and replace "DOMAIN.COM" with the configured value of Google Apps IT Resource parameter "domain" and execute the script in the Oracle Identity Manager database.

    Note:

    If the deployment does not have a requirement of using target user reconciliation, then the following steps can be skipped. However, in that case, updating the account name is also not supported. Hence, you must remove the "Account Name Updated Task" from the "GoogleApps User" process definition in order to stop account name updates.

  9. Go to the GoogleApps User resource object and change "Unique Id" to Not Required from Required. Also, set the "Account Name" field to Required.

    Save the resource object.

  10. Go to the GoogleApps User process definition and mark "Unique Id" from key field to non-key field. Also, mark "Account Name" as a key field.

    Save the resource object.

  11. Go to the GoogleApps User resource object and select the Create Reconciliation Profile option to create a reconciliation profile.
  12. Restart the application server running Oracle Identity Manager.
  13. Run a full target user reconciliation and ensure that all the existing Google Apps accounts in Oracle Identity Manager now have "unique id" as the long value instead of the account name value.

    For example, "118384305435185484147" will be replaced with "gatest".

  14. Revert the resource object and process definition changes performed in steps 7, 8, and 9 to ensure that the "Unique Id" and "IT Resource" fields are set as Key or Required reconciliation fields.