Onboard to Cloud HSM for Google Workspace

This page describes how to onboard Cloud HSM for Google Workspace (CHGWS), the encryption key service for Google Workspace offered by Cloud Key Management Service (Cloud KMS). Cloud HSM for Google Workspace provides enhanced privacy controls for Google Workspace, helping you achieve regulatory standards such as DISA IL5 and elevate data security. Cloud HSM is a standards-aligned, highly available, and fully managed key management service operated at cloud scale with hardware-backed keys stored in FIPS 140-2 Level 3 compliant HSMs (hardware security modules).

Before you begin

Before you onboard Cloud HSM for Google Workspace, complete the following prerequisites:

Set up a Google Workspace.
Enable Google Workspace Client-side Encryption (CSE) in your Google Workspace.
Configure your Identity Provider (IdP) in Google Workspace CSE. Note the Client ID for your IdP. If you use Google Identity Platform, find the Client ID in your Google Cloud project.
Optional: If you allow access to CSE-encrypted content on platform applications other than web (such as mobile or desktop), add the client IDs for those platforms in your IdP settings in the Google Workspace Admin Console. Note all client IDs for this IdP. If you use Google Identity Platform, find these client IDs in your Google Cloud project. For other Identity Providers, create these client IDs separately.

Request Google Workspace onboarding

To onboard to Cloud HSM for Google Workspace, submit an onboarding request. Provide the following information:

Google Workspace ID: Your Google Workspace ID. Find your Google Workspace ID by following the instructions at Find your customer ID.
Google Workspace administrator email addresses: Provide a comma-separated list of administrator email addresses.
Primary Identity Provider (IdP) details:
- IdP JSON Web Key Set (JWKS) URL: For Google Identity Platform, use https://www.googleapis.com/oauth2/v3/certs.
- JSON Web Token (JWT) token issuer: For Google Identity Platform, use https://accounts.google.com.
- JWT audience: Your IdP's Client ID for web applications.
- Additional JWT audiences: Optional. Provide client IDs for non-web platform applications if configured. For Google Identity Platform, use the client IDs given in If you'll use Google identity for CSE.
Guest IdP details: Optional. Complete this section if you're using a guest IdP.
- Guest IdP JWKS URL: The JWKS URL of your guest IdP.
- Guest JWT token issuer: The JWT token issuer of your guest IdP.
- Guest JWT audience: Your guest IdP's Client ID for web applications, except for Google Meet.
- Guest additional JWT audiences: Optional. If you configure a Google Meet web client ID or other non-web platform application client IDs, provide client IDs for each. For Google Identity Platform, use the client IDs given in If you'll use Google identity for CSE.
Endpoint location: us-central1.
Expected number of users: Provide the expected number of users in your Google Workspace instance.

Verify that your IdP JWKS URL is publicly accessible. Confirm the JWT Token Issuer and JWT Audience values with your IdP administrator.

The CHGWS team responds within 24 to 48 hours with your Google Workspace setup status. After successful onboarding, proceed to set up your Google Cloud project for Cloud KMS.

Set up a Google Cloud project for Cloud KMS

Cloud HSM for Google Workspace endpoints rely on Cloud KMS keys for cryptographic operations. Set up a new Google Cloud project to host the Cloud KMS keys.

Create a Google Cloud project. This is your key project. Make note of the project ID and project number; you need these to complete the setup.
Enable billing on the project that you created.
Enable the Cloud KMS API in your Google Cloud key project.

Enable the API
In the Google Cloud console, click terminal Activate Cloud Shell.
Verify that you are in the correct project by comparing your project ID with the project ID in the Cloud Shell prompt.
Using Cloud Shell, create the Cloud HSM for Google Workspace service account:
```
gcloud beta services identity create --service=cloudkmskacls-pa.googleapis.com
```
Note the service identity created by this command. You need the service identity name in the next step.

Grant the CHGWS key Service Agent role to the service account that you created:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER>@gcp-sa-cloudkmskacls.iam.gserviceaccount.com \
    --role=roles/cloudkmskacls.serviceAgent

Replace the following:

PROJECT_ID: The project ID of your key project.
PROJECT_NUMBER: The project number of your key project.

Manage CHGWS service endpoint

The following sections show you how to set up and manage your CHGWS endpoints.

