/
Google Apps Driver 4.1.2.0

Google Apps Driver 4.1.2.0

May 02, 2017

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 © 2015 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

103 Fox Trot Drive

Mars, PA 16046

www.concensus.com

Overview

 

The Google Apps driver for Novell Identity Manager can seamlessly provision and de-provision users, groups, organizational units, and contacts to the Google Apps cloud application keeping the user identity information consistent across the Identity Vault and the cloud application. The Google Apps driver supports secure password synchronization across Identity Vault and Google Apps cloud server.  The Google Apps 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 Google Apps driver uses a combination of language and protocols to enable identity provisioning and data synchronization between an Identity Vault with Google Apps Driver.

Understanding the Google API's

Google has many different API’s available for managing data into and out of the many different Google applications.  API Access must be turned on in the Google Apps Control Panel.  The 4.0.4 driver supports the following API’s:

  • Directory API – The Directory API is responsible for creating users and group objects.  It is required to turn this API on inside the Google Apps control panel.

  • Contacts API* – The Contacts API creates a Shared Contact inside of the Address Book (Contacts).

  • Groups Settings API - The Groups Settings API provides enhanced control of permissions and other group attributes.

  • EMailSettings API – The email API allows modification to the default behavior (as set in your Google apps domain) for items related to email. 

* Note - The Contact API Add events do not show in the Google Apps Control Panel 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 Google Apps 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 Identity Manager Engine or Remote Loader Service resides. 

Supported Operations

The basic configuration files for the Google App 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 Google Apps domain.  Please see Appendix B - Multi E-Mal 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.  It is also required that a license be obtained from Concensus Technologies.  The driver will not start without a valid license from Concensus.

Driver Requirements

The driver requires a supported version of Novell Identity Manager.  Currently Identity Manager 4.0.x and 4.5 are supported.  The driver is supported on Windows and Linux where Identity Manager is supported.

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

  • Google Apps 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 of the Google services used by the Google Apps 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.

Creating a Google Administrative Account

In order to be able to configure OAuth2 and properly authorize a Service Account credential, a Google Apps account with Super Admin access will be required.

To create a new admin in the Google Domain:

  1. Using a web browser, log into the Google Apps Administration Console

  2. From the Dashboard select Users

  3. Click on the green circle in the bottom left corner with a +.  It will display 3 options.  Click 'add user'.

  4. Enter First Name and Last Name.  Set a password and additional info as desired.

  5. Click Create to create the new user.

  6. Search for your new User ID in the list of Users and select it.

  7. Scroll down and select Show More.

  8. Scroll down to Admin Roles and Privileges heading and click expand it

  9. Click on the Manage Roles button

  10. Click on the Super Admin checkbox  and push Update Roles

  11. Log out of the Google console and log back in using the new user ID. 

Note: that if you skip the last step the driver will be unable to start.  The driver is unable to respond to a CAPTCHA request. 

Enabling the Google API Access

The driver will provision users, groups, organizations, and shared contacts into Google Apps.  It is necessary to enable API Access in your Google Apps domain before the driver can perform its work.  

To enable API Access in Google Apps:

  1. Using a web browser, log into the Google Apps Administration Console

  2. From the Dashboard select “Security”

  3. From the Security management page, select “API Reference”

  4. Check the box labeled “Enable API Access”.

Configuring OAuth2

 

Note: The Developer's Console changes frequently as Google implements new features or rolls out updates to various accounts. Your view may differ from the screen shots shown below.

 

