Menu
Amazon Elastic Compute Cloud
User Guide for Windows Instances

Joining a Windows Instance to an AWS Directory Service Domain

You can join an Amazon EC2 Windows instance to an active AWS Directory Service directory or AD Connector directory using Amazon EC2 Systems Manager (SSM) Config. To perform this task with SSM Config, you use the AWS CLI or AWS Tools for Windows PowerShell to create an SSM document that specifies the domain join details, and then associate the SSM document with a running instance.

Alternatively, you can use the launch instance wizard in the Amazon EC2 console to launch an instance and specify the domain that you want to join. The wizard searches for any existing SSM documents for the domain in your account to associate with your instance; if it can't locate one, it creates an SSM document for you, and immediately associates it with your running instance.

Note

The Windows Server 2016 Nano server installation option (Nano Server) does not support online domain joining. You must perform an offline domain join instead. For more information, see Offline Domain Join (Djoin.exe) Step-by-Step Guide on Microsoft TechNet.

After you've associated the SSM document with your instance, you can connect to the instance using domain credentials you've defined in your AWS Directory Service directory.

There's no additional charge for using SSM Config or joining your instance to a domain. Standard charges for instance usage and AWS Directory Service usage apply.

For more information about SSM Config, see Managing Windows Instance Configuration.

Limitations

  • SSM Config is supported only for Windows instances.

  • SSM Config is available in the following regions.

In other regions, you can manually join an instance to a domain. For more information, see Joining an Instance to an AWS Directory Service Directory in the AWS Directory Service Administration Guide.

Prerequisites

  • To join a domain, ensure that you have the following resources available or configured in your AWS account:

    • An active AWS Directory Service directory. For more information about creating a directory, see Getting Started with AWS Directory Service in the AWS Directory Service Administration Guide.

      • To create a directory, you must have a VPC with two subnets. For more information about creating a VPC, see What is Amazon VPC? in the Amazon VPC User Guide. Instances that you join to the domain must be launched into the same VPC in which your domain is located.

    • A Windows instance that meets the requirements described in Prepare the Instance.

    • An Internet connection for your instance, so that it can communicate with SSM Config. Ensure that you have a public subnet into which to launch your instance, and ensure that your instance has a public IP address. Alternatively, you can launch your instance into a private subnet without assigning it a public IP address, and use a NAT instance in a public subnet to initiate traffic to the Internet. For more information about NAT, see NAT Instances in the Amazon VPC User Guide.

  • If you are using the AWS CLI or the AWS Tools for Windows PowerShell to create a configuration document, you need the following information:

    • The name and ID of the directory to join.

    • The IP addresses of the DNS servers in the AWS Directory Service directory. For more information, see Get the DNS Server Address in the AWS Directory Service Administration Guide.

Configure Permissions for SSM

To join an instance to an AWS Directory Service Domain using SSM, you must configure permissions on the instance that will be joined to the domain and for any users who will use SSM. IAM managed policies for SSM can help you quickly configure access and permissions for users and instances. You can find these policies in the IAM console by searching for SSM, as shown in the following screen shot.


						IAM managed policies for SSM

The managed policies perform the following functions:

  • AmazonEC2RoleForSSM (instance trust policy): This policy enables the instance to communicate with the SSM Config API. You must assign this policy to the instance that you will join to the domain using SSM Config.

  • AmazonSSMFullAccess (user trust policy): This policy gives a user access to the SSM Config API and SSM documents. To join an instance to a domain, your IAM account must be assigned either this policy or a comparable policy that you created. If delegating access to another user, assign this policy to administrators and trusted power users only.

  • AmazonSSMReadOnlyAccess (user trust policy): This policy gives a user access to read-only API actions such as Get and List. Users assigned this policy can't make changes on instances using SSM Config.

For information about how to configure these policies, see Managed Policies and Inline Policies.

Joining a Domain Using the AWS CLI or AWS Tools for Windows PowerShell

To use the AWS CLI or the AWS Tools for Windows PowerShell to join a domain, you must create a configuration document, and then associate the SSM document with an already running instance.

To construct the SSM document, use a text editor of your choice, and save the file with the *.json extension. For more information about the structure of an SSM document, see SSM documents in the Amazon EC2 Systems Manager API Reference.

