Using Fortanix DSM for Google Workspace Client-Side Encryption

1.0 Introduction

This article describes how to use Fortanix Data Security Manager (DSM) for Google Workspace Client-Side Encryption (CSE).

To perform Google Workspace CSE integration using Fortanix DSM, you will encrypt the Google Workspace applications’ data (such as Google Docs and Google Drive) with a Data Encryption Key (DEK) and use Fortanix DSM API to wrap the DEK before storing it on Google Cloud storage. To decrypt the document, the Google Workspace application will call the Fortanix DSM APIs to unwrap the DEK and then decrypt the data.

2.0 Definitions

3.0 Prerequisites

  • Fortanix DSM must be set up as the encryption key service.
  • An Identity Provider (IdP) - You need to connect to either an external IdP configured on your Google Workspace account, or Google identity by creating a client ID in the Google Cloud Platform (GCP) console. Your IdP verifies the identity of users before allowing them to encrypt files or access the encrypted files.
  • An Authorization Provider – Configure an authorization provider to enable CSE for Google Docs, Google Drive, Google Meet, and Google Calendar. This is used to verify information such as the caller’s role, resource name, and so on.
    The key service URL is automatically created using Add Instance page in the wizard.
  • AES Key – The key that wraps and unwraps the DEK.
NOTE
  • The AES key is automatically created using the Add Instance page in the wizard.
  • It is important to decide whether to use a single key or a separate key for each document. After the URI is added to Google Workspace; to change the URI, you need to contact Google support for help to change the URI.

4.0 Key Management Best Practices

For key rotation, you need to perform the following steps:

  • Rotate the key in Fortanix DSM
  • Copy the URL for the new key (the ID will be different)
  • Change the URL in Workspace CSE

Workspace CSE will use the new key to encrypt but can still decrypt old data that was encrypted with the old key (if you do not delete the old version).

When using a URL containing a Group ID, you do not need to do anything other than rotate the key in Fortanix DSM.

NOTE

Ensure not to disable the old key while rotating the security object in Fortanix DSM, as the old key is still required to decrypt the encrypted document. Before disabling the old key, first open the encrypted document and save the document again which will then use the new key to encrypt. Post this process you can disable the old key.

5.0 Using Fortanix DSM with Google Workspace

5.1 Overview

Google Workspace CSE encrypts a user’s documents before they leave their web browser. The Workspace application, for example: Google Docs, generates a Data Encryption Key (DEK) in the browser, encrypts user contents with that key, and then it calls Fortanix DSM to wrap the DEK with a Key Encryption key (KEK) in Fortanix DSM. It then stores the encrypted data along with the wrapped DEK in cloud storage. When calling the Fortanix DSM APIs, the Workspace application presents two signed JSON Web Tokens (JWT) with its request that identify the user by their email address used to log in to the Google Workspace application.

Fortanix DSM will verify these JWT tokens based on the account CSE configurations and check whether the user has proper access to the Key Encryption Key (KEK) before wrapping/unwrapping the DEK.

NOTE
For user-based authentication method, as described in Section 5.3: Adding an Instance, the user needs to be a group administrator in the same group where the KEK is located to be able to wrap/unwrap the DEK.

Google Workspace CSE requires the following APIs from Fortanix DSM:

  • Wrap: POST https://<base_url>/wrap
  • Unwrap: POST https://<base_url>/unwrap
  • Privileged Unwrap: POST https://<base_url>/privileged_unwrap
  • Status Check: GET https://<base_url>/status

    Where <base_url> either identifies a single key or a group in Fortanix DSM. When using a single key, all DEKs are encrypted with the same KEK. When using a group, each Google Workspace document’s DEKs will be encrypted with its own dedicated KEK stored in the specified group in DSM and the KEKs are created automatically when wrap API is called to encrypt a document. The base URL patterns for each case are:

  • For single KEK:
    https://<dsm_domain>/crypto/v1/keys/<key_id>/integrations/workspace_cse
  • For separate KEK for each document:
    https://<dsm_domain>/crypto/v1/groups/<group_id>/integrations/workspace_cse
    Where,
    • <dsm_domain> is the fully qualified domain name of your Fortanix DSM cluster, for example: “amer.smartkey.io” for the Americas Region of DSM SaaS.
    • <key_id> is the UUID of the KEK in Fortanix DSM.
    • <group_id> is the UUID of the group where you want to store KEKs for Google Workspace applications.

