Skip to main content

Google Workspace (formerly known as G Suite)

This guide covers the basics of setting up Pomerium to use GCP and Google Workspace / G Suite as your identity provider.

caution

Google changes their configuration screens frequently. Please refer to Google's documentation for authoritative instructions.

Setting up OAuth 2.0​

You need OAuth 2.0 credentials, including a client ID and client secret, to authenticate users.

Create OAuth 2.0​

Log in to your Google account and go to the APIs & services.

  1. Navigate to Credentials using the left-hand menu. If you're not already in a project, you can select one here.

  2. On the Credentials page, click Create credentials and choose OAuth Client ID.

    Create New Credentials

    caution

    If you don't currently have an OAuth consent page configured, Google will not allow you to create credentials until this is completed. Please follow Google's instructions for doing so.

  3. For the Application type choose Web application.

  4. Give the client ID a Name, and add an Authorized redirect URI. The redirect URI format is https://${authenticate_service_url}/oauth2/callback (e.g.https://authenticate.localhost.pomerium.io/oauth2/callback).

    Web App Credentials Configuration

    Click Create once complete.

  5. The Google Cloud Console will display your Client ID and Client Secret. Temporarily save these values to import into Pomerium later.

    Google's OAuth client ID and Secret displayed

Setting up directory Sync​

Create a service account​

In order for Pomerium to validate group membership, we'll also need to configure a service account with G-suite domain-wide delegation enabled.

  1. Open the Service accounts page. If prompted, select a project.

  2. Click + Create Service Account, enter a name and description for the service account. You can use the default service account ID, or choose a different, unique one. When done click Create and continue.

  3. The next sections, labeled Grant this service account access to project and Grant users access to this service account, are not required. Click Continue to both, and then Create.

  4. Select your new service account, and click on the KEYS tab. Select Add key, then Create new key:

    Creating a new key for a Google service account

    In the side panel that appears, select the format for your key: JSON.

  5. Click Create. Your new public/private key pair is generated and downloaded to your machine; it serves as the only copy of this key. For information on how to store it securely, see Managing service account keys.

  6. Click Close on the Private key saved to your computer dialog, then click ← to return to the table of your service accounts.

Next, we need to enable enable G Suite domain-wide delegation:

  1. Locate the newly-created service account in the table. Under Actions, click Manage Details.

  2. In the service account details, click Advanced settings. Show domain-wide delegation, then ensure the Enable G Suite Domain-wide Delegation checkbox is checked.

    caution

    Domain-wide delegation may not be possible from here, depending on what type of Google account you have, as well as Google's updates to their interface. Consult their documentation on Domain-Wide Delegation of Authority as needed.

    If you haven't yet configured your app's OAuth consent screen, you must do so before you can enable domain-wide delegation. Follow the on-screen instructions to configure the OAuth consent screen, then repeat the above steps and re-check the checkbox.

  3. Click Save to update the service account, and return to the table of service accounts. A new column, Domain-wide delegation, can be seen. Click View Client ID, to obtain and make a note of the client ID.

Set the impersonating user​

Open the key file downloaded earlier in a text editor, and add an impersonate_user field to the JSON. In this case, we'd be impersonating the admin account user@pomerium.io.

caution

Google requires that service accounts act on behalf of another user. You MUST add the impersonate_user field to your json key file.

pomerium-oauth-226e52af9cdd.json
{
  "type": "service_account",
  "project_id": "pomerium-redacted",
  "private_key_id": "e07f7c93870c7e03f883560ecd8fd0f4d27b0081",
  "private_key": "-----BEGIN PRIVATE KEY-----\\n-----END PRIVATE KEY-----\n",
  "client_email": "redacted@pomerium-redacted.iam.gserviceaccount.com",
  "client_id": "101215990458000334387",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/redacted%40pomerium-redacted.iam.gserviceaccount.com",
+  "impersonate_user": "user@pomerium.com"
}

The base64 encoded contents of this public/private key pair json file will used for the value of the IdP service account configuration setting:

cat pomerium-oauth-226e52af9cdd.json | base64 -w 0

Set directory permissions for Workspaces​

Next, we need to give that service account permissionson the GSuite / Workspace side of the house.

  1. From your Google Workspace domain's Admin console Main menu, go to Security > Access and data control > API controls.

  2. In the Domain wide delegation pane, select Manage Domain Wide Delegation.

  3. Click Add new.

  4. In the Client ID field, enter the client ID obtained from the service account creation steps above.

  5. In the OAuth Scopes field, enter a comma-delimited list of the scopes required for your application (for a list of possible scopes, see Authorize requests).

    Include at a minimum the following list of scopes:

    • https://www.googleapis.com/auth/admin.directory.group.readonly
    • https://www.googleapis.com/auth/admin.directory.user.readonly

  6. Click the Authorize button.

Google create service account

Configure Pomerium​

Edit config.yaml or set your environment variables to connect Pomerium to Google:

/etc/pomerium/config.yaml
idp-provider: "google"
idp-client-id: "yyyy.apps.googleusercontent.com"
idp-client-secret: "xxxxxx"
idp-service-account: "zzzz" # output of `base64 -i service-account-key.json`, with impersonate_user set.

Troubleshooting​

invalid service account for Google directory provider​

This error message in Pomerium log output coincides with an empty Groups field in the /.pomerium endpoint. It indicates that your service account is missing or incorrectly configured. Revisit the linked section above to adjust your service account settings as needed.