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).

CHGWS is compatible with both Multi-tenant Cloud HSM and Single-tenant Cloud HSM keys.

For more information, see Cloud HSM for Google Workspace.

Automated onboarding support

The Google Workspace Admin console has an automated onboarding process that is considerably faster than onboarding manually. However, automated onboarding is only supported if you meet all of the following criteria:

  • You're setting up Google Workspace client-side encryption (CSE) for the first time.
  • You're using Google Identity as your identity provider (IdP).
  • You're using Multi-tenant Cloud HSM keys.

If you meet all these criteria, go to the Admin console and complete the automated onboarding process.

You'll have to onboard manually if you meet any of the following criteria:

  • You use a third-party IdP.
  • You use Single-tenant Cloud HSM.
  • You plan to migrate keys from another key service.
  • You want to modify an existing Cloud HSM for Google Workspace configuration.

If you meet any of these criteria, follow the setup instructions in this document.

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.

Compatible locations

You can store your Cloud KMS keys in any regional or multi-regional location within the US or Europe geographic areas. Cloud HSM for Google Workspace supports both Multi-tenant Cloud HSM and Single-tenant Cloud HSM keys. To find a specific location, visit Cloud KMS Locations and filter by your HSM type.

Cloud HSM for Google Workspace automatically provides the endpoint in one of the following multi-regions closest to your key location:

  • us
  • eur3

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.

  1. 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.

  2. Enable billing on the project that you created.

  3. Enable the Cloud KMS API in your Google Cloud key project.

    Enable the API

  4. Enable the Workspace Key Access API (Preview) in your Google Cloud key project.

    Enable the API

  5. In the Google Cloud console, click terminal Activate Cloud Shell.

  6. Verify that you are in the correct project by comparing your project ID with the project ID in the Cloud Shell prompt.

  7. 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.

  8. Grant the CHGWS key Service Agent and Browser roles 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
    
    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudkmskacls.iam.gserviceaccount.com \
        --role=roles/browser
    

    Replace the following:

    • PROJECT_ID: The project ID of your key project.
    • PROJECT_NUMBER: The project number of your key project.
  9. Grant the Workspace Key Access API Admin (roles/workspacekeyaccess.admin) role (Preview) to the administrator who creates and manages CHGWS configs and endpoints:

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member=user:ADMIN_USER_EMAIL \
        --role=roles/workspacekeyaccess.admin
    

    Replace the following:

    • PROJECT_ID: The project ID of your key project.
    • ADMIN_USER_EMAIL: The email address of the Google Cloud administrator who creates and manages CHGWS configs and endpoints.

Set up Cloud KMS keys

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

  1. Create a key ring in one of the supported regions:

    gcloud kms keyrings create KEY_RING --location LOCATION
    

    Replace the following:

    • KEY_RING: The name that you want to use for your CHGWS key ring—for example, CHGWS_KEY_RING.
    • LOCATION: The location where you want to create your key ring—for example, us.
  2. Create a Cloud HSM key.

    Multi-tenant Cloud HSM

    To create a key with the hsm protection level:

    gcloud kms keys create KEY_NAME \
        --protection-level "hsm" \
        --keyring KEY_RING \
        --location LOCATION \
        --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.
    • KEY_RING: The name of your key ring—for example, CHGWS_KEY_RING.
    • LOCATION: The location where you created your key ring—for example, us.
    • 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.

    Single-tenant Cloud HSM

    To create a key with the hsm_single_tenant protection level, you must first have a Single-tenant Cloud HSM instance provisioned in the same location.

    1. Create and provision a Single-tenant Cloud HSM instance: Follow the instructions in the Create and manage a Single-tenant Cloud HSM instance guide. Make note of the provisioned Instance ID. You use it in the next step.

    2. Create a key:

      gcloud kms keys create KEY_NAME \
          --protection-level "hsm_single_tenant" \
          --keyring KEY_RING \
          --location LOCATION \
          --purpose "encryption" \
          --crypto-key-backend "projects/PROJECT_ID/locations/LOCATION/singleTenantHsmInstances/INSTANCE_NAME" \
          --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.
      • KEY_RING: The name of your key ring—for example, CHGWS_KEY_RING.
      • LOCATION: The location where you created your key ring—for example, us.
      • PROJECT_ID: The project ID of your key project.
      • INSTANCE_NAME: The name of the Single-tenant Cloud HSM instance where you want to create the 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.

    For more details on key creation options, see Creating keys.