After you decide which approach suits your needs best, you should note the correct URL from the wizard and move on to configuring CSE in the Workspace admin console. But to enable CSE in your Fortanix DSM account, you need to follow the steps in the next section.

5.2 Configuring Workspace CSE in Fortanix DSM

    1. Log in to Fortanix DSM as an account administrator and click the Integrations tab in the left panel.
    2. On the Integrations page, click CONFIGURE on the Google Workspace easy wizard. WorkspaceConfigure.pngFigure 1: Configure Workspace CSE
NOTE
  • If the DSM Account Administrator has configured the Google Workspace CSE integration before DSM version 4.19, then all existing or new users invited to the account need not accept the account invitation in DSM before using the Google Workspace CSE feature.
  • If the DSM Account Administrator has configured the Google Workspace CSE integrations on DSM version 4.19 or later, then all users invited to the account must accept the account invitation in DSM and when applicable verify their account emails before using the Google Workspace CSE feature unless the Account Administrator has configured app authentication as described in Section 5.7: Invite a Google Workspace CSE User.

5.3 Adding an Instance

Validate the Google-issued authorization tokens by adding an instance for Google Workspace users.

The following image illustrates the Add Instance page:

GWorkspaceCSE-CreateInstance.png

Figure 2: Add an Instance

Perform the following steps:

  1. Enter the value for the discovery document URL of the OpenID Connect IdP in Enter discovery document URL field.
    This URL has the following general form:

    https://{domain}[/{path}]/.well-known/openid-configuration

    The /{path} part is optional (denoted with []).

    For example:

  2. Enter the value for Client ID and Client Secret. In order to use the IdP to authenticate users in the Fortanix DSM account, the Account Administrator needs to provide "Client ID" and "Client Secret" values. These are documented in the Single Sign-On Guide.
    NOTE
    The rest of the configuration parameters listed in the SSO guide are retrieved using the discovery document URL described in Step 1 above.
  3. Enter the values for Client ID of CSE application. In order to set up Google Workspace CSE in Fortanix DSM, you must know the value of "Client ID" issued for the CSE client application by the IdP.

    See instructions for client_id in the table found in (Option 1) To connect to your IdP using a .well-known file -> Step 2. Configure your .well-known file in the following page: Connect to your identity provider for client-side encryption.

  4. Select either of the following Document Encryption options:
    • Use Single Key to encrypt all Google Workspace documents – Select this option to encrypt all the Google workspace documents DEKs using a single KEK in Fortanix DSM. This option will generate a URL containing the Fortanix DSM Key ID.
    • Automatically create a new key for each document - Select this option to encrypt each Google workspace document DEK using a new KEK stored in a specific group in Fortanix DSM. This option will generate a URL containing the Fortanix DSM Group ID.
  5. Select one of the following under Authentication Type to authenticate the Google Workspace CSE users with Fortanix DSM.
    • As User: If this option is selected , then all users who are invited to use this feature using the Users tab must accept the Fortanix DSM account invitation and if applicable verify their email address to use this feature. For steps to add a user, refer to Section 5.7: Invite a Google Workspace CSE User.
      NOTE
      This is the previously existing workflow.
    • As App: If this option is selected , then as an Account Administrator, you can add users as an app using the Apps tab where the app name is the email ID of the CSE user, and the credential is Workspace CSE App Auth. Notably, these Workspace users do not have to accept a DSM user invitation or verify their e-mail address. For steps to add a user as an app, refer to Section 5.7: Invite a Google Workspace CSE User.
      NOTE
      • This workflow was introduced in DSM Release 4.19.
      • Using this method, users will not have the overhead of a full DSM account and can only access the CSE related endpoints.
  6. Click the NEXT button to configure the Identity Providers.
    NOTE
    You can only create a single Google Workspace CSE instance at any given time. To add a new instance, edit the existing instance with new values or delete the instance and create a new instance.

5.4 Configure Identity Providers

Configure the Identity Providers that authenticate users for Google Workspace.

The following image illustrates the Identity Providers page:

Identity_Providers.png

Figure 3: Identity Providers

