Terraform Provider for Windows Active Directory (AD)

The terraform-provider-ad allows you to manage Windows Active Directory objects, specifically users, groups, and group policies, using Terraform configuration.

Warning: Technical Preview This provider is currently in a Technical Preview status. It is a community-supported project that is still in development and is NOT INTENDED FOR PRODUCTION USE. It may contain bugs, undergo significant changes, and is provided on an "as-is" basis without official HashiCorp support.

Starting with version 0.4.0, the provider supports Kerberos authentication for WinRM connections. The provider automatically switches to Kerberos authentication when the krb_realm setting is provided.

If no krb_conf file is supplied, the provider uses a default configuration derived from krb_realm and winrm_hostname.

provider "ad" {
  winrm_hostname = var.hostname
  winrm_username = var.username
  winrm_password = var.password
  krb_realm      = "YOURDOMAIN.COM"
}

To begin using the provider in your Terraform projects:

1. Download the provider: Obtain the latest build from the Terraform Registry.
2. Configure your project: Write your Terraform configuration using the AD provider resources.
3. Initialize: Run terraform init in your Terraform configuration directory. This allows Terraform to detect and install the provider plugin.
4. Explore documentation: Review the docs/ folder in the repository for specific configuration options and the examples/ folder for implementation patterns.

# Run this in your Terraform configuration directory
terraform init

To bring an existing Active Directory user under Terraform management, use the terraform import command with the user's ID.

$ terraform import ad_user 9CB8219C-31FF-4A85-A7A3-9BCBB6A41D02

To use this provider, ensure your environment meets the following requirements:

• Terraform: version 0.12.x or greater
• Windows Server: 2012R2 or greater
• Go: version 1.16.x or greater (if building from source)

To use the AD (Active Directory) provider, ensure the following environment requirements are met:

• Windows Server 2012R2 or greater.
• WinRM must be enabled on the target server(s).

To import an existing group membership into Terraform, use the following ID format: {group_uuid}_{random_uuid}. The group UUID and the random UUID are joined by an underscore.

# Example import using the group's UUID and a random UUID joined by an underscore
$ terraform import ad_group_membership 9CB8219C-31FF-4A85-A7A3-9BCBB6A41D02_E9079B50-95C5-4101-8400-E01CC83CF53B

To bring an existing computer object under Terraform management, use the terraform import command followed by the resource type and the object's ID.

$ terraform import ad_computer 9CB8219C-31FF-4A85-A7A3-9BCBB6A41D02

To bring an existing Active Directory Organizational Unit under Terraform management, use the terraform import command with the resource's GUID.

$ terraform import ad_ou.o 9CB8219C-31FF-4A85-A7A3-9BCBB6A41D02

Starting with version 0.4.3, you can point the provider to a management host that is not a Domain Controller. The provider then performs management tasks through that host.

Requirements for Double Hop:

• Must use winrm_proto = "https".
• Authentication between the management host and the DC is performed via Kerberos.
• The AD PowerShell module and the Group Policy PowerShell Module must be installed on the management server.

Example configuration for a management host:

provider "ad" {
  winrm_hostname         = "10.0.0.1"
  winrm_username         = var.username
  winrm_password         = var.password
  krb_realm              = "YOURDOMAIN.COM"
  krb_conf               = "${path.module}/krb5.conf"
  krb_spn                = "winserver1"
  winrm_port             = 5986
  winrm_proto            = "https"
  winrm_pass_credentials = true
}

If the operating system running Terraform is Windows, you can execute commands locally instead of over WinRM. To enable local execution, you must set winrm_hostname, winrm_username, and winrm_password to null (or empty strings) in the provider configuration.

provider "ad" {
  winrm_hostname = ""
  winrm_username = ""
  winrm_password = ""
}