Automate domain join for Amazon EC2 instances from multiple AWS Areas and accounts

As organizations scale upward their Amazon Web Services (AWS) presence, they’re faced with the task of administering user identities and controlling access across multiple Regions and accounts. As this existence grows, managing user usage of cloud assets such as for example Amazon Elastic Compute Cloud (Amazon EC2) becomes increasingly complex. AWS Directory Service for Microsoft Active Directory (also referred to as an AWS Managed Microsoft AD) helps it be easier and much more cost-effective so that you can manage this complexity. AWS Managed Microsoft Advertisement is made on available highly, AWS maintained infrastructure. Each directory will be deployed across several Availability Zones, and supervising detects and replaces domain controllers that fail automatically. In addition, information replication and automated everyday snapshots are usually configured for you. You need to install software don’t, and AWS handles all software program and patching updates. AWS Managed Microsoft Advertisement allows you to leverage your current on-premises consumer credentials to gain access to cloud resources like the AWS Management Gaming console and EC2 instances.

This website post describes how EC2 resources released across several AWS accounts and Areas can automatically domain-join a centralized AWS Managed Microsoft AD. The perfect solution is we describe in this article is implemented for both Linux and Windows instances. Removal of Computer items from Energetic Directory upon example termination can be implemented. The answer uses Amazon DynamoDB to centrally shop account and directory info in a central safety account. We provide AWS CloudFormation templates and platform-particular domain join scripts to work with with AWS Lambda as an instant start solution.


The next diagram shows the domain-join process for EC2 instances across several accounts and Areas using AWS Managed Microsoft AD.

Determine 1: EC2 domain join architecture

Physique 1: EC2 domain join architecture

The function flow works the following:

  1. An EC2 example is launched in a peered virtual private cloud (VPC) of a workload or security accounts. VPCs which are hosting EC2 situations have to be peered with the VPC which has AWS Managed Microsoft Advertisement make it possible for network connectivity with Energetic Directory.
  2. An Amazon CloudWatch Events guideline detects an EC2 instance within the “running” condition.
  3. The CloudWatch event is forwarded to a regional CloudWatch event bus in the security account.
  4. If the CloudWatch event bus is in exactly the same Region as AWS Managed Microsoft AD, it delivers the function to an Amazon Simple Queue Service (Amazon SQS) queue, known as the domain-join queue in this article.
  5. If the CloudWatch event bus is in another Region from AWS Managed Microsoft AD, it delivers the function to an Amazon Simple Notification Service (Amazon SNS) topic. The function is sent to the domain-sign up for queue described in step 4 then, through the Amazon SNS topic membership.
  6. Messages within the domain-sign up for queue are usually held for 5 minutes to permit for EC2 situations to stabilize once they reach the “operating” condition. This delay allows period for installing additional software parts and agents by using EC2 user data and AWS Systems Manager Distributor.
  7. After the holding period over is, messages in the domain-join queue invoke the AWS AD Sign up for/Leave Lambda function. The Lambda perform does the next:
    1. Retrieves the AWS accounts ID that originated the function from the information and retrieves account-particular configurations from the DynamoDB table. This construction identifies AWS Managed Microsoft Advertisement domain controller IPs, credentials necessary to sign up for perform EC2 domain, and an AWS Identity and Access Management (IAM) role which can be assumed by the Lambda functionality to invoke AWS Systems Manager Run Command.
    2. If needed, uses AWS Security Token Service (AWS STS) and prepares a cross-account access program.
    3. Retrieves EC2 example information, like the instance state, system, and tags, and validates the example state.
    4. Retrieves platform-particular domain-join scripts which are deployed with the Lambda function’s program code bundle, and configures invocation of these scripts through the use of data study from the DynamoDB desk (bash script for Linux situations and PowerShell script for Home windows instances).
    5. Uses AWS Techniques Manager Run Control to invoke the domain-sign up for script on the example. Work Command allows you to and securely manage the construction of one’s managed instances remotely.
    6. The domain-join script works on the instance. It uses script instance and parameters characteristics to configure the instance and perform the domain join. The adGroupName tag worth can be used to configure the Energetic Directory user team that may have permissions to get on the instance. The example is rebooted to perform the domain join procedure. Various software elements are set up on the instance once the script works. For the Linux example, sssd, realmd, krb5, samba-typical, adcli, unzip, and packageit are usually installed. For the Home windows instance, the RDS-RD-Server function is installed.

