Microsoft Workloads on AWS

Automated user creation and provisioning in Active Directory and Amazon WorkSpaces

For customers that have workloads in the AWS Cloud, a common use case is the provisioning of new user accounts in Active Directory, and subsequently, WorkSpaces for these new users. In this blog post, we will present an efficient and reusable solution to automate the creation, provisioning, and deprovisioning of Microsoft Active Directory (AD) user accounts and their corresponding Amazon WorkSpaces. This solution streamlines the onboarding process for new employees, ensuring that new users have access to the right resources from day one and enabling the organization to save valuable time and resources.

By efficiently managing your user provisioning workflow, you can ensure a strong security posture and provide a seamless experience for your users.


Automated user provisioning is the process of granting access to applications, systems, and data through a repeatable predefined process without requiring human intervention. It involves the setting up of workflows that automatically create, configure, and manage user accounts. This aids application and system administrators with their day-to-day activities by automating a variety of simple AD-related tasks, such as bulk user creation, management and disabling of user accounts, and creating Organizational Units (OUs) for WorkSpaces and disabled accounts.

Solution overview

For automated user and WorkSpaces provisioning, you will use an  AWS Systems Manager task to manage AD users in a specified OU. A periodic scheduled maintenance window task evaluates the contents of a user uploaded CSV file (containing user details stored in an Amazon Simple Storage Service (Amazon S3) bucket) to provision and deprovision AD users. Active users are created in the OU (specified as a parameter in the AWS CloudFormation script). Deprovisioned user accounts are set to a disabled status and moved to the InactiveWSUsers OU that is automatically created by this solution. AD user passwords are generated by and stored in AWS Secrets Manager. This same task evaluates the specified AD OU and writes the list of current active users to a file in an Amazon S3 bucket, triggering an AWS Lambda function, ws-automation-lambda-compare, that is automatically deployed by this solution. This Lambda function compares the currently deployed WorkSpaces with the list of active users and creates or terminates WorkSpaces as needed.

There are two optional steps in the AWS CloudFormation template. The first one is to register your directory with WorkSpaces. This is only necessary if the directory has not been registered previously. The second optional step is to create the WorkSpaces default role. This is only necessary if no WorkSpaces have been previously launched in the AWS account.

The automation shown in Figure 1 has been built as an AWS CloudFormation template. Download the YAML file from github to your local machine to view and deploy the solution.

Automated User Provisioning in Active Directory and AWS Workspaces

Figure 1: Active Directory users and Amazon WorkSpaces Automation

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

  1. An AD registration Lambda function, ws-automation-lambda-register, and the required roles and policies that are used to register the directory for use with WorkSpaces. See the document Register a directory with WorkSpaces for more information. It requires two subnet IDs as input parameters, each belonging to a different Availability Zone that supports WorkSpaces. The directory registration is a required step to allow WorkSpaces to use an existing AWS Directory Service directory to provision WorkSpaces. This is an optional step for the AWS CloudFormation stack if it has already been configured.
  2. An Amazon S3 bucket. This bucket will be automatically configured with a file userlifecycle/UserListTemplate.csv that contains the template structure for the user details required by the automated process to add or disable users. This template should be used by the admin to create the file userlifecycle/csv. This file should contain the actual list of user IDs that will be picked up by the solution for AD user and WorkSpaces creation. The same Amazon S3 bucket will be used by the automated process to store the CSV file containing an updated list of AD users extracted from the WorkSpaces OU specified in the AWS CloudFormation stack parameters. A trigger on the Amazon S3 bucket is also created that will trigger a Lambda function to create WorkSpaces for active users.
  3. An AWS Systems Manager maintenance window, ws-automation-maintenance-window, with an associated task, IAM role, and policy that runs every 5 minutes. The task runs a PowerShell script that reads the file userlifecycle/UserList.csv from the Amazon S3 bucket containing the list of AD users to be added or disabled. It performs the following tasks in AD:
    1. If the AccountStatus=’A’, add the user to AD with the details provided in the file for the user.
      1. The user credentials are stored in AWS Secrets Manager. The Secret-id for the credentials is set as ws.users.’username’ format. The passwords are generated using the AWS Secrets Manager Get-SECRandomPassword API operation and can be custom configured for complexity based on the AD password requirements.
      2. A WorkSpaces OU is created in AD, if it does not exist. The AD users are added to this OU. The PowerShell script can be customized to specify a different OU.
    2. If the AccountStatus=’D’, move the user to the InactiveWSUsers This OU is created in AD, if it does not exist.
  4. An AWS Lambda function, ws-automation-lambda-compare. This function is triggered by the autogenerated CSV file uploaded by the process to the same Amazon S3 bucket with the list of active AD users. The function iterates through the user list in the file comparing it with current WorkSpaces user IDs and performs the following tasks:
    1. If a user exists in the file but does not have a WorkSpace, an AWS WorkSpace is provisioned in the WorkSpaces OU.
    2. If a user does not exist in the file, the user’s WorkSpace is terminated.
  5. The instance profile, InstanceProfileADManagement, which is assigned to the Amazon EC2  AD member server allowing it to perform the add or disable users administration actions on AD.
  6. This template also creates all the necessary AWS IAM roles and policies. All policies and roles have been created following the AWS recommended security best practice of least privilege. For more information, see Security best practices in IAM.