Set up Cloud KMS keys

Set up the Cloud KMS resources for your CHGWS key service endpoint.

Create a key ring in the us-central1 region:
```
gcloud kms keyrings create KEY_RING --location us-central1
```
Replace KEY_RING with the name that you want to use for your CHGWS key ring—for example, CHGWS_KEY_RING.
Create a Cloud HSM key:
```
gcloud kms keys create KEY_NAME \
--protection-level "hsm" \
--keyring KEY_RING \
--location us-central1 \
--purpose "encryption" \
--rotation-period ROTATION_PERIOD \
--next-rotation-time NEXT_ROTATION_TIME
```
Replace the following:
- KEY_NAME: The name that you want to use for your key—for example, CHGWS_KEY_RING.
- KEY_RING: The name of your key ring—for example, CHGWS_KEY.
- ROTATION_PERIOD: The frequency at which you want to rotate your keys—for example, 7d.
- NEXT_ROTATION_TIME: The date and time when the next key rotation occurs—for example, 2024-03-20T01:00:00.

Request endpoint creation

To request endpoint creation, submit an endpoint creation request. Provide the following information:

Workspace ID: <var>GOOGLE_WORKSPACE_ID</var>
Google Cloud Project ID: PROJECT_ID
Google Cloud Project Number: PROJECT_NUMBER
Cloud KMS keyring name: KEY_RING
Cloud KMS keyring location: us-central1
Cloud KMS key name: KEY_NAME
CHGWS Base URL: Optional. A list of URLs to enable key migration. If you set up CHGWS for the first time for this Google Workspace, leave this field blank.

The CHGWS team responds within 24 to 48 hours with the CHGWS endpoint URL after the endpoint becomes available.

Configure CHGWS endpoint in Google Workspace CSE

Configure Google Workspace CSE to use the CHGWS URL generated when you created the endpoint CHGWS. Follow the instructions at Add and manage key services for client-side encryption.

Migrate Endpoints

CHGWS provides flexibility to move your key service to or from CHGWS. To start a CHGWS migration, submit a migration request. In the request, include the following information:

Endpoint ID: The endpoint ID of CHGWS.
CHGWS Base URL: A list of URLs to enable CHGWS key migration.
- If you migrate to Cloud HSM for Google Workspace, then provide the base URL of each CHGWS endpoint that you migrate from.
- If you migrate from Cloud HSM for Google Workspace, provide the base URL(s) of the CHGWS endpoint(s) that you want to migrate to.

If you migrate between two different Cloud HSM for Google Workspace endpoints, submit two separate requests: one from the previous endpoint and the other to the new endpoint.

The CHGWS team responds within 24 to 48 hours to let you know that the endpoint is ready for migration.

Delete or disable endpoints

Delete or disable operations on the Cloud HSM for Google Workspace endpoint are not directly supported. However, you can disable a Cloud HSM for Google Workspace endpoint by disabling all backing Cloud KMS key versions.

For each Cloud KMS key version backing the endpoint, run the following command:
```
gcloud kms keys versions disable KEY_VERSION --keyring \
    KEY_RING --location us-central1 --key KEY_NAME
```
Replace the following:
- KEY_VERSION: The version of the key that you want to disable—for example, 1.
- KEY_RING: The name of the key ring—for example, CHGWS_KEY_RING.
- KEY_NAME: The name of the key—for example, CHGWS_KEY.

Enable endpoints

If you've disabled a CHGWS endpoint by disabling all key versions of the backing Cloud KMS key, then you can re-enable the CHGWS endpoint. To re-enable the endpoint, enable all active versions of the backing Cloud KMS key by using the following gcloud CLI command:

For each Cloud KMS key version backing the endpoint, run the following command:
```
gcloud kms keys versions enable KEY_VERSION \
    --keyring KEY_RING --location us-central1 --key KEY_NAME
```
Replace the following:
- KEY_VERSION: The version of the key that you want to disable—for example, 1.
- KEY_RING: The name of the key ring—for example, CHGWS_KEY_RING.
- KEY_NAME: The name of the key—for example, CHGWS_KEY.

What's next

Learn more about Cloud Key Management Service.
Learn how to add and manage key services for client-side encryption.

Onboard to Cloud HSM for Google Workspace Stay organized with collections Save and categorize content based on your preferences.