Removal of EC2 situations from AWS Managed Microsoft Advertisement upon example termination follows an identical sequence of measures. Each instance that’s domain joined creates a dynamic Directory domain object beneath the “Personal computer” hierarchy. This domain item must be removed upon example termination so that a fresh instance that uses exactly the same private Ip in the subnet (at another time) can effectively domain sign up for and enable example access with Dynamic Directory credentials. Elimination of the Energetic Directory Computer item is done by working the leaveDomaini.ps1 script (incorporated with this website) through Run Command about the Dynamic Directory Tools example identified in Figure 1.

Prerequisites and set up

To build the perfect solution is outlined in this article, you need:

  • AWS Managed Microsoft AD having an appropriate DNS title (for instance, example.com). To learn more about getting started off with AWS Managed Microsoft Advertisement, see Create Your AWS Managed Microsoft AD directory.
  • AD Equipment. To set up AD Tools and utilize it to create the mandatory users:
    1. Launch the Windows EC2 example in exactly the same Region and account, and domain-sign up for it with the directory you produced in the last step. Get on the example through Remote Desktop Process (RDP) and install Advertisement Equipment as described in Installing the Active Directory Management Tools.
    2. After the AD Equipment are installed, release the AD Users & Computer systems application to generate domain customers, and assign those customers to a dynamic Directory security group (for instance, my_UserGroup) which has permission to gain access to domain-joined instances.
    3. Create the least-privileged user for executing domain joins as explained inside Delegate Directory Join Privileges for AWS Managed Microsoft AD. The identity of the user is kept in the DynamoDB desk and examine by the Advertisement Join Lambda functionality to invoke Energetic Directory sign up for scripts.
    4. Shop the password for the least-privileged user within an encrypted Systems Manager parameter. The password because of this user is saved in the protected string System Supervisor parameter and read by the Advertisement Join Lambda functionality at runtime while digesting Amazon SQS messages.
    5. Assign a distinctive tag value and essential to recognize the AD Tools example. This instance will undoubtedly be invoked by the Lambda functionality to delete Computer items from Energetic Directory upon termination of domain-joined instances.
  • All VPCs which are hosting EC2 situations to be domain joined up with should be peered with the VPC that hosts the relevant AWS Managed Microsoft AD. Alternatively, AWS Transit Gateway could possibly be used to determine this connectivity.
  • In add-on to having network online connectivity to the AWS Managed Microsoft Advertisement domain controllers, domain join scripts that operate on EC2 instances should be in a position to resolve relevant Dynamic Directory resource information. In this remedy, we leverage Amazon Route 53 Outbound Resolver to forwards DNS queries to the AWS Managed Microsoft AD DNS servers, while nevertheless preserving the default DNS capabilities that are offered to the VPC. Find out more about deploying Route 53 Outbound Resolver and resolver rules to solve your directory DNS name to DNS IPs.
  • Each domain-join EC2 instance will need to have a Systems Supervisor Agent (SSM Broker) installed and an IAM part that delivers equivalent permissions as supplied by the AmazonEC2RoleforSSM built-in plan. The SSM Agent can be used to permit domain-join scripts to perform automatically. See Working with SSM Agent to learn more in installing and configuring SSM Brokers about EC2 instances.

Solution deployment

The steps in this section deploy AD Sign up for solution components utilizing the AWS CloudFormation service.

The CloudFormation template given this solution (mad_auto_join_leave.json) deploys sources that are identified inside the protection account’s AWS Area that hosts AWS Managed Microsoft Advertisement (the very best left quadrant highlighted inside Number 1). The template deploys a DynamoDB reference with 5 read and 5 write capacity devices. This will be adjusted to fit your usage. DynamoDB supplies the ability to auto-level these capacities also. You shall have to create and deploy extra CloudFormation stacks for cross-account, cross-Region scenarios.

