Domain Join Automation: AWS SSM & Terraform

Mohamed Jawad P
Feb 14 · 4 min read

This blog will help you to automate the domain join process by using Amazon System Manager and Terraform.

Let's talk about what is domain?

The domain is a logical security boundary which holds all the information of the objects within its boundary. Now, to manage all the objects within the boundary you need centralized management. Active Directory (AD) is a Directory service which provides you with a centralized platform for managing Users, Computers, Groups, OUs, Group Policies and several other things that administrators require to manage on daily basis. A server running Active Directory Domain Services (AD DS) is called a Domain Controller.

In AWS Environment, you can easily setup AD by launching AWS EC2 instance with windows server or you can use AWS Directory Service. To know more about AWS Directory Service read our previous blog on the topic here.

Once the AD setup is completed, you need to join the computers/workspaces, server, and other devices to the domain. There are a few steps for the domain join process:

  1. Change/Assign the DNS Entry
  2. Change the Hostname
  3. Reboot the system
  4. Join to the domain using the credentials
  5. Again reboot

This is process will consume a lot of time if you have thousands of workspaces in your company. You can easily automate this process using the Amazon Systems Manager (SSM). To know more about AWS SSM read our previous blog on the topic here. To set up AWS System Manager you need to follow the prerequisite document.

Here the challenge is to install the Amazon-SSM-Agent in the target instance as per the prerequisite of the AWS SSM document. In most of the AWS AMI already pre-installed Amazon-SSM-Agent, if it is not installed you can use “user data” while launching the instance or else install Amazon-SSM-Agent in a newly launched instance on the all the flavors of OS and create an image on it. Use this image to spin the instances.

Terraform automation tool is used to automate the creation process of the SSM Documents and SSM Parameter stores in AWS Account. SSM Parameter store is used to store credentials and other domain information. These parameter store values are used for Domain join in SSM Document scripts.

Use the below link, to store the domain join credentials values like domain name, username, password etc.. in the SSM Parameter store using terraform script.

The first step in this process is to change the DNS entry of the target instances. To change DNS entry, run a terraform script from below link to set the VPC “DHCP Options Sets” using the IP Address of the AD and VPC DNS.

Next, you need to install a few services in all the target instances like aws-cli, realm, sssd etc.. For that you need to create an SSM run command document to install these services.

In Windows, you require only AWS-CLI service for this domain join process. Use the below terraform script link for creating an SSM run command document to install AWS-CLI service.

In Linux, you need to install services like aws-cli, realm, sssd etc. for that you need to create an SSM run command document to install these services. Use the terraform script link shown below to create the document.

Once the SSM document is created, you can run this document from AWS System Manager Console → Run Command. You can run this document to multiple target instances at the same time.

Coming to the domain join process, the first step is to change the hostname of the machine. Here the hostname will be different for each instance. This challenge is solved using the EC2 instance tag. Add a hostname tag in all the EC2 instances as “key=hostname value=<hostname>”. AWS CLI will fetch this tag value and change the hostname of the Instance using the SSM document. Find the terraform script from below link to create SSM run command document for changing the hostname.

Run this document with respect to the OS type. Once the process is successful, the target instances will be restarted.

After a successful reboot of the target instance, you need to perform the domain join step. For that, visit the GitHub link shown below, to create an SSM run command document using terraform script and run it with respect to the OS type of the target instance to join the domain.

For windows:

For Linux:


Once all the SSM documents are run successfully, the domain join process will be completed. You can also verify using “nslookup” command.

Instead of running the terraform script separately, You can also run and create the entire SSM run document in a single step by downloading entire script from our GitHub link shown below:

In the above processes, you need to run 3 SSM run command documents to complete this Domain join process. Instead of using SSM Run Command document, you can also use the AWS SSM Automation document to complete in a single step. Go to the below link to create SSM Automation document for domain join process using terraform script.

This script also helps you to automatically trigger the domain join automation process once the instance is launched successfully. To trigger this automation you need to use AWS Cloudwatch Event Rule and AWS Lambda.

Tensult Blogs

Stories on Cloud computing, Analytics, Automation and Security

Thanks to Dilip Kola, Anirudh Baskaran, and Sumit.

Mohamed Jawad P

Written by

AWS Certified | Cloud Engineer | Automation | Linux Admin | Network Engineer

Tensult Blogs

Stories on Cloud computing, Analytics, Automation and Security