Add and manage key services for client-side encryption

Supported editions for this feature: Enterprise Plus; Education Standard and Education Plus. Compare your edition

If you've set up your external key service for Google Workspace Client-side encryption (CSE), you need to add it to your Admin console. This connects Google Workspace to the service so it can encrypt content using your encryption keys.

For more information about external key services, go to Set up your key service for client-side encryption.

If needed, you can add multiple key services, for example, to migrate encrypted content from one key service to another or assign different key services to specific users.

Note: For Gmail CSE, you can use hardware encryption keys instead of a key service. Requires having the Assured Controls or Assured Controls Plus add-on. For details, go to Gmail only: Set up and manage hardware encryption keys. 

Add a key service

Expand section  |  Collapse all

Before you begin

If you're adding your first key service

A message appears to remind you to assign a default key service for your top-level organizational unit. You can do this at any time to ensure encryption is available for all users who need to encrypt or decrypt content. For details, go to Assign the default key service for your organization.

If you're adding a second key service

You’ll need to make the current service the backup service. The backup encrypts the same content as the second key service, and is needed if you want to migrate encrypted content to the second service. For details, go to About the backup key service below.

If you already have at least 2 key services and are adding another

You’ll need to remove the backup service from the current primary service, and then choose a backup for the new service. Or, you can add the new service without backup. For details, go to Add a new key service when another service has a backup below.

Consider a naming convention for multiple key services

Establish a naming convention so you can easily identify the key services and for which services and users you’ll apply them. For example, you might want to the name to indicate the region, organizational unit, and key service:

• NORTHAM-R&D-Key-service1
• EUROPE-HR-Key-service2

About the backup key service

If you add more than one key service to your Admin console, one key service must be the backup for another service.

The backup service is used for migrating content

If you want to migrate encrypted content to a new key service—that is, re-encrypt content encrypted by your current service—you need to make the current key service the backup to your new service. Because the backup key service encrypts the same content as its primary service, it ensures content remains accessible if there’s a problem during content migration. For details about migration, go to Migrate encrypted content to a new key service.

Important: You can have only one key service at a time using a backup key service.

Exception for Gmail CSE

If you add a new key service and make your current service the backup using the Admin console, only the backup service encrypts email, not the new key service. To switch key services for Gmail, you need to use the Gmail API to upload new certificates and the private keys' metadata wrapped by the new service. For details about switching to a different key service for Gmail, go to To switch to another key service for Gmail CSE.

Add an external key service

You must be signed in as a super administrator for this task.

1. Sign in to your Google Admin console.

   Sign in using an account with super administrator privileges (does not end in @gmail.com).

2. In the Admin console, go to Menu  DataComplianceClient-side encryption.
3. Under Encryption with external key service, do one of the following:
   • If this is the first key service you're adding, click Add external key service.
   • If you're adding an additional key service, click Add.
4. Enter the following information from the key service you signed up with (or built using the CSE API):

   Name—Enter any name you like. This name appears in some messages to users if Google Workspace can't access your external key service, so they'll know the problem is with the encryption service and not the Google service they're using.

   URL—Your key service provides this URL to you. Before entering this URL, check that it's accessible from the internet.

5. If you added a second key service, click Select backup key, and select an available backup key service. This allows you to migrate encrypted content to the new key service.

   For details about migrating content to a new key service, go to Assign key services for client-side encryption.

6. If you already have at least 2 key services, and you added another, choose whether to add the new key service without backup. For details about your options, go to Add a new key service when another service has a backup below.

   Or, to close the Add external key service dialog without choosing an option, click Cancel.

7. To make sure Google Workspace can communicate with the external key service, click Test connection.
8. If the connection is successful, in the lower-right corner of the page, click Add or Add service.

If this is the first key service you added:

• A message appears to remind you to assign a default key service for your top-level organizational unit. You can do this at any time to ensure encryption is available for all users need to encrypt or decrypt content. For details, go to Assign the default key service for your organization.
• Make sure you connect Google Workspace to your identity provider (IdP) for client-side encryption.

Add a new key service when another service has a backup

If you’ve already added at least 2 key services to the Admin console, one service is the backup for another. If you add another key service, you can’t choose a backup service for it because only one key service at a time can have a backup. Therefore, when adding the new key service, you need to choose an option, depending on how you want to use the key service.

To switch from using an existing key service to the new one 

