Google Driver Authentication and Authorization Configuration Guide

Overview

The Google OAuth system was built with the concept that a human would be at a browser to authorize software to access the API at the time of access. Software such as the Google IDM connector requires a different setup for authentication and authorization. To accomplish this, it is necessary to enable the connector to authenticate to the API service with a service account, assume the admin permission via a designated admin account, and be pre-authorized to access the required API endpoints.

The steps needed to do this are:

1. Create a domain administrator in the Google domain to serve as the connector’s persona for domain activity

2. Create an API Developer project

   1. Owns the service account credentials

   2. Controls API end point activation

   3. Tracks API usage quotas

3. Create a service account in the API project

4. Grant permission in the domain for the service account to interact with the domain via the API REST endpoints

A note about Google’s administrative interfaces

Google changes the look and feel of their admin web interface on a regular basis. Sometimes the interface will be different for two different domains at the same time. An unfortunate result of this is that any set up guide which relies on screen shots or video will become rapidly out of date. The core process remains the same, however. Following the key steps listed above will result in a functional connection, even if the specific screens differ from what are shown in this guide.

Best Practices

When setting up the API project, be sure to add other secure accounts to the project to prevent losing access. Access to the API project is necessary to recreate the service account credential, enable new or different API end points, or manage the quotas or limits.

It is suggested that the IDM connector have its own API project to better manage credentials and API limits.

A note on parent and child Google domains

If your environment consists of multiple Google domains linked in a parent-child relationship, it is possible, even desirable, to create a single driver access account for use with all of the domains. For this to work, the domain administrator should be created in the parent domain and have the “super admin” permission granting it access to all child domains.

It is considered a best practice to create a separate instance of the IDM connector for each domain in your environment, one domain per driver instance. Each instance can use the same credential for access. Having a driver instance per domain allows an IDV account or group to be provisioned into each domain in the environment without issue. When a single driver instance connects to multiple domains, it is not possible to have a user object sync to multiple domains at the same time.

Setup

Creating a domain administrator

It is not recommended that your existing domain administrator account be used for this purpose. It is best to create a specific domain administrator account just for the use of the connector. This allows for better auditing and tracking of the administrator accounts in your domain. Further, it reduces potential issues if an account is accidentally disabled or deleted.

Log into the Google Admin Dashboard at https://admin.google.com using your domain admin account.

Create a new user to be used by the connector. It is recommended that the username be something indicative of the purpose of the account.

In the Users widget, click “add a user”

Open

OAuth1

Add a new user. It is recommended that the username indicate the purpose of the account.

Open

Create or automatically generate and store securely the account’s password. We will need to log into Google with this account to verify functionality and to create the API Project for the driver.

Make that new user a super admin (to manage all child domains)

Log into the admin dashboard with that user to confirm the proper set up. It is necessary to do this step to accept the terms and conditions. Without doing this step, the account cannot be used by the connector.

If you cannot log in with this account and access the admin dashboard, then the connector will not work with this account. If desired, setup a recovery phone number and/or email address and complete the login.

Record the login information in a secure manner for future use.

Create API Project

The next step is to set up an API project in the Google cloud console. The console may be reached at https://console.cloud.google.com

Note: This used to be called the developer’s console.

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. If you’re not logged in, it is recommended that you use the same admin account you created earlier. Be sure to add your primary admin account(s) as additional owner(s) to the API project to protect access to the API project.

If this is the first login to the API Cloud console for this account, you may see a welcome message like this. Accept the terms of service.

From the “Select Project” drop box in the upper left area, select New Project.

You can select a name for the project or go with the suggested name. The name has no functional role in the connector’s function. This project has been named to describe its purpose.

Create the project. It may take a few minutes to complete. When it does, you should get an on-screen notification like this one. Select the project.

The main project screen is shown below.

If you wish to add additional accounts as administrators, or other roles, the “Add people to this project” link in the “Project Info” panel will let you do that.

Note the API information panel. This will show the metrics on how your IDM connector is using the APIs. There are limits on transactions per unit time for the API interfaces. Please refer to Google documentation for the current API limits. It is rare for an IDM integration to hit any API quota limits.

Enable APIs

From the project screen, APIs & Services menu, select Enabled APIs & Services.

Make note of the credentials menu item, it will be used shortly to create the service account credential for the driver to use.