This automation requires the following setup or configuration:

  1. An AWS account.
  2. An AWS Directory Service for Microsoft Active Directory or an Amazon AD Connector if not using AWS Managed AD.
  3. An AD member server – an Amazon EC2 instance (2016 or later) in the Amazon Virtual Private Cloud (Amazon VPC) that has been domain-joined to AD. Your AD might be running on premises or on AWS Directory Service. This instance must be managed by AWS Systems Manager. The instance must have access to the internet since the script will install AD and AWS PowerShell tools used during script execution.
  4. An AD administration account username and password stored in AWS Secrets Manager. This account must have permissions to create or disable AD users in the specified OU. The ARN (Amazon Resource Name) of this secret value is needed as a parameter for the AWS CloudFormation script so it can run AD Admin commands. One secret with two key/value pairs need to be created in AWS Secrets Manager in the following format:
    • Key = username, value = <service account samAccountname>
    • Key = password, value = <service account password in AD>
  5. Two subnets, each in a different WorkSpaces supported Availability Zone, where AD will be registered and where the WorkSpaces will be deployed.
  6. WorkSpaces image and bundle configured with the expected image characteristics and applications that will be used to provision the user’s WorkSpace.

Deployment process

  1. Sign in to your AWS account and choose the Region for your Amazon WorkSpaces environment.
  2. Click the following link to view the AWS CloudFormation template and download it to launch the solution through the AWS CloudFormation console.

Active Directory User and Amazon Workspaces Automation Code


  1. Save the contents of the file ADWorkspaceAutomation.yml locally and deploy it through the AWS Command Line Interface (AWS CLI) or through the AWS CloudFormation console .

The script can be launched from the aws cli using the following command:

aws cloudformation deploy –-template-file ADWorkspaceAutomation.yml –-stack-name ADWorkspaceAutomation_local.yml

If you deploy through the AWS CloudFormation console, select Create Stack, Upload a template file, choose File, and then choose Next.

  1. Review the parameters for the template and update them accordingly. Once the parameters are entered, choose Create to deploy the stack. This solution uses the following parameters:
Parameter Description
1 DirectoryID The ID of the AWS Directory Service object (ie: AD Connector or Amazon Managed Active Directory).
2 DomainOUPath The OU path (e.g. OU=corp, DC=corp,DC=example,DC=com) of the users assigned where WorkSpaces will be created.
3 wsADSecret The ARN of the Secrets Manager entry for the AD service account.
4 Subnet1, Subnet2 Subnet IDs 1 and 2 – each in a different Availability Zone.
5 ADInstanceID The Amazon EC2 instance ID of the AD member server.
6 Drive The letter of the drive on the AD member server where files are temporarily stored from and to Amazon S3 (for example, C).
7 WorkspaceDefaultRoleChoice True or False flag to create the role: WorkSpacesDefaultRole for the WorkSpace users. Note that WorkSpaces will require a role, so a custom role will need to be created if this is set to False.
8 DirectoryRegistrationChoice True or False flag to indicate if the directory should be registered within the two subnets provided above. Note that this should be set to False only if AD has been registered previously.
9 BundleID The ID of the Amazon WorkSpaces Bundle ID that will be used to provision the WorkSpace for the user.
10 UsersBucketName The name of the Amazon S3 bucket to store the user files. Must be a unique name.

