🟧 AWS WorkMail Terraform Module

Provisions an Amazon WorkMail organization together with its registered mail domains, default-domain assignment, users (mailboxes), and groups — secure by default. Built for the AWS provider v6.x.

• 📬 One organization, fully wired. Creates aws_workmail_organization plus its registered domains, the default-domain assignment, users (live mailboxes), and groups — a complete tenant from one module call.
• 🗂️ Directory-flexible. Supply an existing AWS Directory Service directory_id (Simple AD / AD Connector / Managed Microsoft AD) for domain-joined, auditable production use, or leave it null and let WorkMail auto-provision its own directory for lower-friction setups.
• 🔐 CMK-ready encryption. kms_key_arn defaults to null (AWS-managed key) but accepts a customer-managed key — recommended for a regulated FI so key access is independently auditable via CloudTrail.
• 🌐 DNS verification is explicit, not implicit. There is no hosted_zone_id argument on aws_workmail_domain — this module registers the domain and emits the exact DNS records AWS requires; wiring them into Route 53 (e.g. via terraform-aws-route53-zone) is a deliberate, separate step.
• 🙈 No hardcoded passwords, ever. User passwords are supplied per-user through a dedicated user_passwords map marked sensitive = true — never embedded in the main users object, never defaulted.
• 🏷️ Tags on the organization only. aws_workmail_domain, aws_workmail_default_domain, aws_workmail_user, and aws_workmail_group are not taggable in the current provider schema — the documented exception to the universal-tags rule (same shape as terraform-aws-iam-group).

💡 Why it matters: WorkMail mailboxes are live, billed resources the moment they're created, and an organization can't be destroyed cleanly while mail objects still exist underneath it. Getting the directory, encryption, and domain-verification story right in one composite module keeps a regulated FI's email tenant auditable and its destroy path safe.

If these Terraform modules have been helpful to you or your organization, I'd appreciate your support in any of the following ways:

• ⭐ Star this repository to help others discover this Terraform module.
• 🤝 Connect with me on LinkedIn: linkedin.com/in/microsoftexpert
• ☕ Buy me a coffee: buymeacoffee.com/microsoftexpert

Whether it's a star, a professional connection, or a coffee, every gesture helps keep these modules actively maintained and continually improving. Thank you for being part of the community!

terraform-aws-workmail sits just above the identity/directory layer. It optionally consumes a Directory Service directory_id and a KMS CMK arn, and it feeds DNS-verification records forward to Route 53. It does not touch networking, compute, or storage modules.

flowchart LR
 ds["terraform-aws-directory-service (planned)<br/>directory_id (optional)"]
 kms["terraform-aws-kms<br/>CMK arn"]
 r53["terraform-aws-route53-zone<br/>DNS verification records"]
 idc["terraform-aws-iam-identity-center<br/>SSO user id (optional)"]
 wm["terraform-aws-workmail"]

 ds -->|"directory_id (optional)"| wm
 kms -->|"kms_key_arn (optional CMK)"| wm
 wm -->|"domains[*].records"| r53
 idc -.->|"identity_provider_user_id"| wm

 style wm fill:#FF9900,color:#fff,stroke:#cc7a00,stroke-width:2px

ℹ️ terraform-aws-directory-service is not yet part of this repository's authored catalog — until it exists, supply an existing directory id from wherever your Directory Service directory is managed, or leave directory_id = null and let WorkMail self-provision.

flowchart TD
 subgraph mod["terraform-aws-workmail"]
 org["aws_workmail_organization.this<br/>(keystone)<br/>alias + directory + kms + interop"]
 dom["aws_workmail_domain.this<br/>for_each domains"]
 defdom["aws_workmail_default_domain.this<br/>guarded for_each"]
 usr["aws_workmail_user.this<br/>for_each users"]
 grp["aws_workmail_group.this<br/>for_each groups"]
 end

 org --> dom
 org --> defdom
 dom --> defdom
 org --> usr
 org --> grp

 style org fill:#FF9900,color:#fff,stroke:#cc7a00,stroke-width:2px
 style defdom stroke-dasharray: 5 5

The module declares only a required_providers block (providers.tf) and inherits the configured provider. There is no provider {} block and no credential variable — credentials resolve through the standard AWS chain at the root/pipeline level (env vars → SSO/shared credentials → assume_role → instance profile / IRSA → OIDC web identity).

Least-privilege actions the Terraform execution identity needs to manage this module.

⚠️ No iam:PassRole is needed — WorkMail calls Directory Service directly under the executing principal's own permissions, not via an assumed service role.