Creating a Google Service Account

  1. Go to Google Developers Console 

  2. Click on Create Project button

  3. Fill in the Project Name field.  The Project ID field is generated by Google.  It must be unique across the entire Google namespace.

     

    1. Click 'Create'

    2. The new project may take 1 to 2 minutes to create

  4. Once the new project has been created, the Developers Console will display options for the new project.

  5. Click on Enable and manage APIs 

  6. Click on Admin SDK under Google Apps APIs

    1. Click on Enable API

    2. Note the warning displayed indicating the Admin SDK cannot be used until credentials are created.  

  7. Click on Go to Credentials to create credentials now.

     

    1. The Google Apps driver accesses the Google Admin SDK via a Service Account Credential.  Click on the service account link under Find out what kind of credentials you need.

    2. Click on Create service account.  The Create service account screen is displayed.

    3. Enter the name you want to use for the service account.  Note that Google automatically populates the value of the Service Account ID.  You will need to save the value of the Service account ID for configuring the driver.

    4. Check the box for Furnish a new private key and select P12 as the key type.

    5. Check the box for Enable Google Apps Domain-wide Delegation.  

    6. Enter a value for Product name for the consent screen

    7. Click Create.

    8. As part of the service account creation process, Google creates and downloads the P12 file for your account to your computer.  Please verify that a file with the name shown in the confirmation screen exists in your browser's download folder.  

    9. Press Close.

    10. The service account is created and Google shows the Permissions screen for Service Accounts.  You will need to have the Email address shown on the Permissions screen when configuring the driver.  

    11. Click on View Client ID.

    12. You will need the Client ID value when delegating Domain-wide Admin access below.

    13. Click on Manage service accounts.  The Permissions screen will be displayed.

    14. The Service accounts tab is selected.  Select the Permissions tab.

    15. Note the warning that the new project has only one owner.  Click on Add member to add another owner.

    16. Enter the email address for the Google account to be added as an owner.

    17. Click Add.

    18. Return to enabling APIs required by the Google driver.  To do this click on the three horizontal lines to the left of Google Developers Console.

    19. Select API Manager.

  8. Continue enabling Google APIs

    1. Select Contacts API  from Google Apps APIs.

    2. Select Enable API.

    3. Click on Overview to return to the list of Google APIs.

    4. Search for the Groups Settings API by typing Groups in the Search all 100+ APIs control.

    5. Select Groups Settings API from the list of results.

    6. Click on Enable API

    7. The Service account credential to be used by the Google Driver is now created and the APIs required by the Google Driver have been enabled.



Delegate Domain-wide Administrative rights to Google Service Account

 

  1. Go to the Google Administrative Console

  2. Click on the Security icon

  3. Click Advanced Settings.  If Advanced Settings isn't visible, click Show More.

  4. In the Advanced Settings tab, click Manage API client access under the Authentication tab.

  5. Enter the value for Client ID from the Service Account credential  in the Developers Console in the Client Name field.

  6. Enter the list of scopes to authorize for the driver.  The list of scopes is shown below, as well as provided with the driver files in DirectoryScopes.txt that comes in the Google Apps Driver download package.

    1. https://www.googleapis.com/auth/admin.directory.group, https://www.googleapis.com/auth/admin.directory.group.member, https://www.googleapis.com/auth/admin.directory.orgunit, https://www.googleapis.com/auth/admin.directory.user, https://www.googleapis.com/auth/admin.directory.user.alias, https://www.googleapis.com/auth/admin.directory.user.security, https://www.googleapis.com/auth/admin.directory.userschema, https://www.googleapis.com/auth/admin.directory.userschema.readonly, https://www.googleapis.com/auth/userinfo.profile, https://www.googleapis.com/auth/userinfo.email, http://www.google.com/m8/feeds, https://www.googleapis.com/auth/contacts.readonly, https://www.googleapis.com/auth/apps.groups.settings, https://apps-apis.google.com/a/feeds/emailsettings/2.0/

  7. Click Authorize.  Your credentials are ready to use.

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 Google Driver Download page.

