Setting up DKIM for Google Workspace (Gmail) using Terraform and AWS Route 53

Ercan,

DKIM (DomainKeys Identified Mail) is a critical email authentication technique that helps prevent email spoofing. By using DKIM, you digitally sign your email headers with a private key, and the recipient verifies this signature using your public key, which is stored in the DNS records of your domain. Google Workspace (formerly G Suite) leverages DKIM to ensure the emails sent from your domain are verified as coming from you and not a spammer pretending to be you.

In this article, we’ll dive into how to use Terraform to configure DKIM for Google Workspace, using AWS Route 53 for DNS management. This approach is perfect if you’re already managing your infrastructure as code and want to automate the process of creating DNS records for DKIM.

Let’s break down the Terraform block you’ve provided and go step-by-step through what each part does.

1. Overview of the DKIM Process

Before diving into the Terraform code, let’s recap how DKIM works:

  • Signing Outgoing Emails: Google Workspace signs the outgoing email headers with a private key. The domain owner configures the public key as a DNS record.
  • Verifying Incoming Emails: The recipient’s email server fetches the public key from DNS to verify the signature and ensure that the email has not been tampered with during transit.

To set up DKIM, you’ll create a TXT record in your DNS, containing the public key generated by Google Workspace.

2. Terraform Block Breakdown

The provided Terraform block creates a TXT record in AWS Route 53, which is essential for publishing the DKIM public key for Google Workspace. Here’s a breakdown of each part of the block:

a. Local Variable for DKIM Record

locals {
  dkim_record = "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4FbZGvaSuBW9yDhuswEA6S7QRRZlvvS3Rc6xRK92QJ44+IUoobJf+S3VZGSjdv5Jmpu57JGaq1KsObB5DwObvCW6yhJb6rGd0bgXqTzkfHH7sxnkEbDbNEIyUhxuEbUdWE1KtFz0QMb+GMhxC+j+kntpXtVDWugp9lSa7cnkFVho/gRwVkz47QFD1kQjvP9/QraYZo63M5DObFRFF4rDHvBzNTGl6+FC0OkyA49f19iw1+eFtLWu8BpVIn4HxxZWn04i1KHnm1AX9BztBAoVbJ0ZlF1tEJ5eLMPQg5l0BUcSEYi1RcBKTJU+AJ17fGAJEGr7Ft47SJgHdN9XUPH9NwIDAQAB"
}

Here, the locals block defines a local variable dkim_record. This variable stores the DKIM public key in the format required for DNS.

  • v=DKIM1: Specifies the version of DKIM being used.
  • k=rsa: The type of cryptography used; Google typically uses RSA.
  • p=MIIBIjAN…: The public key itself. This key is generated by Google Workspace and is unique to your domain.

b. Creating the DKIM Record in Route 53

resource "aws_route53_record" "google_domainkey_TXT" {
  zone_id = aws_route53_zone.domain_com.zone_id
  name    = "google._domainkey"
  type    = "TXT"
  ttl     = 300
  records = [
    replace(local.dkim_record, "/(.{255})/", "$1\"\"")
  ]
}

This aws_route53_record resource block is responsible for creating the DNS record in your Route 53 hosted zone. Let’s break down each attribute:

  • zone_id: This refers to the hosted zone in AWS Route 53 where the record will be added. The aws_route53_zone.domain_com.zone_id references the Route 53 zone for your domain, which Terraform can manage dynamically.
  • name: The name attribute specifies the DNS name for the record. In this case, it’s set to google._domainkey. This is the specific subdomain that Google Workspace expects for storing DKIM records. The google._domainkey prefix is required by Google to find the public key for verifying DKIM signatures.
  • type: The type of record is set to TXT. DKIM records are stored as TXT records in DNS.
  • ttl: The TTL (Time to Live) is set to 300 seconds (5 minutes). This determines how long DNS resolvers should cache the record before fetching it again.
  • records: This field holds the actual content of the TXT record, which is the DKIM public key. Since DKIM public keys can often exceed 255 characters (the maximum length for a single DNS TXT record), Terraform is using a replace() function to split the string into 255-character chunks.

c. Splitting Long DKIM Records

The replace() function used in this configuration is critical:

replace(local.dkim_record, "/(.{255})/", "$1\"\"")

This line ensures that the DKIM record is split into smaller sections of 255 characters, as DNS servers have a limit on how long a single TXT record can be. The replace() function uses a regular expression to break the string into these chunks and adds the necessary quotes between them.

3. Why Use Terraform for DKIM?

There are a few good reasons to use Terraform for setting up your DKIM DNS records:

  • Automated DNS Management: With Terraform, you can manage your Route 53 DNS records as code. This makes it easy to version control your DNS configurations, ensure consistency, and reduce manual errors.
  • Repeatability: Once the Terraform script is written, you can easily apply it across multiple environments or domains. This is especially useful for managing multiple domains or when you need to re-provision infrastructure.
  • Infrastructure as Code (IaC): Managing infrastructure using code allows for better documentation, collaboration, and auditing. Any changes to your DNS settings are recorded in your version control system (e.g., Git), giving you a clear history of who made changes and why.

4. Steps to Configure DKIM for Google Workspace

To complete the DKIM setup for Google Workspace, you’ll need to follow these steps:

  1. Generate the DKIM key in Google Workspace:
    • Go to your Google Admin Console.
    • Navigate to Apps > Google Workspace > Gmail > Authenticate Email.
    • Generate a new DKIM key for your domain and copy the provided public key.
  2. Apply the Terraform Configuration:
    • In your Terraform configuration file, set the dkim_record local variable to the public key generated by Google Workspace.
    • Run the following commands to apply the configuration to AWS Route 53:
terraform init
terraform plan
terraform apply
  • This will create the DKIM TXT record in your Route 53 DNS zone.
  1. Enable DKIM Signing in Google Workspace:
    • After the DNS record has propagated (this may take a few minutes), return to the Google Admin Console.
    • Go back to the Authenticate Email page and click on Start Authentication. This enables DKIM signing for your domain.

5. Verifying Your DKIM Setup

Once DKIM is enabled, you can test whether it’s working by sending an email from your Google Workspace account to a service like DKIMCore’s DKIM validator or other email testing tools. These services will tell you if the DKIM signature is being applied correctly and if the DNS record is set up properly.

Conclusion

Using Terraform to manage DKIM records for Google Workspace and AWS Route 53 streamlines the process of configuring and maintaining your email authentication setup. By automating this with Infrastructure as Code (IaC), you gain the benefits of reproducibility, auditability, and ease of management, all while ensuring your emails are protected from spoofing and other email-based attacks.

With this configuration, you now have a solid DKIM setup that enhances the security of your email communications, ensuring that recipients can trust the messages you send from your domain. Happy Terraforming!

AWS DevOps