To deploy the solution

  1. Create the versioned Amazon Simple Storage Service (Amazon S3) bucket to store a zip file (for instance, adJoinCode.zip) which has Python Lambda program code and domain join/keep bash and PowerShell scripts. Upload the foundation code zip document to an S3 bucket and discover the version linked to the object.
  2. Navigate to the AWS CloudFormation gaming console. Pick the appropriate AWS Area, and choose Create Stack then. Select With brand-new resources.
  3. Choose Upload a template document (because of this solution, mad_auto_join_leave.json), choose the CloudFormation stack document, and choose Next then.
  4. Enter the stack ideals and name for another parameters, and choose Next.

    Body 2: Defining the stack title and parameters

    Number 2: Defining the stack title and parameters

    The parameters are thought as follows:

  • S3CodeBucket: The title of the S3 bucket that keeps the Lambda program code zip file item.
  • adJoinLambdaCodeFileName: The title of the Lambda program code zip file which includes Lambda Python program code, bash, and Powershell scripts.
  • adJoinLambdaCodeVersion: The S3 Edition ID of the uploaded Lambda program code zip file.
  • DynamoDBTableName: The title of the DynamoDB desk which will hold account configuration details.
  • CreateDynamoDBTable: The flag that indicates whether to produce a new DynamoDB desk or use a preexisting table.
  • ADToolsHostTagKey: The tag crucial of the Home windows EC2 instance which has AD Equipment installed and which will be useful for removal of Dynamic Directory Computer items upon example termination.
  • ADToolsHostTagValue: The tag worth for the main element identified by the ADToolsHostTagKey parameter.
  • Acknowledge development of AWS assets and choose to continue steadily to deploy AWS sources through AWS CloudFormation.The CloudFormation stack creation process is set up, and after a couple of minutes, upon completion, the stack status is marked as CREATE_COMPLETE. The next resources are created once the CloudFormation stack deploys effectively:
    • An Advertisement Join Lambda functionality with connected IAM and scripts role.
    • A CloudWatch Events principle to detect the “working” and “terminated” claims for EC2 instances.
    • An SQS event queue to carry the EC2 instance “jogging” and “terminated” events.
    • CloudWatch event mapping to the SQS event queue and additional to the Lambda perform.
    • A DynamoDB desk to carry the account configuration (in the event that you chose this program).

The DynamoDB table hosts account-level configurations. Account-specific construction is necessary for an example from the given account to become listed on the Dynamic Directory domain. Each DynamoDB product contains the account-specific construction shown in the next table. Storing account-level info in the DynamoDB desk provides the capability to use several AWS Managed Microsoft Advertisement directories and group different accounts accordingly. Additional accounts configurations may also be kept in this desk for implementation of varied centralized security services (example inspection, patch administration, and so forth).

AttributeDescriptionaccountIdAWS account numberadJoinUserNameConsumer ID with AD Sign up for permissionsadJoinUserPwParamEncrypted Systems Supervisor parameter containing the Advertisement Join user’s passworddnsIP1Domain controller 1 IP deal with2dnsIP2Domain controller 2 IP tackleassumeRoleARNAmazon Resource Title (ARN) of the function assumed by the Advertisement Join Lambda functionality

Following is an exemplory case of the method that you could insert something (row) in the DynamoDB table for a merchant account.

aws dynamodb put-item --table-title  --item document://itemData.json

where itemData.json is really as follows.

    "accountId":  "S": "123412341234" ,
    " adJoinUserName":  "S": "ADJoinUser" ,
    " adJoinUserPwParam":  "S": "ADJoinUser-PwParam" ,
    "dnsName":  "S": "example.com" ,
    "dnsIP1":  "S": "" ,
    "dnsIP2":  "S": "" ,
    "assumeRoleARN":  "S": "arn:aws:iam::111122223333:part/adJoinLambdaRole" 