Onboard by using the self-service Workspace Key Access API

You can use the Google Cloud CLI with the Workspace Key Access API to create and manage the following CHGWS resources:

  • Config: Stores your Google Workspace organization and IdP details, including your customer ID, administrator email addresses, allowed domains, and JSON Web Token (JWT) authentication parameters.
  • Endpoint: Connects your CHGWS config to your Cloud KMS key and provides the key service URL (uri) that you register in the Google Workspace Admin console for CSE.

The following sections show you how to create and manage your CHGWS configs and endpoints by using the Google Cloud CLI.

Alternatively, you can Request a CHGWS endpoint by contacting your account representative.

Create CHGWS configs

Your CHGWS config stores information about your Google Workspace organization and the identity providers (IdPs) that your users authenticate with. You can use CHGWS with only a primary IdP, or you can configure both a primary and guest IdP.

To configure CHGWS to use only a primary IdP, do the following:

  • Create a CHGWS config to register your Google Workspace by using the workspace-key-access configs create command:

    gcloud beta workspace-key-access configs create CONFIG_ID \
        --project=PROJECT_ID \
        --location=ENDPOINT_LOCATION \
        --customer-id=CUSTOMER_ID \
        --admin-emails=ADMIN_EMAILS \
        --kacls-owner-domains=OWNER_DOMAINS \
        --idp-configs='
            idpType=PRIMARY_IDP,
            issuer=IDP_ISSUER,
            jwksUri=IDP_JWKS_URI,
            audience=IDP_AUDIENCE,
            additionalAudiences=[ADDITIONAL_IDP_AUDIENCES]
        '
    

    Replace the following:

    • CONFIG_ID: An identifier for your config—for example, my-workspace-config.
    • PROJECT_ID: The project ID of your key project.
    • ENDPOINT_LOCATION: The location where you want to create your config—for example, us. Specify one of the Compatible locations.
    • CUSTOMER_ID: Your Google Workspace customer ID. To find your customer ID, see Find your customer ID.
    • ADMIN_EMAILS: A comma-separated list of Google Workspace administrator email addresses.
    • OWNER_DOMAINS: A comma-separated list of allowed Google Workspace customer domains where you register the key service. Find your domains in the Google Workspace Admin console on the Manage domains page.
    • IDP_ISSUER: The JWT issuer URL of your primary IdP. For Google Identity Platform, use https://accounts.google.com.
    • IDP_JWKS_URI: The JSON Web Key Set (JWKS) URL of your primary IdP. For Google Identity Platform, use https://www.googleapis.com/oauth2/v3/certs.
    • IDP_AUDIENCE: Your primary IdP's OAuth 2.0 client ID for web applications.
    • ADDITIONAL_IDP_AUDIENCES: Optional: A list of OAuth 2.0 client IDs for non-web platform applications, separated by commas without spaces. Applications can include mobile or desktop applications. If you don't need to configure additional audiences, remove the placeholder so the brackets are empty (additionalAudiences=[]). For Google Identity Platform, use the client IDs given in If you'll use Google identity for CSE.

    For more information about available flags, see gcloud beta workspace-key-access configs create.