*Note: gmailshim.jar has been renamed to ctgmailshim.jar.  The Google Driver from Novell (OEM’d from Concensus) is named gmailshim.jar and has a different licensing model.  Be aware that if you have installed the Novell Google Driver it will have overwritten your Concensus shim.

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 that 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 file

      • (Default location, please verify in your installation) IDM 4.x – C:\novell\identity manager\nds\lib 

    • Restart eDirectory on the server from the Services or Control Panel

  • Linux

    • Unzip the file to a temporary location i.e. /root

    • (Default location, please verify in your installation) Copy the gmaillicense.jar file to /opt/novell/eDirectory/lib/dirxml/classes/ folder and overwrite the existing jar file. 

    • Restart eDirectory – rcndsd restart

The expiration date can be seen in the driver trace at level 3 or higher:

Driver File Installation

  • If you are installing the Google Apps Driver on the target server for the first time, copy the zip file containing the Google Apps Driver jar files to the target server running a compatible version of Identity Manager or Remote Loader.

  • 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 Google Driver Download page.

 

  In order to use the pre-config import you will need to extend the eDirectory schema using the following steps:

  • Windows: 

  1.  

    1. Click Start > Settings > Control Panel > Novell eDirectory Services

    2. Click install.dlm, then click Start

    3. Click Install Additional Schema Files, then click Next

    4. Log in as a user with administrative rights, then click OK

    5. Specify the schema file path and name (<InstallDirectory>\Novell_Google_Schema.sch)

    6. Click Finish

       

  • Linux:

  1.  

    1. /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 Novell IDM 4.0.1 Install DVD.  It is not installed by the IDM 4.0.1 installer by default.  These schema files will be kept in sync by Novell and Concensus. 

3. 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:

    • /etc/init.d/ndsd restart

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.  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

  • Linux

    • Unzip the file to a temporary location i.e. /root

    • Copy the gmaillicense.jar file to /var/opt/novell/eDirectory/lib/dirxml/classes/ folder

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.

Driver Import

