Desktop and Application Streaming

Manage Amazon WorkSpaces lifecycle automatically with users in Active Directory

Customers use Amazon WorkSpaces to launch highly performant, scalable, and cost effective managed virtual desktops in the cloud. Amazon WorkSpaces reduces the operational overhead of having to manage traditional VDI infrastructure and complex licensing agreements.

You can further reduce this operational overhead using automation. There are Amazon WorkSpaces API operations that you can use to interact with the service securely, and at scale.

In this blog post, I share a solution to provision WorkSpaces automatically when users are created in Active Directory (AD), in an Organizational Unit (OU) you specify. It also terminates WorkSpaces when users are removed in AD, or moved to a different OU.

This helps you automate WorkSpaces provisioning and termination to keep AD users and their respective WorkSpaces always in sync.

Solution overview

The solution is easily deployed in your AWS account with an AWS CloudFormation template. The template provisions an Amazon S3 bucket, a Systems Manager Maintenance Window, and a Lambda function, and integrates them into your current WorkSpaces environment, as shown in the following diagram:

Amazon WorkSpaces automation solution architecture.

Figure 1: Amazon WorkSpaces automation solution architecture

The AWS CloudFormation template automatically deploys the following components in your AWS account:

  • An Amazon S3 bucket. The bucket stores the CSV file containing an updated list of the users, extracted from the OU you specify in the AWS CloudFormation parameters.
  • An AWS Systems Manager – Maintenance Window, with an associated Task that runs every 5 minutes. The Task has a PowerShell script that extracts the user names in the OU to a CSV file. The file is uploaded to a S3 bucket.
  • An AWS Lambda function. The function is triggered once a new CSV file is uploaded in Amazon S3. The function code loads the file and iterates the user list. It then compares users with current WorkSpaces owners.
    • If a user exists in the file, but does not have a WorkSpace, a WorkSpaces is provisioned.
    • If a user does not exist in the file, the user’s WorkSpace is terminated.
  • The template also creates all the necessary IAM Roles and Policies require. The template follows least privilege access principles.

Solution cost

AWS Systems Manager Maintenance Windows come with no additional cost.  The CSV stored in Amazon S3, should be small. AWS Lambda, is also cost-effective in this scenario. For example, a csv file containing 1000 users is around 7KB in size and Amazon S3 standard costs $0.023 per GB/Month.


Make sure that your environment meets the following requirements before deploying the solution:

  • A domain controller or member server, running on Amazon EC2, joined to your Active Directory domain. Your Active Directory might be running on-premises, or on AWS Directory Services. This instance or server must be managed by AWS Systems Manager.
  • Two subnets that support WorkSpaces are created with sufficient IP addresses to hold the number of WorkSpaces you intend to provision.
  • An AD Connector or AWS Managed Microsoft AD registered for Amazon WorkSpaces that reference the assigned subnets for WorkSpaces.
  • Your AWS account must have service limits set to the bundle type and number of WorkSpaces you plan to create. Open a support ticket to check if you must set these limits accordingly.
  • A WorkSpaces image and bundle configured with the expected image characteristics and applications.
  • An Active Directory Organizational Unit (OU) created to maintain your Amazon WorkSpaces users.

If you brought your own images to Amazon WorkSpaces, contact AWS Support and your AWS account team to make sure you have enough dedicated capacity in the Region.

Deployment Process

1. Sign in to your AWS account and choose the Region you use for your Amazon WorkSpaces environment.
2. Click the button below to view the AWS CloudFormation template and launch the solution through the AWS CloudFormation console.

3. Save the contents of the file ws-automation.yml locally and deploy it through the AWS CloudFormation console by selecting Create Stack, Upload a template file, choose File and then, choose Next.
4. Review the Parameters for the template and enter them accordingly. This solution uses the following parameters:

Parameter Description
AdInstanceID The EC2 Instance ID of the domain controller.
BundleID The ID of the Amazon WorkSpaces Bundle.
DirectoryID The ID of the AWS Directory Services object (that is: AD Connector or AWS Managed Microsoft AD).
UsersBucketName The name of S3 bucket to used store the user files . Must be a unique name.
UsersOU The OU path. (that is: OU=users,OU=workspaces,DC=domain,DC=com) of the users assigned WorkSpaces.
DriveLetter The letter of the drive where you want workspaces-users.csv file to be exported in the Domain Controller or Member Server. (for example: D)

Once the parameters are entered, choose Next.

5. On the Options page, choose Next.
6. On the Review page, review and confirm the settings. Be sure to select the box acknowledging that the template creates AWS Identity and Access Management (IAM) resources.
7. Choose Create to deploy the stack.

Once the solution is deployed, after 5 minutes, a CSV file with users should be available in the defined S3 bucket.

CSV file containing the user list from the Active Directory Organizational Unit.

At this point, the deployed code keeps track of the users in the specified OU. It will automatically provision or terminate WorkSpaces instances accordingly.

Once your WorkSpaces environment is deployed, I recommend you consider deploying WorkSpaces Cost Optimizer solution. This solution is designed to automatically convert WorkSpaces to the most cost effective running mode depending on a user’s WorkSpace usage.


This solution helps reduce operational overhead by using routines designed to provision and terminate Amazon WorkSpaces automatically. It also helps maintain costs by running WorkSpaces only for designated users.

About the Author


João Paulo (JP) Santana is a Startup Solutions Architect for AWS. He spent most of his life in São Paulo, Brazil and now lives in Atlanta, GA. In his spare time, he enjoys spending time with his family and practicing Brazilian Jiu Jitsu.