🔒 Scope workmail:* actions to the organization's ARN once it exists, and gate ds:CreateDirectory / ds:DeleteDirectory separately if your org standard requires directories to be provisioned only by a dedicated directory-service pipeline.

• Every organization requires an underlying directory. Supply an existing Simple AD / AD Connector / Managed Microsoft AD directory_id, or leave it null to let WorkMail auto-provision and manage its own Simple AD directory. The auto-provisioned directory is not a Terraform-managed resource either way — it is only removed on destroy when delete_directory = true.
• Domain verification requires manual/out-of-band DNS records. After registering a domain, read domains[*].records (MX, TXT/SPF, CNAME-DKIM) and create matching records in the domain's Route 53 hosted zone (or external DNS). ownership_verification_status / dkim_verification_status stay PENDING until those records propagate and AWS re-checks them — this module cannot force or await that check.
• WorkMail is a regional service available in a limited set of Regions — confirm the target Region supports WorkMail before use. There is no us-east-1-style global constraint here, but availability is narrower than most services.
• Costs accrue per registered mailbox the moment aws_workmail_user is created (RegisterToWorkMail runs on create). Size the users map deliberately.
• Service quotas: default 1 organization per account/Region (soft, raisable); domains/users/groups scale per current WorkMail service quotas.

terraform-aws-workmail/
├── providers.tf # required_providers (aws >= 6.0, < 7.0); no provider block
├── variables.tf # organization_alias → optional org config → domains/default_domain → users/user_passwords → groups → tags → timeouts
├── main.tf # aws_workmail_organization.this + domain / default_domain / user / group for_each
├── outputs.tf # id + arn + name + state + domains/users/groups maps + tags_all
├── README.md # this file
└── SCOPE.md # in/out-of-scope, IAM permissions, prerequisites, gotchas

Smallest working call — a self-provisioned directory, AWS-managed encryption, one mailbox:

module "workmail" {
  source = "git::https://github.com/microsoftexpert/terraform-aws-workmail?ref=v1.0.0"

  organization_alias = "casey-corp"

  users = {
    jdoe = {
      name         = "jdoe"
      display_name = "Jane Doe"
      email        = "jdoe@casey-corp.awsapps.com"
    }
  }

  tags = {
    Environment = "prod"
    CostCenter  = "1234"
  }
}

module "workmail" {
  source = "git::https://github.com/microsoftexpert/terraform-aws-workmail?ref=v1.0.0"

  organization_alias = "casey-sandbox"
}

module "workmail" {
  source = "git::https://github.com/microsoftexpert/terraform-aws-workmail?ref=v1.0.0"

  organization_alias = "casey-corp"
  directory_id       = "d-1234567890" # existing Managed Microsoft AD / Simple AD / AD Connector
}

module "workmail_kms" {
  source = "git::https://github.com/microsoftexpert/terraform-aws-kms?ref=v1.0.0"
  alias  = "casey/workmail"
}

module "workmail" {
  source = "git::https://github.com/microsoftexpert/terraform-aws-workmail?ref=v1.0.0"

  organization_alias = "casey-corp"
  kms_key_arn        = module.workmail_kms.arn # CMK — auditable/revocable via CloudTrail
}

module "workmail_ephemeral" {
  source = "git::https://github.com/microsoftexpert/terraform-aws-workmail?ref=v1.0.0"

  organization_alias = "casey-dev-ephemeral"

  # OFF by default (directory/app survive destroy) — only safe here because
  # this organization exclusively owns its auto-provisioned directory.
  delete_directory                   = true
  delete_identity_center_application = true
}

module "workmail" {
  source = "git::https://github.com/microsoftexpert/terraform-aws-workmail?ref=v1.0.0"

  organization_alias = "casey-corp"

  domains = {
    primary   = { domain_name = "casey-corp.com" }
    marketing = { domain_name = "casey-marketing.com" }
  }
}

# Read the required DNS records and wire them into terraform-aws-route53-zone:
output "workmail_domain_records" {
  value = module.workmail.domains
}

module "workmail" {
  source = "git::https://github.com/microsoftexpert/terraform-aws-workmail?ref=v1.0.0"

  organization_alias = "casey-corp"

  domains = {
    primary = { domain_name = "casey-corp.com" }
  }

  default_domain = "primary" # must be a key in var.domains
}

locals {
  onboarding_users = {
    jdoe   = { name = "jdoe", display_name = "Jane Doe", email = "jdoe@casey-corp.com", department = "Engineering" }
    bsmith = { name = "bsmith", display_name = "Bob Smith", email = "bsmith@casey-corp.com", department = "Finance" }
    akim   = { name = "akim", display_name = "Amy Kim", email = "akim@casey-corp.com", department = "Compliance" }
  }
}

