G Suite IDM Driver 4.2
Legal Notices
Concensus Consulting, LLC makes no representations or warranties with respect to the contents or use of this documentation, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Concensus Consulting, LLC reserves the right to revise this publication and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes.
Further, Concensus Consulting, LLC makes no representations or warranties with respect to any software, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Concensus Consulting, LLC reserves the right to make changes to any and all parts of Concensus Consulting software, at any time, without any obligation to notify any person or entity of such changes.
Any products or technical information provided under this Agreement may be subject to U.S. export controls and the trade laws of other countries. You agree to comply with all export control regulations and to obtain any required licenses or classification to export, re-export or import deliverables. You agree not to export or re-export to entities on the current U.S. export exclusion lists or to any embargoed or terrorist countries as specified in the U.S. export laws. You agree to not use deliverables for prohibited nuclear, missile, or chemical biological weaponry end uses.
Copyright © 2005-2022 Concensus Consulting, LLC All rights reserved. No part of this publication may be reproduced, photocopied, stored on a retrieval system, or transmitted without the express written consent of the publisher.
Concensus Consulting, LLC
2009 Mackenzie Way Suite 100
Cranberry TWP, PA 16066
Overview
The G Suite driver (Google Apps) for Micro Focus Identity Manager can create, update, and delete users, groups, organizational units, and contacts from an Identity Vault to the G Suite cloud application, keeping the user identity information consistent across the Identity Vault and the cloud application. The G Suite driver supports secure password synchronization across Identity Vault and G Suite cloud server. The G Suite driver for Identity Manager is a Subscriber channel only driver and offers out-of-the-box random password generation policy for the newly provisioned users. The G Suite driver uses a combination of language and protocols to enable identity provisioning and data synchronization between an Identity Vault with G Suite Driver.
Driver Concepts
Data Transfer Between Systems
IDM drivers support two data transfer channels between the Identity Vault and the connected system, called the Publisher and Subscriber channels. The Publisher channel handles data and events from the connected system into the Identity Vault. The Subscriber channel handles data and events from the Identity Vault into the connected system.
The G Suite Driver only supports data transfers from the Identity Vault into Google Apps. Communication is one-way only. Communication channels are discussed in the following sections.
The Publisher Channel
The Publisher Channel is not currently supported by this driver.
The Subscriber Channel
Monitors the Identity Vault for new objects and changes to existing objects.
Any relevant changes are sent to the shim to be executed in the Google Apps system.
Through the use of filters and policies, the driver can be configured to control and manage what changes are detected and sent to Google Apps.
How the Driver Works
The following diagram illustrates the data flow between Identity Manager and Google Apps API’s:
The Identity Manager engine uses XDS, a specialized form of XML, to represent events in the Identity Vault. Identity Manager passes the XDS to the driver policy, which can consist of basic policies, DirXML Script, and XSLT style sheets.
After driver policy has been applied, the driver shim communicates securely over https to the Google Apps API's for your domain. The results are then communicated back to the driver. The driver then processes that information converting it into an appropriate XDS that is reported back to the Identity Manager engine.
Understanding the Google APIs
Google has many different APIs available for managing data into and out of the many different Google applications. API Access must be turned on in the G Suite Admin Console. The driver supports the following APIs:
Directory API – The Directory API is responsible for creating users and group objects. It is required to turn this API on inside the G Suite Admin Console.
Contacts API * – The Contacts API creates a Domain Contact inside of the Address Book (Contacts).
Groups Settings API – The Groups Settings API provides enhanced control of permissions and other group attributes.
GMAIL API – Gmail user account settings, labels, forwarding, send as, and delegation
* NOTE: The Contact API Add events may not show in the G Suite Admin Console and Address Book (Contacts) for up to 24 hours even though they are usable objects right away. Modify events will show immediately.
Driver Features
The G Suite driver can use the local installation of Identity Manager or the Remote Loader Service. The driver can be installed on either Linux or Windows where the Identity Manager Engine or Remote Loader Service resides.
The following sections provide information about how the G Suite Driver supports these standard driver features.
Supported Operations
The basic configuration files for the G Suite Driver are capable of performing the following operations:
User Objects – Add, Modify, Delete, Query, Rename, Set/Change Password
Group Objects – Add, Modify, Delete, Query
Contact Objects – Add, Modify, Delete, Query
Organization Unit Objects – Add, Modify, Delete, Query
Entitlement Support
The driver has support for both RBE and RBPMs entitlements under Identity Manager 4.x. These entitlements may be used for User account, placement, and group membership.
Multiple E-Mail Domain Support
The driver is capable of managing multiple email domains within the same G Suite domain. It is, however, a best practice recommendation to use one driver instance per domain, even when the domains are within the same Google account. The one instance per domain model allows discrete IDV objects to be provisioned into each domain as per business requirements. When one instance is used for multiple domains, IDV objects, such as users, can only be in one domain at a time. Please see Appendix A – Multi E-Mail Domain Support on how to configure the driver.
Driver Installation
The driver is installed from a zip file that can be obtained from the Concensus Technologies download site. Please ensure you have obtained the most up to date version of the driver; earlier versions may not work properly due to Google API service changes since the media was created. It is also necessary to obtain a license from Consensus Technologies to activate the driver. The driver will not start without a valid license from Concensus.
Driver Requirements
The driver requires a supported version of Micro Focus Identity Manager. Currently Identity Manager versions 4.5 or later are supported. The driver is supported on Windows and Linux where Identity Manager is supported. The driver requires a patch and version level of IDM which provides at least a Java 7 (1.7) virtual machine.
A base configuration requires:
Driver license obtained from Concensus
Identity Manager Engine or Remote Loader system with access to the internet *
iManager with the Identity Manager plugins installed
Updated eDirectory Schema
Universal Password enabled on your eDirectory users
G Suite API Access must be turned on
* NOTE: The driver does not support connections to Google through an Internet Proxy Server. Port HTTPS/443 must be open from the driver system outbound.
Configuring Google Authentication
All the Google services used by the G Suite Driver are authorized using OAuth2 via a Service Account Flow. In order to use a Service Account credential, you must have an administrative user account available.
NOTE: Google frequently updates the user interfaces of their web consoles. Your screens may differ from the ones shown in this guide.
Creating a G Suite Administrative Account
In order to be able to configure OAuth2 and properly authorize a Service Account credential, a G Suite domain account with Super Admin access will be required. It is a recommended best practice to create and dedicate an account specifically for use by the driver. This allows for tighter controls and better auditing of domain events.
To create a new admin in the G Suite Domain:
Create a new admin user in the Google Admin Dashboard at https://admin.google.com
Click on the Users icon.
Add a new user.
Name the account something memorable and indicative of its role and purpose. Set or generate a password.
Make the new user a super admin.
Log into the G Suite Admin Console with the new admin user to confirm proper set up.
Accept the terms and conditions. The account will not work until this step is completed.
It is recommended to set up a recovery phone number and/or email address for this new admin account.
NOTE: It is necessary to log in to the admin console with the new admin user via a web browser at least once to fully activate the account. Until that step is done, the driver will not function.
Enabling the G Suite API Access
The driver will provision users, groups, organizations, and shared contacts into G Suite. It is necessary to enable API Access in your G Suite domain before the driver can perform its work.
To enable API Access in G Suite:
Using a web browser, log into the G Suite Admin Console. From the Dashboard select “Security.”
From the Security management page, select “API Reference."
Check the box labeled “Enable API Access.”
Configuring API and Service Account
NOTE: Google frequently updates the user interfaces of their web consoles. Your screens may differ from the ones shown in this guide.
The next step is to set up a developer project in the developer console. After creating the developer project, it is a recommended best practice to add additional administrators/owners of the project beyond the G Suite Driver account created earlier. This can prevent losing access to the project should changes be needed in the future.
Create Developer Project
Go to the Google developers console at https://console.developers.google.com. If possible, using a new tab on your browser is recommended. You should be logged in with the same admin account created earlier. Agree to the terms of service, if needed.
Create a new project within the developer's console.
Fill in the Project Name field. The Project ID field is generated by Google.
Click "Create." The new project may take 1 to 2 minutes to create.
Once the new project is created, there are several steps which must be performed:
Enable the relevant APIs
Create an OAuth ClientID
Create a service account
Enable Admin SDK API
Once the project is created, from the developer's console, proceed to enable the Admin SDK API. The Admin SDK exposes the majority of the necessary API endpoints that the driver needs. When this API is enabled, we will be given an opportunity to create the needed credentials for the connector.
From the project created in the previous step:
Select "Enable APIs and Services."
Scroll to the G Suite APIs, select View All, if needed.
Select and Enable the Admin SDK. The interface will prompt you to create credentials, which will be needed for the driver to connect to Google's servers.
Create Service Account Credentials
From the "create credentials" prompt in the Admin SDK panel, continue to create the necessary credentials for the driver to authenticate and obtain authorization to the G Suite domain.
Select "Create Credentials."
The G Suite driver uses the “service account” credential type. Select “service account,” skipping the wizard.
Click “Create Service Account.”
Give the account a relevant name and description.
Do NOT assign a role or permissions to the service account. Simply continue from the screen above.
There is no need to grant access to the service account. The driver uses a private key as the login credential, so it is necessary to create a key from this screen. Select "Create Key". This key is required for the driver to function.
Save the key in the P12 format. The key will download and be saved on your workstation. This is your ONLY copy of this key. The key cannot be redownloaded from the developer's console. If lost, a new key will need to be created for this service account. A new key can be recreated from the credential in the developer's console project, if needed. The P12 key file is the equivalent of the service account’s password and should be treated accordingly.
The key will need to be copied to the hosting machine which is running the driver.
Click done.
Locate the P12 file and upload it to your IDM server in a location accessible from the driver. /opt/novell/eDirectory/lib/dirxml/classes is a recommended location for Linux hosts. Generally, a good location is the same location as the gmailshim.jar file. If the driver is on a remote loader, then it needs to go with the gmailshim.jar file in the remote loader location.
NOTE: The location and filename of the key file is a necessary configuration parameter for the driver.IMPORTANT: On the service account details screen below, copy and paste the Email and Unique ID values into a text file for later use. The required data is highlighted below. These two values will be used to authorize the service account to access your domain via the various APIs used by the driver.
Managing Credentials and Keys
If you need to create or manage credentials after the fact, they can be accessed from the developer's console, in the project you created earlier. In the console, with your project selected, pull down the menu to IAM & admin and select service accounts as shown below.
From there, you can either create a new service account, manage your existing service account, or create new keys, as shown below.
Please refer to Google's developer console help system accessible from the question mark icon at the top right of the page for more information.
Enable Remaining APIs
The Admin SDK API is not sufficient alone for the connector to function. It is necessary to enable these additional APIs:
Group Settings
Contacts
Gmail
Follow these steps:
From the developer console dashboard (click the GoogleAPIs banner to easily reach this point).
Select Enable APIs. From the API Library, search for and enable Group Settings, Contacts, and GMailAPIs.
Return to the Enable APIs screen and search for “Contacts.” Enable the Contacts API.
Finally search for and enable the Gmail API.
Authorizing Service Account
The service account provides the driver with the ability to authenticate to the G Suite domain. It is necessary to grant that account permission to access your G Suite domain via the API service scope endpoints. For more information, please see the Directory API: Authorize Requests document available from Google.
NOTE: You will need the Unique ID of the service account which was created earlier. You will also need the API scope list provided with the driver. The scope list can be found in a text file called DirectoryScopes.txt. The scope list is a list of authorized scopes, which take the form of URLs, in a comma separated list, all in one line. The authorized scope list can also be found here and in Appendix E – Directory Scopes. Please use the most recent scope list as it may be updated in the future.
From the G Suite Admin Console, select the Security icon.
Scroll down and select “Advanced Settings.”
Select “Manage API client access.” Copy and paste the Unique ID of the service account into the "Client Name" field.
Copy and paste the contents of the DirectoryScopes.txt file (included with the driver download or accessible here or in Appendix E – Directory Scopes) into the "One or More API Scopes" field. Please note that the content should be plain text, so copy from a text file not from a web page to avoid any metadata.
Click Authorize.If this step was successful, the entry will appear in the authorized list similar to the image below:
If, for any reason, this does not work or you need to change the authorized scopes, delete the authorization entry and create it again with the correct information.
Configuring Driver Authentication
This section shows what information needs to be set in the IDM driver properties to use the service account. If you have not yet imported the driver configuration into Designer or iManager, then complete those steps first before attempting to set the service account information.
You will need the following information to configure the authentication settings:
Admin account email address and password for the G Suite domain
This is the one created first in this guide
Do not use your only admin account. Create one for the driver to use.
Service account Email Address
This should have been copied when the service account was created.
It can be found in the developer's console under service account details, as shown below:
Full path and file name of the P12 key file on the IDM server
This file was created as part of the credential process earlier in this guide
The file MUST be uploaded to the IDM server where the Google driver is running.
It is recommended that the file be placed in the same location as the ctgmailshim.jar file
On a Linux host, this location might be:
/opt/novell/eDirectory/lib/dirxml/classes/KEYFILENAME.p12
In IDM Designer or in iManager, edit the G Suite driver properties.
On the "Authentication" tab, set the following:
Authentication ID
The email address of the admin account
Connection Information
The domain name of this Google domain
Set Password
Set the password to the password of the admin account
The admin account is the actual identity used by the driver to effect changes in the domain. Once authenticated via the service account, the driver assumes the identity of the admin account and does the work via that proxy.
On the "Driver Parameters" tab, set the following:
Service Account Email Address
Set this to the service account email address from the service account created earlier.
P12 Private Key File
Set this to the precise path AND file name of the P12 file which was uploaded to the IDM server.
Use the hosting operating systems file and path correct syntax eg:
/path/filename for Linux
C:\path\filename for Windows
Finally, select “Ok” and update the driver in the Vault.
Driver File Installation
When installing the G Suite Driver on the target server for the first time, copy the zip file containing the G Suite Driver jar files to the target server running a compatible version of Identity Manager or Remote Loader.
In order to use the pre-configured import, you will need to extend the eDirectory schema using the following steps:
Windows:
Click Start > Settings > Control Panel > Novell eDirectory Services
Click install.dlm, then click Start
Click Install Additional Schema Files, then click Next
Log in as a user with administrative rights, then click OK
Specify the schema file path and name (<InstallDirectory>\Novell_Google_Schema.sch)
Click Finish
Linux:
/opt/novell/eDirectory/bin/ndssch -h <localhost:524> –t <MY treename> <admin_fdn> /opt/novell/eDirectory/lib/nds-schema/Novell_Google_Schema.sch
NOTE: The schema extension is the same as the Schema file included on the Micro Focus IDM install media.
It may be necessary to restart eDirectory once the driver binary and schema have been updated.
Windows:
Use services to restart your eDirectory Instance
Linux:
Consult eDirectory documentation
Driver License
The driver license file is sent to the technical contact listed on the software subscription license agreement. The technical contact will receive a zip file for each tree the connector is licensed for (typically a production and a test tree). The license will expire at the end of your contract term.
NOTE: The location for the license file will vary dependent on the version of IDM, the hosting operating system, and the options chosen during installation. Consult your IDM and eDirectory documentation for the correct path for your installation. The paths offered below are based on default selections and may not be correct.
To install the license, use the following steps:
Windows:
Unzip the file to a temporary location i.e. c:\temp
Copy the gmaillicense.jar file to the DirXML lib directory
IDM 3.6.1 – C:\novell\nds\lib
IDM 4.0 – C:\novell\identity manager\nds\lib
Later versions – C:\NetIQ\eDirectory\lib
Your location may vary
Restart eDirectory
Linux
Unzip the file to a temporary location i.e. /root
Copy the gmaillicense.jar file to:
/opt/novell/eDirectory/lib/dirxml/classes/
Your location may vary
Restart eDirectory (ndsd)
NOTE: When updating your license, you must remove the old jar file from the folder prior to installing the new one. Do not rename the old jar file. It must be removed such that it is no longer within the classpath of the IDM java virtual machine.
Driver Upgrades
If you are upgrading from a previous version of the driver, please follow the upgrade instructions indicating how to move from your deployed version to the new version. You will find the readme for the currently shipping version at the G Suite Driver Download page.
Replacing an Existing License File
Driver license files expire at the end of the contract term. They must be replaced each year as the driver will discontinue working (no events will be lost if the driver stops) at the end of the license term. The new license will be sent to the Technical Contact on the contract.
Once the new license has been obtained the following steps should be performed:
Windows:
Unzip the file to a temporary location i.e. c:\temp
Copy the gmaillicense.jar file to the DirXML lib directory and overwrite the existing jar file.
Default location (please verify in your installation) for IDM 4.x – c:\netiq\eDirectory\lib
Restart eDirectory on the server from the Services or Control Panel
Linux
Unzip the file to a temporary location i.e. /root
Copy the gmaillicense.jar file to the /opt/novell/eDirectory/lib/dirxml/classes/ folder and overwrite the existing jar file.
Default location (please verify in your installation)
Restart eDirectory
Consult eDirectory documentation
The expiration date can be seen in the driver trace at level 3 or higher:
Creating a New Driver Instance
The G Suite (Google Apps) connector uses IDM packages for initial driver configuration. Please refer to the Micro Focus documentation for IDM Designer for understanding and using Designer. This guide assumes familiarity with Designer and that you have a Designer project of your IDM environment into which the G Suite driver will be installed.
The G Suite driver may be obtained either from Concensus Technologies or Micro Focus. Use of the Concensus packages is not required; the Micro Focus and Concensus packages are identical in all functional ways.
Using Micro Focus Packages
You may use the Micro Focus version of the G Suite packages. If you use the Micro Focus packages, there is one change which needs to be be made from the Micro Focus packages to work properly with the Concensus driver.
After creating the driver instance, or updating an existing instance, open the driver properties in Designer as shown below.
The Concensus driver and the Micro Focus driver use different Java class names. Change the highlighted class name to reflect the Concensus driver.
Vendor | Java Class Name |
|---|---|
Micro Focus | com.novell.nds.dirxml.driver.gmailshim.GMailDriverShim |
Concensus | com.concensustechnologies.dirxml.driver.ctgmailshim.GMailDriverShim |
Please note that the Java class name is case sensitive and needs to be exactly as shown in the above table.
Once the class name is changed, save and deploy the change. The driver will now use the Concensus shim instead of the Micro Focus shim.
Using Concensus Packages
To use the Concensus packages within your designer, it is necessary to add the Concensus package repository to your Designer's online update sources. Note that the following screen shots may not match your version of Designer or future versions. Consult the Designer documentation for details.
From the "Window" menu, select "Preferences."
From the preferences panel, select Micro Focus, Package Manager, and Online Updates.
Press the green plus symbol to add a new source. The URL is https://www.concensus.com/designer.
After saving the changes, pull down the Help menu and check for package updates. Install the latest packages from Concensus to update your Designer.