Open Archiver

Appearance

Connecting to Google Workspace ​

This guide provides instructions for Google Workspace administrators to set up a connection that allows the archiving of all user mailboxes within their organization.

The connection uses a Google Cloud Service Account with Domain-Wide Delegation. This is a secure method that grants the archiving service permission to access user data on behalf of the administrator, without requiring individual user passwords or consent.

Prerequisites ​

  • You must have Super Administrator privileges in your Google Workspace account.
  • You must have access to the Google Cloud Console associated with your organization.

Setup Overview ​

The setup process involves three main parts:

  1. Configuring the necessary permissions in the Google Cloud Console.
  2. Authorizing the service account in the Google Workspace Admin Console.
  3. Entering the generated credentials into the OpenArchiver application.

Part 1: Google Cloud Console Setup ​

In this part, you will create a service account and enable the APIs it needs to function.

  1. Create a Google Cloud Project:

    • Go to the Google Cloud Console.
    • If you don't already have one, create a new project for the archiving service (e.g., "Email Archiver").

  2. Enable Required APIs:

    • In your selected project, navigate to the "APIs & Services" > "Library" section.
    • Search for and enable the following two APIs:
      • Gmail API
      • Admin SDK API

  3. Create a Service Account:

    • Navigate to "IAM & Admin" > "Service Accounts".
    • Click "Create Service Account".
    • Give the service account a name (e.g., email-archiver-service) and a description.
    • Click "Create and Continue". You do not need to grant this service account any roles on the project. Click "Done".

  4. Generate a JSON Key:

    • Find the service account you just created in the list.
    • Click the three-dot menu under "Actions" and select "Manage keys".
    • Click "Add Key" > "Create new key".
    • Select JSON as the key type and click "Create".
    • A JSON file will be downloaded to your computer. Keep this file secure, as it contains private credentials. You will need the contents of this file in Part 3.

Troubleshooting ​

Error: "iam.disableServiceAccountKeyCreation" ​

If you receive an error message stating The organization policy constraint 'iam.disableServiceAccountKeyCreation' is enforced when trying to create a JSON key, it means your Google Cloud organization has a policy preventing the creation of new service account keys.

To resolve this, you must have Organization Administrator permissions.

  1. Navigate to your Organization: In the Google Cloud Console, use the project selector at the top of the page to select your organization node (it usually has a building icon).
  2. Go to IAM: From the navigation menu, select "IAM & Admin" > "IAM".
  3. Edit Your Permissions: Find your user account in the list and click the pencil icon to edit roles. Add the following two roles:
    • Organization Policy Administrator
    • Organization AdministratorNote: These roles are only available at the organization level, not the project level.
  4. Modify the Policy:
    • Navigate to "IAM & Admin" > "Organization Policies".
    • In the filter box, search for the policy "iam.disableServiceAccountKeyCreation".
    • Click on the policy to edit it.
    • You can either disable the policy entirely (if your security rules permit) or add a rule to exclude the specific project you are using for the archiver from this policy.
  5. Retry Key Creation: Once the policy is updated, return to your project and you should be able to generate the JSON key as described in Part 1.

Part 2: Grant Domain-Wide Delegation ​

Now, you will authorize the service account you created to access data from your Google Workspace.

  1. Get the Service Account's Client ID:

    • Go back to the list of service accounts in the Google Cloud Console.
    • Click on the service account you created.
    • Under the "Details" tab, find and copy the Unique ID (this is the Client ID).

  2. Authorize the Client in Google Workspace:

    • Go to your Google Workspace Admin Console at admin.google.com.
    • Navigate to Security > Access and data control > API controls.
    • Under the "Domain-wide Delegation" section, click "Manage Domain-wide Delegation".
    • Click "Add new".

  3. Enter Client Details and Scopes:

    • In the Client ID field, paste the Unique ID you copied from the service account.
    • In the OAuth scopes field, paste the following two scopes exactly as they appear, separated by a comma:
      https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/gmail.readonly
    • Click "Authorize".

The service account is now permitted to list users and read their email data across your domain.

Part 3: Connecting in OpenArchiver ​

Finally, you will provide the generated credentials to the application.

  1. Navigate to Ingestion Sources: From the main dashboard, go to the Ingestion Sources page.

  2. Create a New Source: Click the "Create New" button.

  3. Fill in the Configuration Details:

    • Name: Give the source a name (e.g., "Google Workspace Archive").
    • Provider: Select "Google Workspace" from the dropdown.
    • Service Account Key (JSON): Open the JSON file you downloaded in Part 1. Copy the entire content of the file and paste it into this text area.
    • Impersonated Admin Email: Enter the email address of a Super Administrator in your Google Workspace (e.g., [email protected]). The service will use this user's authority to discover all other users.

  4. Save Changes: Click "Save changes".

What Happens Next? ​

Once the connection is saved and verified, the system will begin the archiving process:

  1. User Discovery: The service will first connect to the Admin SDK to get a list of all active users in your Google Workspace.
  2. Initial Import: The system will then start a background job to import the mailboxes of all discovered users. The status will show as "Importing". This can take a significant amount of time depending on the number of users and the size of their mailboxes.
  3. Continuous Sync: After the initial import is complete, the status will change to "Active". The system will then periodically check each user's mailbox for new emails and archive them automatically.