module "workmail" {
  source = "git::https://github.com/microsoftexpert/terraform-aws-workmail?ref=v1.0.0"

  organization_alias = "casey-corp"
  domains            = { primary = { domain_name = "casey-corp.com" } }
  default_domain     = "primary"

  users = local.onboarding_users
}

module "workmail" {
  source = "git::https://github.com/microsoftexpert/terraform-aws-workmail?ref=v1.0.0"

  organization_alias = "casey-corp"

  users = {
    svc_reporting = {
      name         = "svc-reporting"
      display_name = "Reporting Service Account"
      email        = "svc-reporting@casey-corp.com"
      user_role    = "SYSTEM_USER"
    }
  }

  # Marked sensitive = true — never appears in plan output. Supply from a
  # secrets manager / generated-password module, never a hardcoded literal.
  user_passwords = {
    svc_reporting = var.svc_reporting_initial_password
  }
}

module "workmail" {
  source = "git::https://github.com/microsoftexpert/terraform-aws-workmail?ref=v1.0.0"

  organization_alias = "casey-corp"

  users = {
    conf_room_a = {
      name         = "conf-room-a"
      display_name = "Conference Room A"
      email        = "conf-room-a@casey-corp.com"
      user_role    = "RESOURCE"
    }
  }
}

module "workmail" {
  source = "git::https://github.com/microsoftexpert/terraform-aws-workmail?ref=v1.0.0"

  organization_alias = "casey-corp"

  groups = {
    engineering = { name = "engineering", email = "engineering@casey-corp.com" }
    compliance  = { name = "compliance", email = "compliance@casey-corp.com", hidden_from_global_address_list = true }
  }
}

# Caller's provider block owns default_tags; the module never sets it.
provider "aws" {
  default_tags { tags = { Owner = "platform", ManagedBy = "terraform" } }
}

module "workmail" {
  source = "git::https://github.com/microsoftexpert/terraform-aws-workmail?ref=v1.0.0"

  organization_alias = "casey-corp"

  tags = {
    Environment = "prod" # resource tag — wins over default_tags on key conflict
    DataClass   = "internal"
  }
}

# module.workmail.tags_all == { Owner, ManagedBy, Environment, DataClass }
# (organization only — domains/users/groups are not taggable)

import {
  to = module.workmail.aws_workmail_organization.this
  id = "m-1234567890abcdef1234567890abcdef"
}

module "workmail_hybrid" {
  source = "git::https://github.com/microsoftexpert/terraform-aws-workmail?ref=v1.0.0"

  organization_alias       = "casey-hybrid"
  directory_id             = "d-1234567890"
  interoperability_enabled = true # FORCE-NEW — only for a documented hybrid-Exchange requirement
}

# Customer-managed CMK for organization data
module "workmail_kms" {
  source = "git::https://github.com/microsoftexpert/terraform-aws-kms?ref=v1.0.0"
  alias  = "casey/workmail"
}

# This module — the WorkMail tenant
module "workmail" {
  source = "git::https://github.com/microsoftexpert/terraform-aws-workmail?ref=v1.0.0"

  organization_alias = "casey-corp"
  directory_id       = "d-1234567890" # existing Directory Service directory
  kms_key_arn        = module.workmail_kms.arn

  domains = {
    primary = { domain_name = "casey-corp.com" }
  }
  default_domain = "primary"

  users = {
    jdoe = {
      name         = "jdoe"
      display_name = "Jane Doe"
      email        = "jdoe@casey-corp.com"
      department   = "Engineering"
    }
  }
  user_passwords = {
    jdoe = var.jdoe_initial_password # sensitive — supplied by caller, never hardcoded
  }

  groups = {
    engineering = { name = "engineering", email = "engineering@casey-corp.com" }
  }

  tags = { Environment = "prod", DataClass = "internal" }
}

# Wire the DNS verification records into Route 53
module "workmail_dns" {
  source = "git::https://github.com/microsoftexpert/terraform-aws-route53-zone?ref=v1.0.0"
  #... create records from module.workmail.domains["primary"].records
}

See variables.tf for full heredoc schemas and validation rules.

ℹ️ No tags_all is emitted for domains, the default-domain assignment, users, or groups — none of those resources support tags in the current provider schema.