To configure CHGWS to use both a primary and a guest IdP, do the following:

  • Create a CHGWS config to register your Google Workspace by using the workspace-key-access configs create command and specify the --idp-configs flag twice:

    gcloud beta workspace-key-access configs create CONFIG_ID \
        --project=PROJECT_ID \
        --location=ENDPOINT_LOCATION \
        --customer-id=CUSTOMER_ID \
        --admin-emails=ADMIN_EMAILS \
        --kacls-owner-domains=OWNER_DOMAINS \
        --idp-configs='
            idpType=PRIMARY_IDP,
            issuer=IDP_ISSUER,
            jwksUri=IDP_JWKS_URI,
            audience=IDP_AUDIENCE,
            additionalAudiences=[ADDITIONAL_IDP_AUDIENCES]
        ' \
        --idp-configs='
            idpType=GUEST_IDP,
            issuer=GUEST_IDP_ISSUER,
            jwksUri=GUEST_IDP_JWKS_URI,
            audience=GUEST_IDP_AUDIENCE,
            additionalAudiences=[GUEST_ADDITIONAL_IDP_AUDIENCES]
        '
    

    Replace the following:

    • CONFIG_ID: An identifier for your config—for example, my-workspace-config.
    • PROJECT_ID: The project ID of your key project.
    • ENDPOINT_LOCATION: The location where you want to create your config—for example, us. Specify one of the Compatible locations.
    • CUSTOMER_ID: Your Google Workspace customer ID. To find your customer ID, see Find your customer ID.
    • ADMIN_EMAILS: A comma-separated list of Google Workspace administrator email addresses.
    • OWNER_DOMAINS: A comma-separated list of allowed Google Workspace customer domains where you register the key service. Find your domains in the Google Workspace Admin console on the Manage domains page.
    • IDP_ISSUER: The JWT issuer URL of your primary IdP. For Google Identity Platform, use https://accounts.google.com.
    • IDP_JWKS_URI: The JSON Web Key Set (JWKS) URL of your primary IdP. For Google Identity Platform, use https://www.googleapis.com/oauth2/v3/certs.
    • IDP_AUDIENCE: Your primary IdP's OAuth 2.0 client ID for web applications.
    • ADDITIONAL_IDP_AUDIENCES: Optional: A list of OAuth 2.0 client IDs for non-web platform applications, separated by commas without spaces. Applications can include mobile or desktop applications. If you don't need to configure additional audiences, remove the placeholder so the brackets are empty (additionalAudiences=[]). For Google Identity Platform, use the client IDs given in If you'll use Google identity for CSE.
    • GUEST_IDP_ISSUER: The JWT issuer URL of your guest IdP. For Google Identity Platform, use https://accounts.google.com.
    • GUEST_IDP_JWKS_URI: The JWKS URL of your guest IdP. For Google Identity Platform, use https://www.googleapis.com/oauth2/v3/certs.
    • GUEST_IDP_AUDIENCE: Your guest IdP's OAuth 2.0 client ID for web applications, except for Google Meet.
    • GUEST_ADDITIONAL_IDP_AUDIENCES: Optional: A list of OAuth 2.0 client IDs for non-web platform applications that you configure for your guest IdP, separated by commas without spaces. Applications can include mobile or desktop applications. If you don't need to configure additional audiences, remove the placeholder so the brackets are empty (additionalAudiences=[]). For Google Identity Platform, use the client IDs given in If you'll use Google identity for CSE.

    For more information about available flags, see gcloud beta workspace-key-access configs create.

Optional: To verify that your config is set up correctly, do the following:

  • Describe the config to view its details:

    gcloud beta workspace-key-access configs describe CONFIG_ID \
        --project=PROJECT_ID \
        --location=ENDPOINT_LOCATION
    

Create a CHGWS endpoint

  1. Create a CHGWS key service endpoint, and then attach it to your CHGWS config and Cloud KMS key:

    gcloud beta workspace-key-access endpoints create ENDPOINT_ID \
        --project=PROJECT_ID \
        --location=ENDPOINT_LOCATION \
        --config=projects/PROJECT_ID/locations/ENDPOINT_LOCATION/configs/CONFIG_ID \
        --kms-key=projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME
    

    Replace the following:

    • ENDPOINT_ID: An identifier for your key service endpoint—for example, my-kacls-endpoint.
    • PROJECT_ID: The project ID of your key project.
    • ENDPOINT_LOCATION: The location of your config and endpoint—for example, us. Specify one of the Compatible locations.
    • CONFIG_ID: The ID of the config that you created previously.
    • LOCATION: The location where you created your Cloud KMS key ring—for example, us.
    • KEY_RING: The name of your Cloud KMS key ring.
    • KEY_NAME: The name of your Cloud KMS key.
  2. Describe the endpoint to retrieve its generated uri and verify that its state is ACTIVE:

    gcloud beta workspace-key-access endpoints describe ENDPOINT_ID \
        --project=PROJECT_ID \
        --location=ENDPOINT_LOCATION
    

    Copy the uri value from the output. You use this URL in Configure CHGWS endpoint in Google Workspace CSE.

Request a CHGWS endpoint