Once the AWS CloudFormation stack has successfully deployed, perform the following steps:

  1. From the AWS console, navigate to the Amazon S3 console and choose the output Amazon S3 bucket created by AWS CloudFormation for the automated user process.
  2. Select the folder userlifecycle. Check the box next to the file csv and select Download.
  3. Update the file with the necessary AD user details and save the file locally as csv.
  4. In the Amazon S3 console page, select Upload to upload the newly updated csv file to the userlifecycle folder in the Amazon S3 bucket. The file will be processed during the next run of the maintenance task to add the users to AD and create WorkSpaces.
  5. From the Amazon EC2 console, verify that the AD domain joined Amazon EC2 instance is attached to the instance profile InstanceProfileADManagement. You should be able to connect to the instance with RDP using the AD administration account username and password that was specified in AWS Secrets Manager for the solution to run successfully.
  6. For additional security, review the IAM roles created by this deployment to further restrict access to resources being used by the process.

The file UserListTemplate.csv contains the following columns and should be used as the starter template for adding AD user details. Save the file as UserList.csv and upload it back to the Amazon S3 bucket for the automated process to use.

Example record:

AccountStatus UserName FirstName LastName Email Company
A user1 John Doe Example


To clean up resources deployed as part of this solution, perform the following steps:

Navigate to CloudFormation within the AWS Management Console and delete the CloudFormation stack deployed.

The following steps should be run manually to remove resources since these are used by processes and will not be deleted automatically:

  1. Delete the Lambda function CreateDirectoryRegistration.
  2. Delete the roles RegistrationExecutionRole, ws-automation-lambda-compare-role and ad-management-role created in IAM by AWS CloudFormation. These are not deleted automatically because there are attached resources.
  3. Empty and delete the Amazon S3 bucket used for uploading user CSV files.
  4. Delete the credentials stored in AWS Secrets Manager for any AD users that were added to AD via the CSV file. The Secret-id for the credentials is set as users.’usernameformat. 


This solution provides an efficient, reusable, and scalable process to automate user provisioning in the AWS Cloud and helps reduce operational overhead by eliminating the manual steps involved in adding users to AD and creating WorkSpaces. It streamlines the onboarding process for new employees, ensuring that new users have access to the right resources from day one. This solution also simplifies the deprovisioning process, ensuring that access is revoked promptly and securely, and it reduces cost by promptly terminating WorkSpaces access for disabled users.

AWS has significantly more services, and more features within those services, than any other cloud provider, making it faster, easier, and more cost effective to move your existing applications to the cloud and build nearly anything you can imagine. Give your Microsoft applications the infrastructure they need to drive the business outcomes you want. Visit our .NET on AWS and AWS Database blogs for additional guidance and options for your Microsoft workloads. Contact us to start your migration and modernization journey today.

Prasanthi Jonnavittula

Prasanthi Jonnavittula

Prasanthi is a Cloud Application Architect at Amazon Web Services based in Plano Texas, focused on providing cloud solutions for AWS customers. With over 25 years of experience as a full stack Java developer, Prasanthi has worked extensively in the Finance and Telecom industries. In her spare time she enjoys going on long hikes with her family, learning Carnatic music, cooking & gardening.

JP Santana

JP Santana

João Paulo (JP) Santana is a Principal Solutions Architect at AWS. He spent most of his life in São Paulo, Brazil and now lives in Orlando, FL where he works with our customers in the Southeast region of the US. In his spare time, he enjoys spending time with his wife and three kids, grilling a good Brazilian steak, or practicing Brazilian Jiu Jitsu.

John Galley

John Galley

John Galley is a Cloud Architect with AWS Professional Services. He works with partners and customers designing and architecting enterprise solutions on AWS.