• ID/ARN format: organization id is m-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx; arn is the cross-resource reference type for scoping workmail:* IAM policy statements.
• Force-new fields: organization_alias, directory_id, kms_key_arn, and interoperability_enabled are all FORCE-NEW on the organization — changing any of them destroys and recreates the entire tenant. domain_name and organization_id are FORCE-NEW on aws_workmail_domain. email is FORCE-NEW on aws_workmail_user.
• tags ↔ tags_all ↔ default_tags: only aws_workmail_organization supports tags in the current provider schema. var.tags flows to it and merges with provider default_tags (resource tags win on key conflict); tags_all is the computed merge. Domains, the default-domain assignment, users, and groups are not taggable — the documented exception, matching the terraform-aws-iam-group precedent.
• No hosted_zone_id on aws_workmail_domain. DNS verification records are exported, not consumed. This module's contract ends at registering the domain and exposing records; creating the matching Route 53 records is terraform-aws-route53-zone's job (or any DNS provider) one layer up.
• aws_workmail_default_domain has no true "unset." There is no API call to revert a default-domain assignment; removing the resource from configuration only stops Terraform from managing it. domain_name is an in-place-updatable argument on this resource (only organization_id is FORCE-NEW), so swapping which domain is default does not recreate anything.
• Eventual consistency: domain ownership/DKIM verification statuses transition from PENDING asynchronously as AWS re-checks DNS — expect a delay between creating records and seeing VERIFIED.
• Destroy ordering: Terraform's implicit dependency graph destroys domains/default-domain/users/groups (all reference aws_workmail_organization.this.organization_id) before the organization. Destroying the organization fails if mailboxes, domains, or groups exist outside this module's state — clean those up first.
• Billing on create: aws_workmail_user registers a live mailbox (RegisterToWorkMail) at creation time and deregisters it on destroy — this is not a lightweight directory-identity resource.
• us-east-1 globals: N/A — WorkMail has no CloudFront/WAFv2/ACM-style global-resource coupling. It does have narrower Regional availability than most services; confirm the target Region supports WorkMail.

Secure-by-default posture and every opt-out, explicitly:

Other principles:

• One composite, one keystone. The organization owns only the resources meaningless without it — domains, the default-domain pointer, users, and groups.
• for_each, never count, for every child collection — keyed by stable caller strings so reorders don't churn the plan. The default-domain assignment uses a guarded single-key for_each.
• Primary outputs id + arn, plus name, state, and tags_all (organization only).
• Secrets isolated, not nested. password is pulled into its own sensitive = true map rather than embedded in the users object, because Terraform can only mark a whole variable sensitive, not a single nested attribute.
• DNS is out of scope by design. Registering a domain and creating its verification records are different concerns owned by different modules.

# Validate without backend or credentials
terraform init -backend=false
terraform validate
terraform fmt -check

plan / apply require valid AWS credentials (profile / SSO / OIDC) resolved through the standard provider chain, plus the IAM actions listed above, and a Region where WorkMail is available.

⚠️ Always pin the module source with ?ref=v1.0.0 — never a branch.

• terraform init -backend=false && terraform validate — schema + reference integrity.
• terraform fmt -check — canonical formatting.
• terraform plan against a sandbox account to confirm the organization, domains, default-domain assignment, users, and groups materialize as expected.
• Assert module.<name>.arn, domains[*].records, and tags_all in your root-module test harness. For user paths, assert user_passwords values never appear in plan output (Terraform redacts sensitive variables automatically).

module.workmail.aws_workmail_organization.this: Creation complete after 3m12s [id=m-1234567890abcdef1234567890abcdef]
module.workmail.aws_workmail_domain.this["primary"]: Creation complete [id=m-1234.../casey-corp.com]
module.workmail.aws_workmail_default_domain.this["this"]: Creation complete
module.workmail.aws_workmail_user.this["jdoe"]: Creation complete [id=m-1234.../12345678-1234-1234-1234-123456789012]

Outputs:
arn = "arn:aws:workmail:us-east-1:123456789012:organization/m-1234567890abcdef1234567890abcdef"
id = "m-1234567890abcdef1234567890abcdef"
default_mail_domain = "casey-corp.com"
domains = { "primary" = { "domain_name" = "casey-corp.com", "ownership_verification_status" = "VERIFIED",... } }
tags_all = { "DataClass" = "internal", "Environment" = "prod" }

• Amazon WorkMail Administrator Guide
• Amazon WorkMail pricing
• AWS Directory Service — directory types
• Terraform: aws_workmail_organization · aws_workmail_domain · aws_workmail_default_domain · aws_workmail_user · aws_workmail_group
• Sibling modules: terraform-aws-kms, terraform-aws-route53-zone, terraform-aws-iam-identity-center
• Module internals: SCOPE.md

🧡 "Infrastructure as Code should be standardized, consistent, and secure."