NOTE
Fortanix DSM does not check if Single Sign On (SSO) settings exist for each Identity Provider that is configured, but it is recommended to add these IdPs in the Fortanix SSO settings as well. Refer to User’s Guide: SSO, for more details.
Perform the following steps:
  1. Enter a descriptive name for IdP in Identity Provider name field.
  2. Select either of the following Signing keys. These are used to validate the signature on the authentication JWT. 
    • Stored Signing Key:
      • Add Public Key: Provide one or more public keys by uploading or pasting the key(s) in PEM format. When specifying multiple keys, specify the Key ID so that keys can be differentiated by their unique Key IDs.
        Stored_Keys.png
    • FETCHED SIGNING KEY:
      • Key URL: Specify a URL where the signing keys can be fetched from. The specified URL should return the signing keys in one of the following formats:
        • JWK Set: please refer to Section 5 of RFC 7517 for details.
        • A JSON object mapping key IDs to base64 encoded public keys in DER format.
      • Cache duration: To improve performance, Fortanix DSM will cache the fetched keys, but you can control how long the keys are cached.
        Fetched_Sining_key.png
  3. Valid issuers: one or more valid issuers. This information is used to validate the iss field of the JWT.
  4. Valid Audiences: one or more valid audiences. This information is used to validate the aud field of the JWT.
    It is recommended to use fetched signing keys if the signing keys are rotated periodically. 
    If you are not using any external IdP with your Workspace account, then use the following values for the identity provider:

    For third-party IdPs follow the instructions in Connect to identity provider for client-side encryption and provide the same information that you use when configuring your IdP in the Workspace admin console - option 2 (or from the .well-known document of your IdP - option 1)

  5. Click the NEXT button to configure the Authorization Providers.

5.5 Configuring Authorization Providers

Configure one or more authorization providers that allow the service to validate the Google-issued authorization tokens for Workspace CSE APIs. Different workspace applications might require different authorization settings.

The following image illustrates the Authorization Providers page:

Authorization_Provider.png

Figure 4: Authorization Provider

Perform the following steps:

  1. Select Google Drive and Docs, Google Meet, and Google Calendar if you want to configure these options as an authorization provider. The authorization provider settings will be automatically included for Google Drive and Google Docs, Google Meet, and Google Calendar.
  2. If you want to add another authorization provider, then click the ADD ANOTHER AUTHORIZATION PROVIDER button.
    • Enter a name for the provider.
    • Key URL: Enter the remote public key location.
    • Cache Duration: Fortanix DSM will cache the keys to improve performance, but you can control how long the keys are cached.
    • Valid issuers: One or more valid issuers. This information is used to validate the iss field of the authorization JWT. For example, gsuitecse-tokenissuer-drive@system.gserviceaccount.com  is used for Google Drive and Docs.
    • Valid Audiences: One or more valid audiences. This information is used to validate the aud field of the authorization JWT. For example, cse-authorization is used for Google Drive and Docs.
      The following image illustrates the entered values in the respective fields:
    Configure_Authoriation_Provider.pngFigure 5: Configure Authorization Provider
  3. Click the NEXT button to review the listing.

5.6 Reviewing the Added Instance

Review the information on the added instance for the Google Workspace CSE. This page confirms that your Google Workspace CSE instance is set up.

The following image illustrates the Review page:

Review_and_Save_Instance.png

Figure 6: Review and Save Instance

Click the SAVE button to save the instance and generate the Key Service URL. Upon saving the instance, a Google Workspace CSE group is automatically created.

In the summary page, copy the Key Service URL for using it in the Google Workspace Admin Console to encrypt all Google Workspace CSE documents.

Copy_Key_Service_URL.png

Figure 7: Copy Key Service URL

5.7 Invite a Google Workspace CSE User

To invite a user to use the Google Workspace CSE feature using the User authentication method:

  1. Click the Users tab in the DSM UI left panel.
  2. On the Users page, click add.png to invite a new Google Workspace CSE user.
  3. Enter the user’s email address in the Enter e-mail to invite field.
  4. Select the Role for the user as Account Member and provide the necessary Group Administrator, Group Auditor, or Group Custom Role permission or select the Role as Account Administrator as described in User’s Guide: Authorization in DSM.
  5. Click the INVITE button.
    CSE-InviteUser.png
    Figure 8: Invite User Using User Authentication