To request onboarding and endpoint creation, contact your account representative for assistance, and provide the following information:

  • Google Workspace details:

    • Google Workspace customer ID: Your Google Workspace customer ID. To find your customer ID, see Find your customer ID.

    • Google Workspace administrator email addresses: Provide a comma-separated list of administrator email addresses.

  • IdP details:

    • Primary IdP details:

      • IdP JWKS URL: For Google Identity Platform, use https://www.googleapis.com/oauth2/v3/certs.
      • 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 that you configure. 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.
  • CSE Key details:

    • Google Cloud project ID: PROJECT_ID
    • Google Cloud project number: PROJECT_NUMBER
    • Cloud KMS key ring name: KEY_RING
    • Cloud KMS key ring location: LOCATION
    • Cloud KMS key name: KEY_NAME
    • Cloud KMS key protection level: Either hsm or hsm_single_tenant
    • 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.
  • Additional Details:

    • Customer Name: Provide customer name.
    • Expected number of users: Provide the expected number of users in your Google Workspace instance.

Manage CHGWS service endpoints

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

Configure CHGWS endpoint in Google Workspace CSE

After you create a CHGWS endpoint, go to the Google Workspace Admin console to configure Google Workspace to use the endpoint. The endpoint URL and IdP settings in the Admin console must match the details of the CHGWS endpoint. If you update the config of the CHGWS endpoint, then you must also update the key service configuration in the Google Workspace Admin console to match the updated details. For more information, see Add and manage key services for client-side encryption.

Key service migration

CHGWS provides flexibility to move your key service to or from CHGWS. To start a key service migration, contact your account representative for assistance with submitting a migration request. In the request, include the following information:

  • Endpoint ID: The endpoint ID of CHGWS.
  • Key Service URL: A list of URLs to enable key service migration.

    • If you migrate to Cloud HSM for Google Workspace, then provide the base URL of each key service endpoint that you migrate from.
    • If you migrate from Cloud HSM for Google Workspace, provide the base URLs of the key service endpoints that you want to migrate to.

Update a config by using the self-service Workspace Key Access API

You can update the administrator email addresses, allowed customer domains, or IdP details of an existing CHGWS config by using the gcloud CLI. Updating a config automatically updates all endpoints that use the config.

  1. Update your CHGWS config. Include only the flags for the fields that you want to update, and remove any flags for fields that you want to keep unchanged—each flag that you include replaces the existing values for that field:

    gcloud beta workspace-key-access configs update CONFIG_ID \
        --project=PROJECT_ID \
        --location=ENDPOINT_LOCATION \
        --admin-emails=ADMIN_EMAILS \
        --kacls-owner-domains=OWNER_DOMAINS \
        --idp-configs='
            idpType=PRIMARY_IDP,
            issuer=IDP_ISSUER,
            jwksUri=IDP_JWKS_URI,
            audience=IDP_AUDIENCE,
            additionalAudiences=[ADDITIONAL_IDP_AUDIENCES]
        ' \
        --idp-configs='
            idpType=GUEST_IDP,
            issuer=GUEST_IDP_ISSUER,
            jwksUri=GUEST_IDP_JWKS_URI,
            audience=GUEST_IDP_AUDIENCE,
            additionalAudiences=[GUEST_ADDITIONAL_IDP_AUDIENCES]
        '
    

    Replace the following:

    • CONFIG_ID: The ID of the config that you want to update.
    • PROJECT_ID: The project ID of your key project.
    • ENDPOINT_LOCATION: The location of your config—for example, us. Specify one of the Compatible locations.
    • ADMIN_EMAILS: Optional: a comma-separated list of Google Workspace administrator email addresses. Remove --admin-emails if you don't want to update administrator email addresses.
    • OWNER_DOMAINS: Optional: a comma-separated list of allowed Google Workspace customer domains where you register the key service. Find your domains in the Google Workspace Admin console on the Manage domains page. Remove --kacls-owner-domains if you don't want to update allowed customer domains.
    • --idp-configs:
      • If you configured only a primary IdP: Remove the second (GUEST_IDP) --idp-configs flag (and the trailing backslash on the preceding line) and update the details in the PRIMARY_IDP flag. Your guest IdP remains unset.
      • If you configured both a primary IdP and a guest IdP: You must include both --idp-configs flags even if you're updating only one of them—if you omit the GUEST_IDP flag, your guest IdP is overwritten as unset, and if you omit the PRIMARY_IDP flag, the update fails.
      • If you don't want to update any IdP: Remove both --idp-configs flags so your existing IdP details remain unchanged.
    • Primary IdP details: Required whenever you include --idp-configs:
      • IDP_ISSUER: The JWT issuer URL of your primary IdP. For Google Identity Platform, use https://accounts.google.com.
      • IDP_JWKS_URI: The JWKS URL of your primary IdP. For Google Identity Platform, use https://www.googleapis.com/oauth2/v3/certs.
      • IDP_AUDIENCE: Your primary IdP's OAuth 2.0 client ID for web applications.
      • ADDITIONAL_IDP_AUDIENCES: Optional: a comma-separated list of OAuth 2.0 client IDs for non-web platform applications (such as Android, iOS, or desktop applications), separated by commas without spaces. If you don't need to configure additional audiences, remove the placeholder so the brackets are empty (additionalAudiences=[]). For Google Identity Platform, use the client IDs given in If you'll use Google identity for CSE.
    • Guest IdP details: Optional: required only when you include the second (GUEST_IDP) --idp-configs flag:
      • GUEST_IDP_ISSUER: The JWT issuer URL of your guest IdP. For Google Identity Platform, use https://accounts.google.com.
      • GUEST_IDP_JWKS_URI: The JWKS URL of your guest IdP. For Google Identity Platform, use https://www.googleapis.com/oauth2/v3/certs.
      • GUEST_IDP_AUDIENCE: Your guest IdP's OAuth 2.0 client ID for web applications, except for Google Meet.
      • GUEST_ADDITIONAL_IDP_AUDIENCES: Optional: a comma-separated list of OAuth 2.0 client IDs if you configure a Google Meet web client ID or other non-web platform application client IDs for your guest IdP (separated by commas without spaces). If you don't need to configure additional audiences, remove the placeholder so the brackets are empty (additionalAudiences=[]). For Google Identity Platform, use the client IDs given in If you'll use Google identity for CSE.

    For more information about available flags, see gcloud beta workspace-key-access configs update.

  2. Optional: Review the details of the config to confirm that it is updated correctly:

    gcloud beta workspace-key-access configs describe CONFIG_ID \
        --project=PROJECT_ID \
        --location=ENDPOINT_LOCATION
    
  3. Optional: If you have an unused config that isn't attached to any endpoint, you can delete it:

    gcloud beta workspace-key-access configs delete CONFIG_ID \
        --project=PROJECT_ID \
        --location=ENDPOINT_LOCATION
    