When adding a new key service, choose the option Remove backup from key service, and then click Remove backup.

Now you can add the new key service and choose a backup service. After that, you can migrate encrypted content to the new key service. For details, go to Migrate encrypted content to a new key service.

Recommendation: Choose this option only if the current key service doesn’t have any issues with encrypting content. Also, if the backup key service is being used to migrate content to your current primary service, make sure migration is complete—once you remove the backup, migration will stop immediately. For details, go to Migrate encrypted content to a new key service.

To use the new key service without migrating encrypted data 

When adding a new key service, choose the option Add key service without backup, then click Add service.

Recommendation: Choose this option only if you want to use this key service for an organizational unit or group that doesn't already has content encrypted by another key service. If content is already encrypted, you'll need to keep the existing key service to ensure the encrypted content is accessible.

Edit a key service

Expand section  |  Collapse all

Change a key service's name

You must be signed in as a super administrator for this task.

1. Sign in to your Google Admin console.

   Sign in using an account with super administrator privileges (does not end in @gmail.com).

2. In the Admin console, go to Menu  DataComplianceClient-side encryption.
3. Under External key service, click the name of the key service you want to change.
4. Edit the key service's name.
5. Click Continue.

Change a key service's URL

You must be signed in as a super administrator for this task.

If your users are having trouble accessing content encrypted by a key service, ask the key service for a new encryption URL. Then replace the previous URL with the new one in the Admin console to allow users to recover their content.

If users can't encrypt new content with a key service, you can try assigning a different key service to organizations or groups that are having trouble.

If you replace a URL with one from a different key service: All files already encrypted with your previous key service can't be decrypted, and users can't access their content. 

To change a key service's URL:

1. Sign in to your Google Admin console.

   Sign in using an account with super administrator privileges (does not end in @gmail.com).

2. In the Admin console, go to Menu  DataComplianceClient-side encryption.
3. Under External key service, click the name of the key service for which you want to change the URL.
4. Click Having issues?Add a new URL.
5. To make sure Google Workspace can communicate with the external key service, click Test connection.
6. If the connection is successful, in the lower-right corner of the page, click Continue.

Remove the backup from a key service

You might want to remove the backup key service from another key service if:

• You no longer need it for migrating content. 
• You want to add another key service and need to choose a backup service so you can migrate encrypted content to the new service.

For details about content migration, go to Migrate encrypted content to a new key service.

To remove the backup key service:

1. Sign in to your Google Admin console.

   Sign in using an account with super administrator privileges (does not end in @gmail.com).

2. In the Admin console, go to Menu  DataComplianceClient-side encryption.
3. Under External key service, click the name of the key service for which you want to remove the backup.
4. Click Remove backup.
5. Check the boxes under To remove backup, confirm you understand the following.
6. Click Remove backup.

Disable a key service that has backup

You can disable a key service if it has a backup key service assigned to it. For example, you might want to disable a key service and use its backup if users are having issues with either accessing encrypted content or encrypting new content. Because the key service you want to disable has a backup, client-side encrypted content will still be accessible.

To disable a key service and use its backup instead:

1. Sign in to your Google Admin console.

   Sign in using an account with super administrator privileges (does not end in @gmail.com).

2. In the Admin console, go to Menu  DataComplianceClient-side encryption.
3. Under External key service, click the name of the key service for which you want to remove the backup.
4. Click Disable & use backup.
5. Check the boxes under By disabling, I understand the following.
6. Click Disable & use backup.

If you're having issues with a key service

Expand section  |  Collapse all

Users can’t access encrypted content

There might be a problem with the key that’s being used to decrypt content. Contact your key service to request a new URL. For details about changing the URL for a key service, go to Change a key service’s URL above.

Or, if the key service has a backup service, try using the backup instead For details, go to Disable a key service that has backup above.

Users can’t encrypt new content

There might be a problem with the key that’s being used to encrypt content. Contact your current key service to request a new URL. For details about changing the URL for a key service, go to Change a key service’s URL above.

Alternatively, you can try the following:

• Replace the current key service with another key service. Go to Migrate encrypted content to a new key service.
• If the key service has a backup service, try using the backup instead For details, go to Disable a key service that has backup above.

After migration to new key service, users can’t access encrypted content or encrypt new content

Try using the backup key service instead. For details, go to Disable a key service that has backup above.

If users still can’t access encrypted content or encrypt new content, there’s a problem with the backup key. Contact your key service for help.