Automating Microsoft AD and DNS with Terraform & KopiCloud AD API

9 min readMay 15, 2023

In this story, we will discuss how to automate Microsoft Active Directory and Microsoft DNS with Terraform and KopiCloud AD API.

This is my story #150 in Medium, which is very special and is the perfect moment to introduce a project I have been working on since December 2020!

The KopiCloud AD Terraform Provider

This story is part of my KopiCloud AD Terraform Provider series.

I have been deploying Active Directory in AWS, Azure, GCP, and OCI cloud environments for +10 years. I have been using AD since Microsoft launched the public beta in 1999, so this is one of my favorite subjects to write about.

Automating Microsoft AD and DNS with Terraform & KopiCloud AD API (this story)
How to Configure the KopiCloud AD Terraform Provider
How to Create and Manage AD Users with Terraform
How to Deploy KopiCloud AD API from the AWS MarketPlace

1. Intro: A Bit of History

KopiCloud AD API was born many years ago from a personal need, like most of KopiCloud tools.

In 2014, I started a project called KopiBoot, a tool to automate the deployment of Windows applications on the public and private cloud. This project included the initial code to create resources in Active Directory and DNS, used by this API.

I presented the first beta of KopiBoot at an event in Paris; a few minutes later, I saw Mitchell Hashimoto, co-founder of HashiCorp, presenting Terraform, and I decided to scrap the project. 😢

After that, I developed a simple AD API for customers to integrate their existing apps with Active Directory, using part of this code. And then, a dozen of customers were using the API.

2. The Active Directory Terraform Provider

Been Active Directory, one of my favorite products (I started with AD in 1999 with the Beta of Windows Server 2000!), I got extremely frustrated with the lack of Terraform Active Directory and Microsoft DNS providers.

Well, we have the HashiCorp AD provider. Still, it is very limited, is not production ready, and uses a username and password to authenticate. Also, I need a machine with WinRM to use as a gateway (everyone who knows WinRM knows it is very complex to set up in an internal network and even more complicated in cloud environments!)

The limitation of the Terraform AD provider resides in the lack of Active Directory API; it is clear to have a great Terraform module for AD, I will need to build an API first!

The good news is that I wrote one used for years by some of my customers (large insurance companies, government institutions, startups, etc.).

With the help of a small team, we wrote the documentation, tested the system for hundreds of scenarios, added several more methods, and rewritten some API methods to work with Terraform.

I wrote scripts and Terraform code to deploy the API in multiple cloud providers (AWS, Azure, GCP, and OCI) and your servers.

We finished in May 2023 with the Amalfi release of the KopiCloud AD API and the KopiCloud AD Terraform provider.

3. Introducing KopiCloud AD API, the API for Microsoft Active Directory and DNS

KopiCloud AD API is a REST API designed to securely manage Microsoft Active Directory and DNS from custom applications, automation tools, DevOps pipelines, and Terraform.

With KopiCloud AD API, you can:

Integrate Microsoft AD and DNS with your applications or scripts.
Use our Terraform Provider in your CI/CD pipelines without credentials.
Manage AD Users, AD Groups, AD OUs, and AD Computers.
Manage DNS Records and DNS Zones.

3.1. Compatibility

Compatible with AWS, Azure, GCP, and OCI VMs running AD DCs.
Compatible with AWS, Azure, and GCP Active Directory Managed Services.

Note: currently is only supported in Windows Servers in English.

4. Installing KopiCloud AD API Server

The KopiCloud AD API can be deployed using Cloud Provider Marketplace images, setup scripts, Terraform code, or the setup application.

Check the Download page or our GitHub repo for details. We are working on adding more options, and some of them, such as Cloud Marketplace images, can take several weeks to get approved.

The process of setting up a KopiCloud AD API server is straightforward.

Get a License — Generate a free trial license (no credit card required) or purchase a license here.
Install KopiCloud AD API; check the options on our download page.
Join the machine to the AD Domain we will manage using the API.
Create a Service Account with Domain Administrators permissions for the KopiCloud AD API.
Run the KopiCloud AD API Config tool to configure a few final settings.

Check the documentation page for more details.

4.1. Installing from Cloud Provider Marketplaces

Go to your cloud provider marketplace, and search for kopicloud:

Note: at the moment of writing this story (May 2023), KopiCloud AD API is available in the AWS Marketplace. Coming soon to Azure and GCP Marketplaces.

4.2. Installing using Terraform

Go to our download page, and download the Terraform Code for your cloud provider:

Note: at the moment of writing this story (May 2023), we have Terraform code to deploy KopiCloud AD API in Amazon Web Services (AWS), Microsoft Azure, Google Cloud (GCP), and Oracle Cloud (OCI) for both Windows Server 2019 and 2022.

4.3. Installing KopiCloud AD API in any server

Go to our download page, and download a PowerShell to deploy KopiCloud AD API in any Windows Server 2019 and 2022.

5. Creating KopiCloud AD API Authentication Tokens

KopiCloud AD API supports two types of tokens: JWT Token and Basic Token.

This token will authenticate to the API from application integrations, the API Swagger, and the Terraform Provider.

5.1. Login to the KopiCloud AD API Management Portal

Enter your username and password to log in:

And click on the Login button.

5.2. Create JWT Token

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object.

This information can be verified and trusted because it is digitally signed.

JWT tokens are recommended for applications like Terraform and can expire automatically.

To create a JWT Token, login to the KopiCloud AD API Management Portal and click on the JWT Token menu.

Enter a unique token name and expiration time (or 0 to create a not-expiring token) and click the Generate button.

