5.12 Google Apps Module

The Google Apps module for G Suite allows Retain to archive Gmail data items. To configure Retain for Gmail archiving, Retain needs Gmail to be configured to allow Retain access, and the appropriate information entered into Retain.

Google Apps requires that a project be created, an OAuth key created and a Service Account specified and enabled before the Retain system can connect and archive mail.

To archive from Google Apps:

  • Create a project

  • Create a new Client ID key

  • Record client secret

  • Create a Service Account and Manage API Client Access

  • Generate a P12 key certificate

5.12.1 Prerequisite

Retain supports two-factor authentication with OpenId Connect for OAuth 2.0. To utilize OpenId the Retain Server needs to be accessible from the Internet. The URL through which the Retain Server is accessible from the internet must be specified. For this, you must create a Project and Client ID.

NOTE:As a cloud service these screens may change at anytime.

To configure OpenID for Retain use:

  1. Go to the Google API Console, and select 'Create a project'

  2. In the sidebar under "API Manager", select 'Credentials' and then select 'OAuth consent screen tab

  3. Choose an 'Email Address', specify a 'Product Name', and press 'Save'

  4. In the 'Credentials' tab, select the 'Create credentials' drop-down list, and select OAuth client ID

  5. Under 'Application type', select 'Web application' and Specify a name. The origin field should be the Retain Server's URL.

    If using two-factor authentication for GMail login, enter an Authorized redirect URL (e.g. http://retain.gwava.com/RetainServer/Server/openIdConnect.jsp?).

    When complete, select the 'Create' button.

  6. The OAuth client dialog box should be displayed. This dialog box contains the Client ID and Client secret.

    • Copy the Client ID and paste it into the Retain Client ID field in the Google Apps module configuration. Do not lose the client secret.

    • OAuth access requires the secret and ID. This is the only time the secret will be displayed.

    To attain the client secret for an existing project:

    1. Select the Web Client and click the Edit OAuth Client button

    2. Copy the Client ID and Client Secret which is required to configure OpenId tab for Google apps module.

      The OAuth Client needs to be enabled for domain-wide delegation to function. To enable domain-wide delegation, Retain requires a service account.

  7. From the Products and Services hamburger menu at the top-left: Select IAM & Admin

  8. Select the 'Service Accounts' and click the 'Create service account' button

  9. Configure the Service Account Name and ID. No Role is needed.

    • Select the option to Enable Google Apps Domain-wide Delegation.

    • Enable "Furnish a new private key" and select the P12 file.

    • Copy the Service Account name and ID. These are required by Retain.

    • Click 'Create'.

    The key will be automatically created and downloaded to the local machine. Do not lose the P12 file. This is the only copy and it is required to configure Retain.

  10. You will need the Client ID from the Service Account

  11. Go back to the API manager and enable: Calendar API, Gmail API and Admin SDK. Click on each one and click Enable on top.

  12. The last step is to authorize the domain. Browse to the Google home page and select 'Admin' from the drop down menu at the top right.

  13. Select 'Security' from the administration menu.

  14. From the Security menu, click 'Show More'

  15. Select the 'Advanced Settings' option.

  16. On Advanced Settings, select 'Manage API client access'

  17. In this window, enter the client ID created with the service account, and then input the entire domain the client will be accessing.

    The Service Account name would be like Retain-Service as above and the API Scopes (listed in the module) would be:

    https://mail.google.com/ , https://www.googleapis.com/auth/admin.directory.group ,https://www.googleapis.com/auth/admin.directory.user ,https://www.googleapis.com/auth/gmail.readonly

  18. Once entered, click 'Authorize'.