Update an endpoint to use a different config

You can attach a CHGWS endpoint to a different config in the same Google Cloud project and location; however, you can't change the backing Cloud KMS key associated with an endpoint.

Update the config attached to an endpoint:

gcloud beta workspace-key-access endpoints update ENDPOINT_ID \
    --project=PROJECT_ID \
    --location=ENDPOINT_LOCATION \
    --config=projects/PROJECT_ID/locations/ENDPOINT_LOCATION/configs/NEW_CONFIG_ID

Replace the following:

  • ENDPOINT_ID: The ID of the key service endpoint that you want to update.
  • PROJECT_ID: The project ID of your key project.
  • ENDPOINT_LOCATION: The location of your endpoint and config—for example, us. Specify one of the Compatible locations.
  • NEW_CONFIG_ID: The ID of the config in the same project and location that you want to attach to the endpoint.

Request updates to an endpoint

If you onboarded by requesting a CHGWS endpoint and need to update your existing CHGWS details, contact your account representative to submit an update request. In the request, include your Google Workspace customer ID, your Google Cloud project ID and CHGWS endpoint ID, and the updated Google Workspace administrator email addresses or IdP details listed in Request a CHGWS endpoint.

Disable and enable endpoints and billing

You can't delete a CHGWS endpoint, however, if you self-onboarded your endpoint, then you can disable or re-enable an endpoint by using Workspace Key Access with gcloud CLI. Disabling an endpoint transitions it to the DISABLED state and terminates its billing subscription.

To disable an endpoint that you self-onboarded, do the following:

  • Disable the active endpoint and disable billing:

    gcloud beta workspace-key-access endpoints disable ENDPOINT_ID \
        --project=PROJECT_ID \
        --location=ENDPOINT_LOCATION
    

    Replace the following:

    • ENDPOINT_ID: The ID of the key service endpoint that you want to disable.
    • PROJECT_ID: The project ID of your key project.
    • ENDPOINT_LOCATION: The location of your endpoint—for example, us. Specify one of the Compatible locations.

