This guide walks you through setting up a Google Workspace identity integration. This entails creating a service account, configuring domain wide delegation for the service account, and downloading the credentials for the service account to access necessary fields to authenticate with the Google Workspace API.

Before You Begin

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

You need to already have access to the Google Workspace Admin Console and you must have a Google Workspace account (not necessarily the same one that you log in to the admin colse with) set up that you will use with domain-wide delegation. This account should have the following permissions:

You will also need to have access to the Google Cloud Console.

1. Create a Service Account

Follow the Manually create a service account section from this guide to create a new service account. If you don't already have a Google Cloud Console project, you will need to create one; instructions are included in the linked guide. The Cloud Console project will need to have access to the Admin SDK API. If you are using an existing project and need to enable access to the Admin SDK API, you can use this page to do so.

2. Set up Domain Wide Delegation

You can use this guide to learn how to set up domain wide delegation. When prompted for the OAuth scopes to enable for the delegation enter the required scopes separate by commas with no spaces or newlines.

Recommended scopes list:

For convenience, here are the scopes listed in the table above in the correct format to copy-paste into the domain wide delegation setup dialog: https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/admin.directory.group,https://www.googleapis.com/auth/admin.directory.user,https://www.googleapis.com/auth/admin.directory.user.security,https://www.googleapis.com/auth/admin.reports.audit.readonly

If you need to limit the permissions granted to the service account, https://www.googleapis.com/auth/admin.directory.group.readonly may be used instead of https://www.googleapis.com/auth/admin.directory.group, similarly https://www.googleapis.com/auth/admin.directory.user.readonly may be used instead of https://www.googleapis.com/auth/admin.directory.user. https://www.googleapis.com/auth/admin.directory.user.security may be omitted. Operations that would require modifying users or groups will not work if the .readonly scopes are used. Expire All Sessions will not work without the .security scope.

3. Download the Service Account Credentials

In the Google Cloud Console, navigate to IAM & Admin > Service Accounts, then select the service account you created in step 1. Open the "Keys" tab, and select "Add Key" > "Create new key" > JSON. This will create the key and download it automatically. Protect this key file, as it allows access to your Google Workspace account via delegation.

4. Extract the Service Account Credentials

Make a note of the following fields from the downloaded key file: client_id, private_key, token_uri, and client_email.

Consider the following example key file:

{
        "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
        "client_email": "EXAMPLE@EXAMPLE.iam.gserviceaccount.com",
        "client_id": "1234567890",
        "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/EXAMPLEt%40EXAMPLE.iam.gserviceaccount.com",
        "private_key": "-----BEGIN PRIVATE KEY-----\nKEY MATERIAL HERE-----END PRIVATE KEY-----\n",
        "private_key_id": "1234567890",
        "project_id": "example-project-id",
        "token_uri": "https://oauth2.googleapis.com/token",
        "type": "service_account",
        "universe_domain": "googleapis.com"
}

In this example...

• client_id is 1234567890
• private_key is -----BEGIN PRIVATE KEY-----\nKEY MATERIAL HERE-----END PRIVATE KEY-----\n
• token_uri is https://oauth2.googleapis.com/token
• client_email is EXAMPLE@EXAMPLE.iam.gserviceaccount.com

5. Configure the Integration

Create your integration by supplying all of the required and any desired optional values.

Client Email: This is the client_email value gathered in step 4.

Client ID: This is the client_id value gathered in step 4.

Client Secret: This is the private_key value gathered in step 4.

Delegate: This is the email address of the user you are delegating access to.

Extra > OAuth Scopes: If you chose to use scopes other than recommended ones in step 2, make sure the scopes listed in this section exactly match your choices.

Optional Fields

Token URL: This is the token_uri value gathered in step 4.