To invite a user to use the Google Workspace CSE feature using the App authentication method:

  1. Click the Apps tab in the DSM UI left panel.
  2. On the Apps page, click add.png to add a new Google Workspace CSE user as an app.
  3. For the App name field, enter the Google Workspace CSE user’s email ID.
  4. Select the Authentication method as Workspace CSE App Auth.
  5. Assign the app to a Google Workspace CSE group in DSM.
  6. Click the SAVE button to create the user as an app.
    CSE-InviteUserasApp.png
    Figure 9: Invite User Using App Authentication

5.8 Editing and Deleting and Instance

You can edit any of the provided information in the Google Workspace CSE instance using the Edit button corresponding to each widget on the screen.

You can also remove the Google Workspace CSE instance using the DELETE button available at the end of the screen.

Edit_or_Delete_and_Instance.png

Figure 10: Edit or Delete an Instance

5.9 Enabling Google Workspace to Access Keys in Fortanix DSM

Google Workspace CSE needs a URL to access the KEK stored in Fortanix DSM. This URL is generated in the Review wizard.  

Use the resource URL in your Workspace admin console as your “key service URL”.

  1. Log in to admin.google.com with an administrator account and click Security -> Client-side encryption.
  2. Under Add external key service:
    1. Enter a name for the external key service, provide the URL that you copied in the above step, and then click Continue.
    2. Click TEST CONNECTION and make sure the connection is successful.
    3. Click Add Service -> Continue to finish the configuration.
  3. Under Add identity provider, enter the details of the well-known identity provider that you provided in Fortanix Google CSE settings in Section 5.3: Adding an Instance.
  4. Click TEST CONNECTION and make sure the connection is successful.
  5. Click Add Provider to add the IdP.
  6. Under Apps, click the Drive and Docs icon:
    1. Client-side encryption status -> Turn it ON
    2. Default external key service -> Select the newly added key service from drop down

Add_External_Key_Service_and_Identity_Provider.pngFigure 11: Add External Key Service and Identity Provider

After completing the Workspace settings, follow the steps listed in About client-side encryption - Google Workspace Admin Help. You should be able to go to Google Docs and create an encrypted document, if everything works you will see audit log messages on the key(s) in Fortanix DSM showing requests coming from your browser.

6.0 Configure Gmail CSE in Fortanix DSM

With Gmail Workspace CSE, security administrators of an organization can send and receive client-side encrypted emails within or outside their organization. The encryption scheme uses asymmetric private keys and certificates for authentication and key agreement for message encryption. As the security administrator of an organization, you can now configure Google Workspace CSE in Fortanix DSM to enable the relevant CSE endpoints to support users signing and decrypting messages in Gmail.

6.1 Gmail CSE Prerequisites

  • Refer to the Prerequisites in Section 3.0: Prerequisites.
  • The user must have a Google Workspace Enterprise Plus, Education, or Education Plus Tier and a Google Workspace CSE integration configured in Fortanix DSM.
  • Users can create a main/master wrapping AES key separate from the default one for the integration that will be used to wrap the RSA private keys in a later step.

6.2 Add an Instance

Validate the Google-issued authorization tokens by adding an instance for Google Workspace users. Refer to Section 5.3: Adding an Instance for more details.

6.3 Configure Identity Provider

Configure the Identity Providers that authenticate users for Google Workspace. Refer to Section 5.4: Configure Identity Providers for more details.

6.4 Configure Authorization Provider

Configure Gmail as the authorization provider. To configure Gmail as an authorization provider, enter the following values:

  1. Enter a name for the provider, for example: Gmail
  2. Key URL: https://www.googleapis.com/service_accounts/v1/jwk/gsuitecse-tokenissuer-gmail@system.gserviceaccount.com
  3. Cache Duration: 86400 seconds
  4. Valid Issuersgsuitecse-tokenissuer-gmail@system.gserviceaccount.com
  5. Valid Audiences: cse-authorization

The following image illustrates the entered values in the respective fields:

Gmail_Auth_Provider.png Figure 12: Configure Gmail Authorization Provider

6.5 Review the Added Instance

Review the information on the added instance for the Gmail Workspace CSE. Refer to Section 5.6: Reviewing the Added Instance for more details.

6.6 Invite a Gmail Workspace CSE User

To add users for Gmail CSE, create an app with the authentication method Workspace Cse App Auth.