(Update with your personal values as befitting your environment.)

In the preceding illustration, adJoinLambdaRole is assumed by the AD Sign up for Lambda function (if required) to determine cross-account access using AWS Security Token Service (AWS STS). The role must provide enough privileges for the Advertisement Join Lambda functionality to retrieve instance details and run cross-account Techniques Manager commands.

adJoinUserName identifies a consumer with the minimum amount privileges to accomplish the domain join; this user was made by you in the prerequisite steps.

adJoinUserPwParam identifies the title of the encrypted Techniques Manager parameter that shops the password for the Advertisement Join user. This parameter was made by you in the prerequisite steps.

Solution test

After you deploy the answer using the steps in the last section successfully, the next thing is to check the deployed solution.

To check the solution

  1. Navigate to the AWS EC2 system and launch the Linux instance. Start the example in a open public subnet of the accessible VPC.
  2. Select an IAM function that gives at the very least AmazonEC2RoleforSSM permissions to the example.
  3. Include an adGroupName tag along with the worthiness that identifies the title of the Dynamic Directory security team whose members must have usage of the instance.
  4. Make sure the security group connected with your example has permissions for the IP address to get on the instance utilizing the Secure Shell (SSH) process.
  5. Wait around for the example to start and perform the Dynamic Directory domain join. It is possible to demand AWS SQS gaming console and observe a delayed information that represents the CloudWatch example “running” event. This information is processed after 5 minutes; then you can take notice of the Lambda function’s information processing sign in CloudWatch logs.
  6. Log into the instance with Dynamic Directory user credentials. This user should be the known person in the Active Directory security group identified by the adGroupName tag value. Following can be an example login command.
    ssh ‘user1@example.com’@<public-dns-name|public-ip-deal with>
  7. Likewise, launch a Home windows EC2 example to validate the Active Directory domain join through the use of Remote Desktop Protocol (RDP).
  8. Terminate domain-joined up with instances. Get on the AD Tools example to validate that the Energetic Directory Computer item that represents the example is deleted.

The AD Sign up for Lambda function invokes Systems Supervisor commands to provide and work domain join scripts in the EC2 instances. The AWS-RunPowerShellScript control can be used for Microsoft Home windows instances, and the AWS-RunShellScript command can be used for Linux situations. Techniques Manager order parameters and execution position can be seen in the operational systems Supervisor Run Command console.

The AD user used to execute the domain join is really a least-privileged user, as referred to in Delegate Directory Join Privileges for AWS Managed Microsoft AD. The password because of this consumer is passed to situations through SSM Run Instructions, as defined above. The password is seen in the SSM Order background log and in the domain sign up for scripts operate on the instance. Additionally, all script parameters could be read on the example through the “adjoin” encrypted SSM parameter locally. Make reference to the domain sign up for scripts for information on the “adjoin” SSM parameter.

Additional information

Directory sharing

AWS Managed Microsoft Advertisement can be distributed to other AWS accounts inside the same Region. Figure out how to use this function and seamlessly domain sign up for Microsoft Windows EC2 instances and Linux instances.

autoadjoin tag

Launching EC2 instances having an autoadjoin tag major with a “false” price excludes the instance through the automated Energetic Directory join practice. You might like to do that in scenarios where you intend to install additional agent software program before or following the Dynamic Directory join process. It is possible to invoke domain sign up for scripts (bash or PowerShell) through the use of user data or additional indicates. However, you’ll have to reboot the example and re-operate scripts to perform the domain join procedure.


In this website post, we demonstrated the way you could automate the Dynamic Directory domain join course of action for EC2 instances to AWS Managed Microsoft AD across several accounts and Regions, and in addition centrally manage this configuration through the use of AWS DynamoDB. By adopting this design, administrators can manage Active Directory-aware applications and resources across their accounts centrally.

When you have feedback concerning this post, submit remarks in the Comments section below. Should you have questions concerning this post, contact AWS Support.

Want a lot more AWS Security how-to articles, news, and show announcements? Stick to us on Twitter.

%d bloggers like this: