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

5.7.2 Google Apps Module Setup

All configuration required is now complete in Google Apps, and the information and files keys are available for configuration of Retain.

5.7.3 Core Settings Tab

Once Google has been configured to allow access to Retain, the Google Apps Module may be configured.

The module needs to be enabled on this page to make it active in the Retain system.

The module can be given a name.

The Send Method option enables either the SMTP Forwarding or FTP features. For either feature to appear and function, the Module Forwarding tab must be configured on the Server Configuration page. See that section for more information.

The Send Method option enables either the SMTP Forwarding or FTP features. For either feature to appear and function, the Module Forwarding tab must be configured on the Server Configuration page. See that section for more information.

Address book caching must be enabled to gather and maintain an updated list of users. Authentication is used to allow access to the Retain message store for users based on their existing Gmail account login. If the Enable Jobs option is not enabled, no jobs may be completed with the Google Apps module.

5.7.4 Settings Tab

In order to connect to the Google system, Retain requires the email address of the Admin user OAuth Service Account and a p12 Certificate for authentication. Retain archives the Gmail system through IMAP, and will login and download the message data to the Retain data store.

Test the connection to ensure that the configuration has been completed correctly.

Jobs and profiles for Gmail will not be visible until the address book has been cached. After the module has been cached, all configuration options for profiles, workers, schedules, jobs and data storage will be enabled and visible.

5.7.5 OpenID Tab

Configure the OpenId Connect tab in Retain by inputting the Client ID, the Client Secret, and the Public RetainServer URL and saving changes. NOTE: The public RetainServer URL should look something like http://<yourdomain.com>/RetainServer. Only specify to the ".../RetainServer" portion of the URL, the rest is automatically filled-in. Specifying the complete URL will result in a connection error.

If Retain has been configured with OpenId credentials, the login page will display an option to login with Google credentials. If a user is currently logged-in to their Gmail account, simply clicking the "Login with my Google account" button will automatically log them into Retain.

5.7.6 Next Step

Configure a job Google Apps Jobs.