Provisioning the Google Apps Service Account for Schemus

Products

• Email Security.cloud

Issue/Introduction

Schemus authenticates to Google Apps with the OAUTH2 protocol, using the Service Account email address and associated private key as credentials.

Note that, although a Service Account is used for authentication, a separate Google Apps user account is required to access the group and user data.

Environment

Email Security.cloud

Resolution

There are a few prerequisites in order to have a successful synchronization :

1 - Before Schemus can retrieve data from Google Apps, you must sign up for a Google Apps account and create an administrator. Once created, the account is managed from the Admin console at  https://admin.google.com.

2 - API access must be enabled to allow Schemus to make requests to the directory API. Service accounts are added to a project, which should be created before configuring the service account.

3 - Enabling API Access

• From the Admin console (https://admin.google.com) click on Security, then click on API reference.
• Select the Enable API access checkbox if not already selected then click SAVE. Note that SAVE appears after a setting has been modified on the page.
  Note: If Security is not shown, click on MORE CONTROLS at the bottom of the page.
• Creating a project
• Create a new project on the Google APIs console at https://console.developers.google.com/project.
• Click on CREATE PROJECT at the top of the page. Choose a name for the project then Click Create.

4 - Service Account configuration

A Service Account can be created using the Google APIs console Credentials page at https://console.developers.google.com/projectselector/apis/credentials.

On the initial page, select the project created above then click Continue. On the API Manager page, select Credentials from the left pane then Click Create credentials in the main window. Select Service account key from the drop-downlist. Select New service account from the drop-down list then enter a name for the account. A role is not required.

Click Create to create the account and download the service account's key as either JSON or P12. Save the key to a location accessible by Schemus. If no role was selected, click CREATE WITHOUT A ROLE from the dialog to create the account and download the key. After downloading the key, click on Manage service accounts and make a note of the Service Account's email address.

Note: The email address and key file are required on the Google Apps settings page when configuring Schemus.

Make a note of the Client ID, which is used below to delegate authority to the Service Account.

Note: The Client ID will not be shown on the credentials or permissions pages unless domain-wide delegation is enabled. To enable domain-wide delegation on a service account click Manage service accounts then click the dots to the right of the service account entry under Actions and

select Edit. Click SHOW DOMAIN-WIDE DELEGATION then select Enable G Suite Domain-wide delegation and click Save.

 

5 - Enable the Admin SDK

The Admin SDK must now be enabled for the project to allow access to the directory information. On the Google APIs console page at https://console.developers.google.com/projectselector/apis, select the project then click Library and search for Admin SDK then click on Admin SDK from the search results then click ENABLE. Further information on Service accounts and OAUTH 2.0 is available on the Google developers site at https://developers.google.com/identity/protocols/OAuth2ServiceAccount

6 - Delegate authority to the Service Account

From the Admin console (https://admin.google.com) click on Security, then click on Advanced settings and Manage API client access.

Note: - If Security is not shown, click on MORE CONTROLS at the bottom of the page. - If Advanced settings is not shown on the Security page, click on Show more.

In the Client Name field enter the Service Account Client ID taken from the Google APIs console above.

In the One or more API Scopes field enter all of the scopes given below, separated by commas. Enter only the scope URLs, without the description.

Click Authorise

The table below lists the scopes, with a brief description

 Note: The scopes above provide read-only access to the data required by Schemus