At the top of the APIs & Services page, select the + ENABLE APIS AND SERVICES link.

The API library lists all of the Google APIs that can be used by various applications through this project. The APIs that are needed for the IDM Google connector are found under the Google Workspace section.

Scroll to the Google Workspace section. Alternatively, you could search in the search box for the necessary APIs.

The specific APIs are:

• Admin SDK API

• Groups Settings API

• Gmail API

• Contacts API

  • This API is shown as no longer in development. The connector will transition to the People API in the future, however, it is necessary to enable this API for now.

  • You will need to search for this API, it will not be listed in the Workspace section.

Select each API in turn and enable them. The Admin SDK API is shown here. The other APIs will be very similar.

The API will take a few moments to create. Once it does, you will see the Service Details view of the API. We will use this view as a simple way to create the credentials for the connector.

Click the “Create Credentials” button shown above to start that process. You can also click the ‘credentials’ menu on the left to do the same thing at any time.

Either create credentials or enable the rest of the APIs listed above.

Creating Service Account

Creating the credentials will result in a service account which can be used by the connector to authenticate to the Google API services and to your Google domain.

Use the Admin SDK API in the API selection. The connector does NOT access a specific user’s data and will not require an OAuth client. Select the “Application Data” option to create a service account.

Select “No” on the question about using the API with Compute Engine, etc. Continue with “next”

Fill out meaningful values for the service account name and description and create.

The account will not need access to the project nor will any users need access to the service account. Click done to finish creating the service account.

Navigate to the credentials section using the menu on the left to view the credentials available.

Note the create credentials link at the top. This can be used to create the service account if the method described earlier was not used.

The service account created earlier is shown at the bottom. Select it.

The IDM Google driver uses a service account key to authenticate to the Google servers. It is necessary to create a key for it to use. Select Keys.

Create a new key.

Create a key using the P12 download format. The IDM Google. connector reads the P12 file for the credential to authenticate.

Once the key is created, it will download automatically to your computer. Keep the key file secure.

The key file will need to be uploaded to the IDM server hosting the Google driver. The file must be in a location accessible to the IDM Google connector on the server’s filesystem. The typical location would be in the same location as the shim JAR file itself.

If necessary, the key can be deleted (which will invalidate the p12 file) and a new one generated.

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.

Please record the path and filename of the p12 file in a text document to be used to configure the IDM Google connector!

To authorize the service account to access your Google domain, we will need the service account email address and unique ID which can be found on the details view of the service account as shown below.

Copy and paste both the email and unique id values into a text file for use in configuration and authorization!

If you have not already done so, enable the remaining APIs. Failure to enable all of them will result in the Google driver failing to start with an error as it attempts to establish a client instance to each API endpoint.

Authorize Access

After the API project is created, the relevant APIs are enabled, and a service account created, the final step is to authorize the service account to access the domain through the domain wide delegation setting. This setting uses the unique identifier of the service account along with the defined scopes which will be used by the account to pre-authorize access without prompting.

To do this, access the Google domain admin control panel as a domain administrator. https://admin.google.com

From the left menu, access Security, Access and data control, API controls.

Select Manage Domain Wide Delegation

The above screenshot shows a domain with many provisioned service accounts, please disregard them.

For the next step, you will want to find and open the DirectoryScopes.txt file provided with the driver. It should be in the same location as the driver shim. The scopes are listed in this document as well. You will want to have them ready in a comma delimited text document to be copy and pasted into the authorization form field when we delegate access to the service account.

Select to add a new API client.

The Client ID is the service account unique ID. The OAuth scopes are the scopes from the domain scopes file or from this document. They should be all on one line with comma separation.

You should see the API client show in the list after the authorization step is completed.

Here are the scopes to be authorized:

Here are the directory scopes as used in the security authorization. They need to be entered all on one line, comma separated into the OAuth scopes box. Use the code-snippet box below for easier copy/paste of the scopes.

Configuring the IDM Google Driver Authentication

In IDM Designer or in Identity Console, edit the properties of the IDM Google Driver.

In the Authentication tab, set the AuthenticationID to be the domain admin account created earlier. There is no need to set a password for it (the service account p12 key file handles authentication to the domain as the service account).

Set the connection information to be the domain name.

On the Driver Parameters tab, set the service account email address and the full path and file name for the p12 file you uploaded earlier.

Deploy the configuration (or save it in Identity Console) and test.