SSM documents run with administrative privilege on Windows instances because the EC2Config service runs in the Local System account. If a user has permission to execute any of the pre-defined SSM documents then that user also has administrator access to the instance. Delegate access to SSM Config and Run Command judiciously. This becomes extremely important if you create your own SSM documents. Amazon Web Services does not provide guidance about how to create secure SSM documents. You create SSM documents and delegate access to Run Command actions at your own risk. As a security best practice, we recommend that you create low-level SSM documents for low security tasks and delegate access to non-administrators.

Use the following AWS CLI or AWS Tools for Windows PowerShell commands to create the SSM document, launch an instance, and then associate the file with your instance.

Action AWS CLI AWS Tools for Windows PowerShell
To create an SSM document in your account. create-document New-SSMDocument
To launch an instance. You can also join an existing instance to a domain, provided it meets the prerequisites. For more information, see Prerequisites. run-instances New-EC2Instance
To associate the SSM document with your instance. create-association New-SSMAssociation

To join a domain using the AWS CLI or AWS Tools for Windows PowerShell

  1. Open a text editor on your computer, and write an SSM document. When you are done, save the file with a .json extension. The following is an example of an SSM document that allows instances to join domain d-1234567890:

    Copy
    { "schemaVersion": "1.0", "description": "Sample configuration to join an instance to a domain", "runtimeConfig": { "aws:domainJoin": { "properties": { "directoryId": "d-1234567890", "directoryName": "test.example.com", "dnsIpAddresses": [ "198.51.100.1", "198.51.100.2" ] } } } }

    Note

    If a valid organizational unit (OU) exists then you could also specify the following:

    Copy
    { "schemaVersion": "1.0", "description": "Sample configuration to join an instance to a domain", "runtimeConfig": { "aws:domainJoin": { "properties": { "directoryId": "d-1234567890", "directoryName": "test.example.com", "directoryOU": "\"OU=Computers,OU=example,DC=test,DC=example,DC=com\"", "dnsIpAddresses": [ "198.51.100.1", "198.51.100.2" ] } } } }
  2. Create the SSM document in your account, and give it a name. The name of the file must be between 1 and 64 characters in length.

    AWS CLI

    Copy
    aws ssm create-document --content file://path/to/myconfigfile.json --name "My_Custom_Config_File"

    Tools for Windows PowerShell

    First create a variable that contains the file contents, and then create the document.

    Copy
    $doc = Get-Content C:\temp\myconfigfile.json | Out-String New-SSMDocument -Content $doc -Name "My_Custom_Config_File"
  3. Launch an EC2 instance into the same VPC in which your domain (d-1234567890) is located. You must assign an IAM role to your instance. You must also ensure that your instance has a public IP address, unless you're using a NAT instance for Internet communication. Take note of the instance ID in the output.

    AWS CLI

    Copy
    aws ec2 run-instances --image-id ami-1a2b3c4d --subnet-id subnet-33cc44dd --key-name my-key-pair --instance-type m1.large --iam-instance-profile MyInstanceProfile --associate-public-ip-address { "OwnerId": "123456789101", "ReservationId": "r-bbaa1122", "Groups": [ { "GroupName": "default", "GroupId": "sg-5c5c5c5c" } ], "Instances": [ ... "InstanceId": "i-1234567890abcdef0", ... }

    Tools for Windows PowerShell

    Copy
    New-EC2Instance -ImageId ami-1a2b3c4d -SubnetId subnet-33cc44dd -KeyName my-key-pair -InstanceType m1.large -InstanceProfile_Id MyInstanceProfile -associatePublicIp $true
  4. Associate the SSM document with the running instance.

    AWS CLI

    Copy
    aws ssm create-association --instance-id i-1234567890abcdef0 --name "My_Custom_Config_File"

    Tools for Windows PowerShell

    Copy
    New-SSMAssociation -InstanceId i-1234567890abcdef0 -Name "My_Custom_Config_File"
  5. Check the status of the domain join. For more information, see Getting the Domain Join Status.

Joining a Domain Using the Amazon EC2 Launch Wizard

You can use the launch instance wizard in the Amazon EC2 console to join a new instance to a domain that you specify. If you don't already have one, the wizard creates an SSM document for you, and associates it with your new instance.

Note

You can't use the Amazon EC2 console to associate an SSM document with an existing instance.

To join a domain using the launch wizard

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. On the Amazon EC2 console, click Launch Instance.

  3. On the first page of the wizard, select a Windows AMI. On the next page, select an instance type, and then click Next: Configure Instance Details.

  4. On the Step 3: Configure Instance Details page, select a VPC from the Network list, and a subnet from the Subnet list. Ensure that you select the VPC in which your AWS Directory Service domain is located.

  5. In the Auto-assign Public IP list, select Enable (if the subnet setting is not set to enable by default).

    Note

    If you're launching your instance into a private subnet and using a NAT instance in a public subnet for Internet communication, you do not have to assign your instance a public IP address.

  6. Select your domain from the Domain join directory list, and select the IAM role to associate with the instance from the IAM role list.

  7. Complete the rest of the configuration steps as required, and then click Next until you reach the Step 6: Configure Security Group page. Ensure that you select or create a security group with a rule that allows RDP access from your IP address, or from a range of IP addresses within your network. For more information about security group rules, see Authorizing Inbound Traffic for Your Windows Instances.

  8. Click Review and Launch to launch your instance.

  9. Check the status of the domain join. For more information, see Getting the Domain Join Status.

Getting the Domain Join Status

You can check the status of your domain join by viewing the system log for the instance, or by checking the status of the association.

Note

After a configuration file is associated with an instance, it may take several minutes before the instance is joined to the domain.

You can check your instance's system log by using the Amazon EC2 console, AWS CLI, or Tools for Windows PowerShell.

To get the system log using the console

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, click Instances.

  3. Select your instance, right-click, select Instance Settings, and then click Get System Log.

To get the system log using a command line tool

  • Use the get-console-output (AWS CLI) command; for example:

    Copy
    aws ec2 get-console-output --instance-id i-1234567890abcdef0
  • Use the Get-EC2ConsoleOutput (AWS Tools for Windows PowerShell) command; for example:

    Copy
    Get-EC2ConsoleOutput -instanceId i-1234567890abcdef0

In the system log, the following output indicates that the domain join was successful:

Copy
2015/02/02 10:59:36Z: Info: EC2Config configuration status:2;region:us-east-1;iam:1;authz:1 2015/02/02 10:59:42Z: Info: EC2Config: Downloading config awsconfig_Domain_d-1234567890_corp.example.com 2015/02/02 10:59:45Z: Info: EC2Config: The instance is joining domain with id:d-1234567890, name:corp.example.com ... 2015/02/02 10:59:48Z: Info: EC2Config: The instance successfully joined the domain. 2015/02/02 10:59:48Z: Info: EC2Config: The instance will reboot shortly for domain join to take effect.

Alternatively, you can check the status of the association between the configuration document and the instance by using the AWS CLI or the Tools for Windows PowerShell.

To check the status of the association

  • Use the describe-association (AWS CLI) command; for example:

    Copy
    aws ssm describe-association --name "My_Custom_Config_File" --instance-id i-1234567890abcdef0
  • Use the Get-SSMAssociation (Tools for Windows PowerShell) command; for example:

    Copy
    Get-SSMAssociation -Name "My_Custom_Config_File" -instanceId i-1234567890abcdef0

Connecting To Your Instance Using Domain Credentials

After you've joined your instance to a domain, you can connect to your instance using domain credentials that you've defined in AWS Directory Service.

To connect to an instance as an administrator using your directory credentials

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, click Instances, select your instance, and then click Connect.

  3. In the dialog box, click Download Remote Desktop File, and open the file using an RDP client.

  4. On the login screen, instead of using the local computer name and password generated from your key pair file, enter the details as follows:

    • User name: enter the fully-qualified name of your domain, followed by a backslash (\), and then the user name, in this case, Admin; for example: corp.example.com\Admin.

    • Password: enter the password that you specified when you created your domain.

    For more information about connecting to an instance, see Connecting to Your Windows Instance.

After you've verified that you can connect to your instance as an administrator, users in your domain can connect to the instance using the same procedure, replacing the Admin credentials with their own user name and password.

Troubleshooting

If you are having trouble joining your instance to a domain, or if you are having trouble connecting to your instance using domain credentials, first verify the status of the domain join by checking instance's system log, or by checking the status of the association: Getting the Domain Join Status.

Cannot Connect to Instance

If the domain join was successful, but you are having trouble logging into to your instance, try the following:

  • If you can connect to your instance, but you cannot log in, check that you are using the correct user name and password. The user name must include the fully qualified name of your domain (for example, corp.example.com), and the password must be the password configured in the domain, not the password generated by a key pair file.

  • If you cannot connect to your instance, check your security group settings. You must have a rule that allows RDP access from your IP address or network.

The Domain Join was Unsuccessful

In the system log, the following output indicates the EC2Config service was unable to connect and download the associated SSM document, and therefore the domain join was unsuccessful:

Copy
Info: EC2Config configuration status:3;region:us-east-1;iam:0;authz:0

The output can help you troubleshoot the cause of the failure:

  • configuration status:3: The calls to SSM Config failed. Ensure that you have granted the required IAM permissions to IAM users. SSM Config also requires an Internet connection from your instance - your instance must have a public IP address, and must be launched into a public subnet. For more information about public subnets, see Your VPC With Subnets in the Amazon VPC User Guide.

  • iam:0: The instance does not have an associated IAM role. You cannot join your instance to a domain if there is no IAM role associated with the instance. To associate an IAM role, see Attaching an IAM Role to an Instance.

  • authz:0: The instance is not authorized to access SSM Config. This happens if you launched the instance without an IAM role, or if the role associated with your instance does not have the necessary permissions to access the service.

You can also troubleshoot specific reasons for a domain join failure by checking the status of the association using the describe-association (AWS CLI) command or the Get-SSMAssociation (Tools for Windows PowerShell) command. For example, the following output indicates that the IAM role associated with the instance does not have permission to use the ds:CreateComputer action:

Copy
Name : My_Config_Doc InstanceId : i-1234567890abcdef0 Date : 2/10/2015 1:31:45 AM Status.Name : Failed Status.Date : 2/10/2015 1:38:38 AM Status.Message : RunId=631148a7-894f-4684-8718-ee4cexample, status:Failed, code:0, message:RuntimeStatusCounts=[Failed=1], RuntimeStatus=[aws:domainJoin={Failed,User: arn:aws:sts::123456789101:assumed-role/NoDomainJoinPermission/i-1234567890abcdef0 is not authorized to perform: ds:CreateComputer}] Status.AdditionalInfo : {agent=EC2Config,ver=x.x.xx,osver=6.2.9200,os=Windows Server 2012 Standard,lang=en-US}

Viewing Information About Your Associations

You can use the AWS CLI or the AWS Tools for Windows PowerShell to view information about your associations and your SSM documents.

Action AWS CLI AWS Tools for Windows PowerShell
To view information about an association for a specific instance and SSM document. You can also use this command to view the status of an association. describe-association Get-SSMAssociation
To view information about a specified SSM document. You can also use this command to view the status of an SSM document, for example, creating. describe-document Get-SSMDocumentDescription
To view the contents of a specified SSM document. get-document Get-SSMDocument
To view a list of associations for a specified SSM document or a specified instance. list-associations Get-SSMAssociationList
To view a list of your SSM documents. list-documents Get-SSMDocumentList

Changing an Association

You can't update an SSM document after you create it. If you want to join your instance to a new domain, you must first delete the association, and then create a new association using a new SSM document. It can take up to 15 minutes for the configuration changes to take effect.

For more information about deleting an association, see Disassociate the SSM document from the Instance. For more information about associating a new document with an instance, see Associate the SSM document with the Instance.

Deleting an association does not change the configuration on the instance. Your instance is still joined to a domain until you manually remove it from the domain by modifying the network connection configuration information and system properties of the instance.

Deleting an SSM document

If you no longer require an SSM document, you can delete it. You must first disassociate the file from any instances it is associated with before you delete it. For more information about deleting an SSM document, see Delete the SSM document.