Sectigo Google Workspace S/MIME Connector application

IT administrators who manage a Google Workspace account for an organization can set up and use the Sectigo Google Workspace S/MIME Connector application ("the application") to provision and manage S/MIME email certificates for users in a Google Workspace domain.

Overview

Secure/Multipurpose Internet Mail Extensions (S/MIME) provides an added security level for email communications. S/MIME is based on asymmetric cryptography and lets users encrypt outgoing messages and attachments so that only intended receipients will be able to read the message.

Users can also digitally sign a message to prove the identity of the sender—​a digitally signed message assures the recipient that the message hasn’t been tampered with and verifies the identity of the sender.

Sectigo S/MIME certificates can be used for the following:

  • Sign outgoing mail messages with the user’s certificate and private key

  • Decrypt incoming mail messages with the user’s private key

  • Encrypt outgoing mail messages with the recipient’s certificate and public key

  • Verify incoming mail messages with the sender’s certificate and public key

Scope

This guide covers instructions for connecting to the Sectigo REST APIs and provisioning, uploading, and managing S/MIME email certificates for users in a Google Workspace domain.

Audience

This guide is intended for IT administrators and system administrators, who manage a Google Workspace Enterprise Plus account for an organization, and are responsible for provisioning and managing S/MIME email certificates for users in a Google Workspace domain. The administrators should have knowledge of IT security, cloud security, Google Workspace, and be familiar with Sectigo Certificate Manager (SCM).

Additional resources

S/MIME Connector application architecture

The following diagram presents the architecture of the application.

S/MIME Connector application architecture

The Sectigo Google Workspace S/MIME Connector application allows an administrator of a Google Workspace domain to perform the following operations for the domain users:

  • Generate and upload S/MIME keys

    • Obtain a client certificate from SCM

    • Create a .p12 package (an S/MIME key)

    • Upload the S/MIME key to the user’s Gmail account

  • Update S/MIME keys that are nearing expiry

    • Renew certificates that are about to expire (within the defined range, for example, 30 days or less)

    • Upload the renewed S/MIME key to the user’s Gmail account

The application uses the Gmail S/MIME API to upload and manage S/MIME email certificates for users in a Google Workspace domain. Each S/MIME certificate is for a specific alias for a user email account. Aliases include the primary email address and custom "Send As" addresses. A single S/MIME certificate is marked as the default for each alias.

Prerequisites

  • Google Workspace Enterprise Plus account: An active Google Workspace Enterprise Plus account (the email S/MIME encryption is only available on the Enterprise Plus plan)

  • GCP project with Gmail API enabled: Create a project on Google Cloud Platform and enable Gmail API for this project

  • Service account: A service account with domain-wide delegation of authority:

    1. Create a service account.

    2. Generate and download the service account credentials (a public/private key pair) in the JSON format. The keys will be used as an input parameter in the smimeconnector.json file.

    3. Enable domain-wide delegation for the service account and grant the following scopes to your service account by entering a comma-delimited list of the scopes in the OAuth Scopes field.

      Scope Description

      https://www.googleapis.com/auth/gmail.settings.basic

      View, edit, create, or change your email settings and filters in Gmail

      https://mail.google.com/

      Read, compose, send, or permanently delete your emails from Gmail

      https://www.googleapis.com/auth/gmail.modify

      Read, compose, and send emails from your Gmail account

      https://www.googleapis.com/auth/gmail.readonly

      View your email messages and settings

      https://www.googleapis.com/auth/gmail.settings.sharing

      Manage your sensitive mail settings, including who can manage your mail

  • Enabled S/MIME encryption: An administrator must enable S/MIME in Google Admin for the domain in order for the certificates to work.

    If you are using a private CA, upload your root certificate.
  • Enabled SCM API: Enable API access for your account:

    1. On the Organizations page, select your organization and click Edit.

    2. Select Certificate Settings, then expand the Client Certificates menu.

    3. Enable the Web API option.

      If the option is not available for your account, contact Sectigo Support or the Onboarding Team to have SCM API access enabled.
  • SCM connection parameters: Specify SCM customer-specific connection parameters in the application.properties file to allow the application to obtain client certificates for the Google Workspace domain users.

  • Java 11+: The application requires JDK 11+ for operation, which can be installed with the following command.

    sudo apt install openjdk-11-jre-headles

The application package

The Sectigo Google Workspace S/MIME Connector application package contains the following:

  • smime-connector.jar: The application in the Java archive (JAR) format

  • application.properties: This file contains the SCM customer-specific connection parameters allowing the application to obtain client certificates for the Google Workspace domain users. See The integration parameters for more information.

  • template.json: The service account key file that was downloaded to your machine. The file contains the service account identity information and the private key.

  • input.csv: This file contains email addresses and credentials of Google Workspace users for which client certificates will be provisioned and managed.

The integration parameters

The integration provides various parameters that you can use in different scenarios. These parameters should be specified in the application.properties file.

Service account credentials

The following parameter specifies the path to the service account key file.

Parameter Type Description

googleserviceaccount.credential.jsonfile

Mandatory

The full path to the service account key file

Customer-specific parameters

The following table lists parameters that are required for establishing a connection with Sectigo Certificate Manager (SCM).

Parameter Type Description

sectigo_cm_user

Mandatory

User ID to access your URI

sectigo_cm_password

Mandatory

Password to access your URI

sectigo_cm_uri

Mandatory

Your specific Sectigo URI

sectigo_cm_org_id

Mandatory

Your organization ID (numeric)

sectigo_cm_base_url

Mandatory

The base URL of the Sectigo CA