Before you can re-enable an endpoint, the Cloud KMS key and key versions that are used by the endpoint must be accessible and active. Enabling an endpoint restarts its billing subscription and transitions the endpoint to the ACTIVE state.

To re-enable an endpoint that you disabled by using the workspace-key-access endpoints disable command, do the following:

  • Re-enable the endpoint and restart billing:

    gcloud beta workspace-key-access endpoints enable ENDPOINT_ID \
        --project=PROJECT_ID \
        --location=ENDPOINT_LOCATION
    

    Replace the following:

    • ENDPOINT_ID: The ID of the key service endpoint that you want to enable.
    • PROJECT_ID: The project ID of your key project.
    • ENDPOINT_LOCATION: The location of your endpoint—for example, us. Specify one of the Compatible locations.

Disable and enable underlying key versions

Regardless of how you onboarded your endpoint, you can disable the underlying Cloud KMS key versions in Cloud KMS by using the Google Cloud console, gcloud CLI, or Cloud KMS API. Disabling the underlying key versions disables the endpoint without terminating the billing subscription; you can then disable billing separately.

To disable the underlying key versions, do the following:

  • For each Cloud KMS key version that backs the endpoint, run the following command:

    gcloud kms keys versions disable KEY_VERSION --keyring \
        KEY_RING --location LOCATION --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.
    • LOCATION: The location of the key version that you want to disable—for example, us.
    • KEY_NAME: The name of the key—for example, CHGWS_KEY.

To re-enable a CHGWS endpoint that you disabled by disabling all key versions of the Cloud KMS key that backs the endpoint, do the following:

  • For each Cloud KMS key version that backs the endpoint, run the following command:

    gcloud kms keys versions enable KEY_VERSION --keyring \
        KEY_RING --location LOCATION --key KEY_NAME
    

    Replace the following:

    • KEY_VERSION: The version of the key that you want to enable—for example, 1.
    • KEY_RING: The name of the key ring—for example, CHGWS_KEY_RING.
    • LOCATION: The location of the key version that you want to enable—for example, us.
    • KEY_NAME: The name of the key—for example, CHGWS_KEY.

Manage billing for CHGWS

Billing begins as soon as your CHGWS endpoint is created and active. From that point on, recurring subscription charges for Cloud HSM for Google Workspace continue as long as the endpoint remains ACTIVE on the Google Cloud project. This section explains different ways how you can stop accruing charges for Cloud HSM for Google Workspace and how you can resume them.

Disable and enable endpoints

If you self-onboarded your endpoint, then you can use the Workspace Key Access API to disable a CHGWS endpoint while keeping other resources in your Google Cloud project active. Disabling an endpoint transitions it to the DISABLED state and terminates its billing subscription. You can later re-enable the endpoint to restart its billing subscription and transition it back to the ACTIVE state.

For more information, see Disable and enable endpoints and billing.

Disable or enable project billing

You can disable billing for the project that contains your Cloud KMS keys for Cloud HSM for Google Workspace. Disabling billing makes all chargeable services within the project stop working. After the project level billing is disabled, expect the Cloud HSM for Google Workspace subscription charges to stop within 24 hours.

When you want to resume using Cloud HSM for Google Workspace, you can re-enable billing on the project. After billing is re-enabled, your subscription fees resume and your CHGWS endpoint and Cloud KMS keys function normally again.

Request manual deactivation or activation

If you onboarded by requesting a CHGWS endpoint and need to disable the endpoint while keeping other project resources active, file a request similar to the onboarding request. Provide Google Workspace details, CHGWS endpoint ID, and other relevant details and describe your requirement. Manual tickets can take 48 hours to be completed by the CHGWS team. After the request is completed, expect the Cloud HSM for Google Workspace subscription charges to stop within 24 hours.

You can re-enable the CHGWS endpoint and its billing by creating a similar request.

Delete or restore the project

You can delete the project that contains your Cloud KMS keys for Cloud HSM for Google Workspace. Deleting a project stops all services within the project. You can recover a deleted project within 30 days of deletion. However, Cloud KMS keys in the project can't be recovered, so all the documents and other data that are encrypted with keys in the restored project remain permanently crypto-shredded. Restoring a deleted project resumes the subscription charges of Cloud HSM for Google Workspace even though the Cloud KMS keys remain unrecoverable.

What's next