The driver can be imported through Designer or iManager.  Concensus prefers Designer (to download visit: https://www.novell.com/coolsolutions/dirxml/designer or off of the IDM product DVD) and will document the steps here.

  1.  

    1. Launch Designer and open your project or create a new project.

    2. Create a new driver by right clicking on the  

         icon and choosing new/driver from the menu.

    3. From the Driver Configuration Wizard/Select Base Configuration select the  button.

    4. Then click browse and select the GoogleApps-IDM3_6_1-V8.xml file from the GoogleISO\iManager folder on your CD-ROM drive and click run to begin the import.

    5. From the Import Information Requested screen fill out the following information:

      1. Driver Name – This is the driver name.  It defaults to Google Apps

      2. Authentication ID – Admin account User ID

      3. Google Domain Name:  This is the name of the Google Apps domain (primary email domain).  This is used by the driver to connect to your Google Apps domain: https://www.google.com/a/mydomain.com

      4. Password – The password is not required or used by the Google Driver.  Leave this blank.

      5. Service Account Email Address:  This is the Service Account Email Address created in the Google Developer Console.

      6. P12 Private Key File:  The path and file name of the .p12 credential file created with the Service Account credential in Google Developer Console.

      7. Override JAXP Factory?:  Set to true to have the driver override the default setting for the system property javax.xml.parsers.SAXParserFactory with the value org.apache.xerces.jaxp.SAXParserFactoryImpl.   

      8. Publisher Heartbeat Interval:  If you have policies which need to fire periodically on the publisher channel, set the hearbeat interval value here.   The driver will send a heartbeat message to the Identity Manager engine each time the interval expires.

      9. Hash passwords before sending them to Google:  Set this value to true to cause the driver to hash passwords being set on Google users.

      10. Hit Next to continue to fill out general parameters.

  1. Select Close on the Import Configuration screen. 

  2. Save your project in designer

  3. The driver import is now complete.  You should continue to the driver customization section to continue your setup.

  4. Once the driver is configured you need to deploy it using designer and give the driver the correct rights in the tree.  Please refer to the Novell IDM documentation on how to use designer to deploy a driver.

Driver Customization

The IDM driver for Google Apps can be customized using Novell iManager or Designer.  The pre-configuration file used for import is only a template.  With an understanding of Identity Manager policy and xslt you can configure the driver to do just about anything the Google API’s will allow you to do.  For examples please review the other Identity Manager driver configuration files and Novell Cool Solutions. 

This section will document the items in the pre-configuration file. 

Driver Properties

The Driver Properties page (Right click on the driver in designer and choose properties from the menu) contains all of the items that the driver needs to startup and connect to Google. 

Driver Configuration

Driver Module tab

  • This tab sets the Java class name or allow configuring for remote loader.

Authentication tab

  • Application ID: The account for the Google user ID used by the driver

  • Connection Information: The domain name of the Google Apps domain.

  • Set Password:  The driver uses OAuth2 for authorization.  Do not set a password here.

  • If you are configuring the remote loader you set up that authentication information here.

Startup Option

  • Auto start: The driver will start when the eDirectory server starts

  • Manual:  The driver will start only from user interaction in iManager or Designer

  • Disabled:  The driver will not start, and no events will be cached for the driver.

Driver Parameters

Driver Options

  • Service Account Email Address:  Email address associated with the Service Account credential created in Google Developers Console

  • P12 Private Key File:  Path and filename of credential file associated with Service Account credential created in Google Developers Console.

Subscriber Options

  • Hash passwords before sending them to Google:  Set this value to true to cause the driver to hash passwords being set on Google users.

Publisher Options

  • Publisher Heartbeat Interval:  If you have policies which need to fire periodically on the publisher channel, set the hearbeat interval value here.   The driver will send a heartbeat message to the Identity Manager engine each time the interval expires.

GCVs

Account Tracking tab

  • Account Tracking is documented by 

Managed System Information tab

User Settings tab

  • Entitlement settings for User objects

  • RBPMS Settings

Groups Settings tab

This tab is currently not used by the driver config

Google Config tab

  • Google Apps Primary Domain Name:  This is the domain name of the primary Google Apps domain the driver is connecting to.

  • Google Apps Secondary Domain Names:  This is a list of secondary Google domain names the driver can service

Password Settings tab

  • Google Apps Password Settings configures how passwords are generated for new users being created in Google Apps.

    • You can select using a random password, specifying how many characters and numbers are required.

    • You can select using a value from an existing attribute.

  • Password Synchronization configures policy configurations around how passwords are synchronized from the ID Vault to Google Apps for a given user.

OU Settings tab

  • User placement settings:  This variable controls placement policies to not generate placement, use Mirrored placement, or Entitlement based placement.

  • Advance RBPM Settings.  

The last tab in the list named using the driver name, and is intended to be a bucket for administrators to place their own GCV definitions.

Trace 

  • Trace Level – For normal production use this value should be set to 0.  For driver testing and debug information set this to trace level 3.  Trace level 5 is used to dump more information about the driver operations between Google Apps and the Driver Shim. 

  • Trace file – If you are tracing you should set the path and name of the file you want to trace to. For example /var/log/googleappsdriver.log.  If you set this option please be sure to set the Trace file size limit as it defaults to Unlimited. 

  • Trace file encoding – Recommended not to change from default settings

  • Trace file size limit – Typically set to no more than 1024 MB.

  • Trace name – Typically set to GoogleApps.  This is not a required entry.

Driver Filter

The driver supports Contacts, Users, Groups and Organizational Units classes.  For the User and Contact the following table will list the default list of attributes.  These classes support many more attributes that can be found by refreshing the application schema and mapping them to an eDirectory attribute in the schema mapping rule.

Class

Attribute

Notes

OrganizationUnit

Description

 

 

OU

This   is the naming value of the attribute

 

 

 

Group

Member

 

 

Owner

 

 

CN

Required

 

DirXML-GAGroupEMailAddress