How do I use user data to add a new user account with RDP access to my Amazon EC2 instance?

Short description

To create a new local user with RDP permissions that can connect to your EC2 instance, use PowerShell commands that run as part of user data. If you plan to launch a new instance, then the user data automatically runs each time the instance restarts or reboots. If you use an instance that you already launched, then you must schedule the user data to run.

For more information, see User data execution.

Resolution

Important: Before you stop and start your instance, take the following actions:

• Create a backup of your Amazon Elastic Block Store (Amazon EBS) volume.
  Note: If your instance is instance store-backed or has instance store volumes that contain data, then Amazon EC2 deletes the data when you stop the instance.
• Temporarily remove the instance from its Amazon EC2 Auto Scaling group when you complete the resolution steps.
  Note: If you stop an instance that's in an Amazon EC2 Auto Scaling group, then you might terminate the instance based on your scale-in protection settings. Instances that you launch with Amazon EMR, AWS CloudFormation, or AWS Elastic Beanstalk might be in an Auto Scaling group.
• Set the instance shutdown behavior to Stop to make sure that the instances don't terminate when you stop them.

Note: When you stop and start an instance, the instance's public IP address changes. It's a best practice to use an Elastic IP address to route external traffic to your instance instead of a public IP address. If you use Amazon Route 53, then you might need to update the Route 53 DNS records when the public IP address changes.

Add the PowerShell script to your instance at launch

Complete the following steps:

1. Use the launch instance wizard to configure the instance launch, and then choose Advanced under Configure storage.

2. Under Advanced details, choose User data.

3. Enter the following PowerShell script:

   <powershell>$user = New-LocalUser -AccountNeverExpires:$true -Password ( ConvertTo-SecureString -AsPlainText -Force 'ExampleP@ssword!') -Name "RDPUser" -FullName "Local RDPUser" -Description "Local Administrator"
   Add-LocalGroupMember -Group "Administrators" -Member $user 
   Add-LocalGroupMember -Group "Remote Desktop Users" -Member $user 
   </powershell>

   Note: The preceding example script creates a new local user named RDPUser with the ExampleP@ssword! password. The AWS account is set to enabled, doesn't expire, and includes a brief description. The script adds the user account to both the Administrators group and the Remote Desktop Users group. Access to the Remote Desktop Users group is required, but you can remove the Add-LocalGroupMember -Group "Administrators" -Member $user section if needed.

4. Choose Launch instance.

Add the PowerShell script to your instance after launch

If your EC2 instance is already launched, then complete the following steps:

1. Configure your settings so that Amazon EC2 reflects updated user data at the next start.

2. Stop your EC2 instance.

3. Open the Amazon EC2 console.

4. Choose Instances, and then select your instance.

5. Choose Actions, and then select Instance settings.

6. Choose View/Change User data.

7. For User data, enter the following PowerShell script:

   <powershell>$user = New-LocalUser -AccountNeverExpires:$true -Password ( ConvertTo-SecureString -AsPlainText -Force 'ExampleP@ssword!') -Name "RDPUser" -FullName "Local RDPUser" -Description "Local Administrator"
   Add-LocalGroupMember -Group "Administrators" -Member $user 
   Add-LocalGroupMember -Group "Remote Desktop Users" -Member $user 
   </powershell>

   Note: The preceding example script creates a new local user account named RDPUser with the ExampleP@ssword! password. The account is set to enabled, doesn't expire, and includes a brief description. The script adds the user account to both the Administrators group and the Remote Desktop Users group. Access to the Remote Desktop Users group is required, but you can remove the Add-LocalGroupMember -Group "Administrators" -Member $user section if needed.

8. Start your instance.

Verify that Amazon EC2 created the user account

To confirm that Amazon EC2 created the user account, you can use Session Manager, a capability of AWS Systems Manager, or PSSession remote access.

To create the $usernamelist variable, run the following command:

$usernamelist = Get-WmiObject -Class Win32_UserAccount -Filter "LocalAccount='True'" |Select Name, Status, Disabled, AccountType, Lockout, PasswordRequired, PasswordChangeable, SID

Note: The $usernamelist variable contains a list of all user accounts that match the Local Account is true requirement.

To get a detailed view of the user account that you created, run the following command:

$usernamelist | select-string -AllMatches RDPUser

Note: Replace RDPUser with your user account name.

Troubleshoot issues

If you experience issues when you add a new user account, then take the following actions:

• If Amazon EC2 didn't create the user account, then run the route print or invoke-webrequest commands to check the instance metadata and access to user data. If you receive a response that isn't a 200 response, then check the instance user data.
• To view user data logs, see How can I troubleshoot issues when I run user data scripts to configure my EC2 Windows instance?
• Test the script on a local computer before you run it.
• Confirm that the instance uses the correct version of PowerShell and that the script can run on a second instance.