Google Cloud Environment Setup

Setting up your Google Cloud environment to work with KeeperPAM

Google Cloud Environment Overview

Overview

Resources in your GCP environment can be managed by a Keeper Gateway using a service account configured in the PAM Configuration record. Optionally this service account can be configured to have domain-wide delegation, enabling Keeper Gateway to rotate passwords for Google Workspace users (GCP principals) discovered during GCP discovery.

The service account must be configured appropriately to enable access to the target GCP resources:

• Compute Engine

• Cloud SQL

• Cloud Resource Manager

• Managed Microsoft Active Directory

Additionally, in order to enable Google Workspace user password changes, the service account also needs:

• Domain-wide delegation enabled in Google Workspace Admin Console

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

• The google_admin_email must have user management permissions in Workspace

See below for more details about enabling password rotations for GCP Principals.

Required Service Account Setup

A service account is a special kind of account typically used by an application or compute workload, such as a Compute Engine instance, rather than a person.

The minimal set of permissions needed by the KeeperPAM service account are as follows:

compute.instances.list
compute.zones.list

cloudsql.instances.get
cloudsql.instances.list
cloudsql.users.update

resourcemanager.projects.getIamPolicy

managedidentities.domains.list

To ensure least privilege, the service account provided in the GCP configuration should be granted these permissions only:

• Create a Custom Role (e.g. KeeperPAM)

• Create a Service Account

• Assign the role to the Service Account

• Create a new JSON Private Key for the Service Account

Save the downloaded file in the Keeper vault for protection. The contents of this file will also be added to the "Service Account Key" field of the PAM Configuration record in the Keeper vault.

---

Optional Setup for GCP User Password Rotation

You can optionally activate the ability for KeeperPAM to rotate Google Workspace identities by following the steps in this section.

When discovering GCP resources, the system identifies users from IAM policies with the user: prefix (e.g., user:[email protected]). These are typically Google Workspace users who have been granted permissions in your GCP project.

To rotate passwords for these Workspace users, the service account must:

1. Have domain-wide delegation enabled in Google Workspace

2. Be authorized with the appropriate OAuth scope

3. Have an admin email specified that the service account will impersonate

Prerequisites

• A Google Cloud Platform project with a service account

• Google Workspace admin access

• The service account's Client ID (found in the service account details)

Step-by-Step Configuration

Enable Domain-Wide Delegation for the Service Account

1. Go to the Google Cloud Console

2. Navigate to IAM & Admin → Service Accounts

3. Locate your service account (the one whose key is used in the PAM Configuration)

4. Click on the service account to view its details

5. Go to the Details tab

6. Under Advanced settings, find the Domain-wide delegation section

7. Click Enable Google Workspace Domain-wide Delegation

8. Note the Client ID - you'll need this in the next step

Authorize the Service Account in Google Workspace Admin Console

1. Go to the Google Workspace Admin Console

2. Navigate to Security → Access and data control → API controls

3. Scroll down to Domain-wide delegation

4. Click Manage Domain-Wide Delegation

5. Click Add new

6. In the Client ID field, paste the Client ID from step 1

7. In the OAuth scopes field, enter:

   https://www.googleapis.com/auth/admin.directory.user

8. Click Authorize

Configure the Google Admin Email

The Google Admin Email is a Google Workspace user account that:

• Has administrative privileges in Google Workspace

• Specifically has User Management permissions

• Will be impersonated by the service account when making password changes

Create or Identify an Admin User

Option A: Use an existing Super Admin

• Use the email of an existing Google Workspace Super Admin

• Example: [email protected]

Option B: Create a dedicated service admin account (Recommended)

• Go to Directory → Users in Google Workspace Admin Console

• Click Add new user

• Create a user with a name like:

  • Name: Keeper Gateway Service

  • Email: [email protected]

• Assign admin roles to this user:

  • Go to Directory → Users

  • Click on the newly created user

  • Click Admin roles and privileges

  • Assign User Management Admin role (or Super Admin if needed)

---

Set up the PAM Configuration Record

In the Keeper Vault > Secrets Manager > PAM Configurations > create a new GCP PAM Configuration record. Set the following:

Service Account Key (JSON format)

This is the key file created above during the Service Account setup. The format is like this:

{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "[email protected]",
  "client_id": "...",
  "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": "..."
}

Google Admin Email

This is only required if GCP service principal rotation is configured.

[email protected]

---

How It Works

When rotating a password for a GCP user:

1. The system discovers users from GCP IAM policies (e.g., user:[email protected])

2. During password rotation, the code:

   • Loads the service account credentials from the JSON key

   • Requests credentials with the admin.directory.user scope

   • Creates delegated credentials by impersonating the Google Admin email

   • Uses the Google Admin Directory API to update the user's password

3. The password change is applied to the Google Workspace user

Required Permissions Summary

GCP Project Permissions (for Discovery)

The service account needs these IAM permissions in the GCP project:

• resourcemanager.projects.getIamPolicy - To discover users from IAM policies

Google Workspace Permissions

The service account needs:

• Domain-wide delegation enabled

• OAuth Scope: https://www.googleapis.com/auth/admin.directory.user

The Google Admin email account needs:

• User Management Admin role (or Super Admin)

Troubleshooting

Error: "No Google Admin email provided"

• Cause: The google_admin_email field is not set in the PAM Configuration record

• Solution: Add the admin email to the PAM Configuration record

Error: "Permission denied" or "Forbidden"

• Cause: Domain-wide delegation not properly configured

• Solution:

  1. Verify the service account has domain-wide delegation enabled

  2. Verify the Client ID is correctly added in Google Workspace Admin Console

  3. Verify the OAuth scope https://www.googleapis.com/auth/admin.directory.user is authorized

Error: "Insufficient permissions"

• Cause: The Google Admin email doesn't have sufficient privileges

• Solution: Ensure the admin email has User Management Admin role or Super Admin role

Error: "Invalid credentials" or "Authentication failed"

• Cause: Service account key is invalid or expired

• Solution:

  1. Regenerate the service account key in GCP Console

  2. Update the PAM Configuration record with the new key JSON

User password change succeeds but user can't log in

• Cause: Password policy requirements not met

• Solution: Password generation respects these constraints:

  • Minimum 8 characters

  • At least one lowercase letter

  • At least one uppercase letter

  • At least one digit

  • At least one symbol from: !@#$%^&*()_+-=[]{}|

Security Best Practices

1. Use a dedicated service admin account: Create a separate Google Workspace user specifically for this service rather than using a personal admin account

2. Limit service account key distribution: Store the service account key JSON securely in Keeper Secrets Manager only

3. Monitor admin activity: Regularly review the Google Workspace admin audit logs for activities by the service account

4. Rotate service account keys: Periodically rotate the service account keys and update the PAM Configuration

5. Principle of least privilege: Only grant User Management Admin role, not Super Admin, unless additional permissions are needed

Additional Resources

• Google Workspace Domain-Wide Delegation Guide

• Google Admin SDK Directory API

• Service Account Authentication