6.7 Create Wrapped Private Key

  1. Refer to Section 5.9: Enabling Google Workspace to Access Keys in Fortanix DSM for steps to access the KEK stored in Fortanix DSM.
    1. Follow Steps 1-5 in Section 5.9.
    2. In Step 6 in the Section 5.9, Under Apps, click the Gmail icon:
      • Client-side encryption status -> Turn it ON
      • Default external key service -> Select the newly added key service from drop down
      Gmail_Add_Ext_IDP.png Figure 13: Add additional key service and identity provider
    3. Complete the Workspace CSE settings. Follow Steps 1 to 7 in Section: CSE Setup Overview in About client-side encryption - Google Workspace Admin Help.
      • You should have generated an S/MIME (Secure/Multipurpose Internet Mail Extensions) certificate for each user who will use Gmail CSE to either send or receive emails.
        NOTE
        To send and receive signed and encrypted emails outside the organization, you will need to provision the users with certificates issued by a commercial Certificate Authority.
      • Next, for each user’s private key, you need to make a /wrapkey request.
      • When creating your private key metadata, the user must manually do either of the following using the /wrapkey endpoint in DSM
        • Import the private key into DSM, and then create the wrap key request.
        • Inline the key in the wrap key request.
      • After you have the wrapped response, configure the CBOR (Concise Binary Object Representation) serialization, and then base64 encode the resulting string.
        NOTE
        The user must structure the wrapped response using the CDDL (Concise Data Definition Language) format below before generating the metadata blob.
        # 
        # The CDDL for the wrapped private key metadata that will be serialized in CBOR and encoded using base64.
        # 
        WorkspaceCseWrappedPrivateKey = {
            wrapped_key: bytes,       ; The private key wrapped as a blob returned 
                                      ;     from the /wrapkey endpoint
            wrapping_key: tstr,       ; The Uuid of the wrapping key
            obj_type: tstr,           ; The object type of the wrapped key, for now should be "Rsa".
            iv: bytes,              ; The iv used during wrapping of the private key 
                                      ;     returned from the /wrapkey endpoint
            mode: tstr,             ; The mode used during wrapping, see this page for a list of valid modes
                                      ; https://support.fortanix.com/hc/en-us/articles/360028212271-Wrapping-a-Key
            ? ad: bytes,              ; The optional authenticated data used during wrapping
            ? tag: bytes,             ; The optional tag used during wrapping
        }
        
      • Google requires you to now format the wrapped private key generated above and save it in a file with a .wrap extension. For example, user1@example.com.wrap.
      The wrapped private key must have a JSON object with the following two required fields:
      {
        "kacls_url": "URL provisioned in the workspace for the base CSE integration",
        "wrapped_private_key": "base64 encoded bytes"
      }
      

6.8 Provisioning User Key-Pairs

Next, you need to upload the S/MIME certificate and private key metadata encrypted by DSM to Gmail.

NOTE
  • The Workspace CSE administrator:
    • Must have their GCP service account set up and save the credentials somewhere accessible.
    • Will need the metadata blob for each user and their certificate chains.
    • Will need the kacls_url that is listed in the Google Admin Console
  1. To upload user’s certificates and wrapped private keys to Gmail, refer to the script in Set up your Organization for Gmail client-side encryption to make the appropriate API calls to Google.
  2. After following the steps, you should be able to go to Gmail to encrypt and sign email messages. If everything works, you will see audit log messages on the key(s) in Fortanix DSM showing requests coming from your browser.

7.0 Frequently Asked Questions

  • How to identify the security object associated with the Google document when using Group ID?
    When using Group ID, Fortanix DSM creates a security object for each document that is encrypted from Google CSE and you can identify the security object associated with a document in Fortanix DSM by clicking on the encrypted document in Google drive and paying close attention to the document URL that contains the security object.  
  • How can I segregate the security objects created by multiple teams in Google Workspace since all the security objects are created in a single group in Fortanix DSM when using Fortanix DSM Group ID in KMS URL?
    When using Group ID in KMS URL, all the security objects are created in the default group. However, you can create multiple groups, for example HR, Finance, IT, and so on, and move the associated security objects manually to the new group from the default group.
    One point to note is that when you move an object to a different group, users still need to be group members in that group to be able to use the key to wrap/unwrap, otherwise they would get an access control error. This security requirement is the best way to ensure correct permissions over the keys that the user needs to decrypt documents.

Comments

Please sign in to leave a comment.

Was this article helpful?
0 out of 0 found this helpful