Then, the token will be generated. Copy the token and store it in a safe place!

5.3. Create a Basic Token

Basic tokens are created by combining a username and password.

To create a Basic Token, login to the KopiCloud AD API Management Portal and click on the Basic Token menu.

Enter your username and password and click on the Generate button.

Note: If you change your password, you must regenerate your Basic Token.

Then, the token will be generated. Copy the token and store it in a safe place!

6. Set up the KopiCloud AD API Terraform Provider

In your "provider.tf" file, configure the KopiCloud AD Terraform Provider with the host, the URL of your KopiCloud AD API server, and the token, the token generated in the previous step.

terraform {
  required_providers {
    kopicloud = {
      source = "kopicloud-ad-api/ad"
    }
  }
}

provider "kopicloud" {
  host  = "https://api.kopicloud.local"
  token = "Basic b3NjYWI8UzFsdkyQMVsuD70"
}

7. Automating Microsoft Active Directory with Terraform and KopiCloud AD API

Let's look at what is possible with the KopiCloud AD Terraform Provider and Microsoft Active Directory.

7.1. AD Terraform Resources

The provider includes Terraform Resources to manipulate AD resources:

kopicloud_computer: Create, Update, or Destroy an AD Computer
kopicloud_distribution_group: Create, Update, or Delete an AD Distribution Group
kopicloud_security_group: Create, Update, or Delete an AD Security Group
kopicloud_group_membership: Add an AD User to an AD Group
kopicloud_ou: Create, Update, or Delete an AD Organization Unit (OU)
kopicloud_user: Create, Update, or Delete an AD User
kopicloud_user_disable_account: Disable an AD User
kopicloud_user_enable_account: Enable an AD User
kopicloud_user_password_reset: Reset the Password of an AD User
kopicloud_user_rename_account: Rename an AD User
kopicloud_user_unlock_account: Unlock an AD User

7.2. AD Terraform Data Sources

The provider includes Terraform Data Sources to list existing AD resources:

kopicloud_computer_list: List AD Computers
kopicloud_distribution_group_list: List AD Distribution Groups
kopicloud_security_group_list: List AD Security Groups
kopicloud_group_list: List all AD Groups
kopicloud_group_membership_list: List AD Groups Associated with an AD Username
kopicloud_ou_list: List AD Organization Units (OUs)
kopicloud_user_list: List Users in the AD

8. Automating Microsoft DNS with Terraform and KopiCloud AD API

Let’s look at what is possible with the KopiCloud AD Terraform Provider and Microsoft DNS.

8.1. DNS Terraform Resources

The provider includes Terraform Resources to manipulate DNS Records and DNS Zones:

kopicloud_dns_a_record: Create and remove DNS A Records
kopicloud_dns_aaaa_record: Create and remove DNS AAAA Records
kopicloud_dns_cname_record: Create and remove DNS CNAME Records
kopicloud_dns_lookup_zone: Create and remove DNS Lookup Zones
kopicloud_dns_reverse_lookup_zone: Create and remove DNS Reverse Lookup Zones

8.2. DNS Terraform Data Sources

The provider includes Terraform Data Sources to list existing DNS Records and DNS Zones:

kopicloud_dns_a_records_list: List DNS A Records
kopicloud_dns_aaaa_records_list: List DNS AAAA Records
kopicloud_dns_cname_records_list: List DNS CNAME Records
kopicloud_dns_zone_list: List All DNS Zones
kopicloud_dns_lookup_zone_list: List DNS Lookup Zones
kopicloud_dns_reverse_lookup_zone_list: List DNS Reverse Lookup Zones

9. AD Terraform Example

In this simple example, we will add an AD User to a new AD Group.

First, we will create an AD Global Security Group:

resource "kopicloud_security_group" "marketing" {
  name        = "marketing-security-group"
  scope       = "Global"
  description = "This is the marketing global security group"
  email       = "marketing-security-group@kopicloud.com"
  ou_path     = "CN=Users,DC=kopicloud,DC=local"
}

Then, we will create an AD User:

resource "kopicloud_user" "robert" {
  username      = "rsmith"
  password      = var.password
  first_name    = "Robert"
  initials      = "T"
  last_name     = "Smith"
  display_name  = "Robert T Smith"
  company       = "KopiCloud Limited"
  description   = "Marketing Director"
  department    = "Marketing"
  email_address = "robert.smith@kopicloud.net"
}

And finally, we will add the AD User to the AD Group:

resource "kopicloud_group_membership" "marketing" {
  depends_on = [kopicloud_security_group.marketing, kopicloud_user.robert]

  user_name  = kopicloud_user.robert.username
  group_name = kopicloud_security_group.marketing.name
}

10. DNS Terraform Example

This simple example will list all DNS A Records in the kopicloud.local zone:

data “kopicloud_dns_a_records_list” “test” {
  zone_name = "kopicloud.local"
}

And we will use an output to return all DNS A Records that match the Zone Name:

output "OUTPUT_dns_a_records_list_zone_name" {
  description = "List existing DNS A Records filtered by Zone Name"
  value = data.kopicloud_dns_a_records_list.test
}

In future stories, we will explore the KopiCloud AD Terraform Provider in detail.

Explore the KopiCloud AD API repo at https://github.com/KopiCloud-AD-API. There are examples for all the resources and data sources. And lots of scripts to test and evaluate the Terraform provider.

Visit the KopiCloud AD API website for more details about the REST API and the Terraform Provider at https://adapi.kopicloud.com

And that’s all, folks. If you liked this story, please show your support by 👏 this story. Thank you for reading!