CSR parameters

The following table lists parameters that are required for generating the certificate signing request (CSR).

Parameter Type Description

sectigo_csr_domain

Mandatory

A single value for a domain included in the certificate Common Name (CN) field.

sectigo_csr_country

Mandatory

The country name included in the certificate Country (C) field.

sectigo_csr_state

Mandatory

The state or province name included in the certificate State (ST) field.

sectigo_csr_location

Mandatory

The location name included in the certificate Location (L) field.

sectigo_csr_organization

Mandatory

The organization name included in the certificate Organization (O) field.

sectigo_csr_organization_unit

Mandatory

The organization unit included in the certificate Organization Unit (OU) field.

sectigo_csr_email_address

Mandatory

The email address included in the certificate emailAddress field.

sectigo_csr_key_algo

Optional

The private key algorithm to use to generate the private key. The default value is RSA.

sectigo_csr_key_size

Optional

The size of the TLS/SSL key to generate. The possible values are:

  • 2048: A 2,048-bit RSA key will be generated (default).

  • 3072: A 3,072-bit RSA key will be generated.

  • 4096: A 4,096-bit RSA key will be generated.

Certificate issuance parameters

The following table lists parameters that are used for certificate issuance.

Parameter Type Description

sectigo_client_cert_file_path

Mandatory

The location where the certificate, CSR, private key, and enrollment IDs are stored.

sectigo_client_cert_type

Mandatory

The type of client certificate (numeric). This is the ID of the client certificate type.

sectigo_client_cert_validity

Mandatory

The certificate validity period in days (numeric). The values available are dependent on the certificate type.

Certificate auto-renewal

sectigo_expiry_window

Optional

The period of days prior to expiration that a new certificate enrollment process will be initiated (numeric). The default expiry window is 30 days.

Collect certificate

sectigo_loop_period

Optional

The interval (in seconds) between repeated attempts to collect a certificate (numeric). The default value is 10.

sectigo_max_timeout

Optional

The maximum time (in seconds) during which repeated attempts to collect a certificate will be made (numeric). The default value is 600.

In addition to the parameters listed in the preceding table, you are required to pass CSR parameters.

Using the application

The following sections explain how to provision and manage client certificates for Google Workspace users.

List the existing certificates

Run the following command in the terminal to list the available S/MIME certificates from a Google Workspace user account.

  • Email user

  • Email alias

java -jar smime-connector-<version>.jar list <[email protected]>
java -jar smime-connector-<version>.jar list <[email protected]> <[email protected]>
List certificates

Provision and upload certificates

The insert command generates keys in the PKCS12 format and uploads the S/MIME certificates to the Google Workspace user accounts listed in the input.csv file. The CSV file should contain entries in the following format.

[email protected], , firstName1, middleName1, lastName1, user1Password
[email protected], [email protected], firstName1, middleName1, lastName1, alias1Password
[email protected], [email protected], firstName1, middleName1, lastName1, alias2Password
[email protected], , firstName2, middleName2, lastName2, user2Password

The .p12 file generated for the user will be copied to the defined certificate location on the system and the password listed in the CSV file will be used to protect the user certificate (the .p12 file).

java -jar smime-connector-<version>.jar insert <path_to_the_csv_file>
Insert certificates

Set the default certificate

The default command sets the default certificate for a Google Workspace user account.

  • Email user

  • Email alias

java -jar smime-connector-<version>.jar default <[email protected]> <certificateID>
java -jar smime-connector-<version>.jar default <[email protected]> <[email protected]> <certificateID>

Renew certificates

The update command renews S/MIME certificates that are within the defined renewal period and uploads them to the Google Workspace user accounts listed in the input.csv file. The CSV file should contain entries in the following format.

[email protected], , firstName1, middleName1, lastName1, user1Password
[email protected], [email protected], firstName1, middleName1, lastName1, alias1Password
[email protected], [email protected], firstName1, middleName1, lastName1, alias2Password
[email protected], , firstName2, middleName2, lastName2, user2Password

The .p12 file generated for the user will be copied to the defined certificate file path on the system and the password listed in the CSV file will be used to protect the user certificate (the .p12 file).

java -jar smime-connector-<version>.jar update <path_to_the_csv_file>
Renew certificates

Delete certificates

The delete command removes S/MIME certificates from a Google Workspace user account.

  • Email user

  • Email alias

java -jar smime-connector-<version>.jar delete <[email protected]>
java -jar smime-connector-<version>.jar delete <[email protected]> <[email protected]>
Delete certificates

Encrypt emails

If you have S/MIME enabled for your Google Workspace account, it automatically encrypts your outgoing emails.

To check if a message you’re sending is encrypted:

  1. Start composing a message.

  2. Add the recipient’s email address to the To field.

  3. To the right of your recipient’s email address, you’ll see a lock icon that shows the level of encryption that is supported by the recipient. If there are multiple users with various encryption levels, the icon will show the lowest encryption level.

  4. To change your S/MIME settings or learn more about your recipient’s level of encryption, click the lock, then View details.

    Recipients with support for S/MIME encryption

View the signature in an email

To verify that emails are properly signed with the sender’s digital signature:

  1. Send a test email to yourself or another recipient, and then open it.

  2. Click Show details. The green lock icon next to the security field means that S/MIME enhanced encryption was used to protect your sensitive data. S/MIME encrypts all outgoing messages if Gmail has the recipient’s public key. Only the recipient with the corresponding private key can decrypt this message.

    Email sender info
  3. Click Sender info. You will see the user’s email address in the Signed by field and the CA name in the Issuer field.

    Sender’s digital signature