# Google Cloud Environment Setup

## Google Cloud Environment Overview  <a href="#iam-admin-user" id="iam-admin-user"></a>

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FkBgMnT6tO0ghipaaVRin%2Fgenerated-image.png?alt=media&#x26;token=3b513acd-d175-470c-b31c-75a2c99db100" alt=""><figcaption></figcaption></figure>

## 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](#google-workspace-setup-for-gcp-user-password-rotation) for more details about enabling password rotations for GCP Principals.

### Required Service Account Setup <a href="#ec2-role" id="ec2-role"></a>

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](https://docs.cloud.google.com/iam/docs/creating-custom-roles) (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 <a href="#google-workspace-setup-for-gcp-user-password-rotation" id="google-workspace-setup-for-gcp-user-password-rotation"></a>

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:john.doe@example.com`). 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 href="#prerequisites" id="prerequisites"></a>

* 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 <a href="#step-by-step-configuration" id="step-by-step-configuration"></a>

#### Enable Domain-Wide Delegation for the Service Account <a href="#id-1-enable-domain-wide-delegation-for-the-service-account" id="id-1-enable-domain-wide-delegation-for-the-service-account"></a>

1. Go to the [Google Cloud Console](https://console.cloud.google.com)
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 <a href="#id-2-authorize-the-service-account-in-google-workspace-admin-console" id="id-2-authorize-the-service-account-in-google-workspace-admin-console"></a>

1. Go to the [Google Workspace Admin Console](https://admin.google.com)
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 <a href="#id-3-configure-the-google-admin-email" id="id-3-configure-the-google-admin-email"></a>

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: `admin@example.com`

**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: `keeper-gateway@example.com`
* 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 <a href="#id-4-configure-the-pam-configuration-record-in-keeper" id="id-4-configure-the-pam-configuration-record-in-keeper"></a>

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:

```json
{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "your-sa@your-project.iam.gserviceaccount.com",
  "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.

```
keeper-gateway@example.com
```

***

### How It Works <a href="#how-it-works" id="how-it-works"></a>

When rotating a password for a GCP user:

1. The system discovers users from GCP IAM policies (e.g., `user:john.doe@example.com`)
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 <a href="#required-permissions-summary" id="required-permissions-summary"></a>

#### GCP Project Permissions (for Discovery) <a href="#gcp-project-permissions-for-discovery" id="gcp-project-permissions-for-discovery"></a>

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

* `resourcemanager.projects.getIamPolicy` - To discover users from IAM policies

#### Google Workspace Permissions <a href="#google-workspace-permissions" id="google-workspace-permissions"></a>

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 <a href="#troubleshooting" id="troubleshooting"></a>

#### Error: "No Google Admin email provided" <a href="#error-no-google-admin-email-provided" id="error-no-google-admin-email-provided"></a>

* **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" <a href="#error-permission-denied-or-forbidden" id="error-permission-denied-or-forbidden"></a>

* **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" <a href="#error-insufficient-permissions" id="error-insufficient-permissions"></a>

* **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" <a href="#error-invalid-credentials-or-authentication-failed" id="error-invalid-credentials-or-authentication-failed"></a>

* **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 <a href="#user-password-change-succeeds-but-user-cant-log-in" id="user-password-change-succeeds-but-user-cant-log-in"></a>

* **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 <a href="#security-best-practices" id="security-best-practices"></a>

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 <a href="#additional-resources" id="additional-resources"></a>

* [Google Workspace Domain-Wide Delegation Guide](https://developers.google.com/workspace/guides/create-credentials#optional_set_up_domain-wide_delegation_for_a_service_account)
* [Google Admin SDK Directory API](https://developers.google.com/admin-sdk/directory/reference/rest/v1/users/update)
* [Service Account Authentication](https://cloud.google.com/docs/authentication/production)