Synchronize Active Directory users to AWS IAM Identity Center using SCIM and PowerShell

In this blog post, I will show you how to use PowerShell to synchronize changes to Microsoft Active Directory (AD) users and groups for federated access to Amazon Web Services (AWS).

Introduction

Some customers have a well-established Active Directory Federation Service (ADFS) implementation and would like to leverage it for federated access to AWS via integration with the AWS IAM Identity Center (IAM IDC), which was previously known as AWS Single Sign-On. The challenge is that ADFS does not support System for Cross-domain Identity Management (SCIM). SCIM is an open standard designed to support create, read, update, and delete (CRUD) operations when synchronizing users and groups.

In this blog post, you will use PowerShell to synchronize users and groups through a RESTful API for SCIM exposed by the IAM IDC. At the end of this blog post:

• You will have an AWS Fargate task that will run every 12 hours to sync users and groups from your on-premises AD to your IAM IDC SCIM endpoint.
• The task will create new users and groups within IAM IDC that align with your AD configuration choices.
• It will also update IAM IDC user and group entities to match specified AD user objects and specified AD groups.

Prerequisites

• You have already enabled and configured AWS IAM Identity Center with ADFS as the External Identity Provider.
• You have enabled automatic provisioning and noted the SCIM API endpoint and SCIM token.
• You have created an AD user account with read-only permissions to the AD objects that will be synced.
• You have configured an Outbound Resolver in Amazon Route 53 to support resolution of on-premises domain controllers from the AWS environment.
• You have an Amazon Virtual Private Cloud (VPC) with a private subnet with a NAT gateway and connectivity to the on-premises AD environment.
• You have Docker Desktop installed on a machine to build the container image that will run the PowerShell script.
• You have installed AWS CLI v2 on the machine where the container image is built and have a configured the CLI to access the AWS account where the solution will be hosted.

Solution overview

You will implement a serverless approach to synchronizing AD users and groups to the IAM IDC service via SCIM. You will set up an AWS Fargate cluster that will run a small container image for the PowerShell script. This script will retrieve sensitive AD and SCIM credentials from AWS Secrets Manager while retrieving general configuration information from the AWS Systems Manager Parameter Store.

Once that information is retrieved, the PowerShell script will perform a lookup against the on-premises AD environment, compare the information with what is in the IAM IDC, and create or update the users and groups to match the on-premises user and group memberships. Figure 1 is an architecture diagram of this solution:

Figure 1: Architectural Diagram of PowerShell / SCIM Sync Process

Securely store credentials and configurations

Following best practices, the script does not store any credentials in the code and it retrieves key variables from a secure parameter store. To access the credentials and parameter store, an AWS IAM role, which will be used by the AWS Fargate task, is granted privileges to read the values.

AWS Secrets Manager

AWS Secrets Manager will store the credentials needed to read the AD objects and the credential used to access the SCIM API.

There are two secrets that will need to be stored in AWS Secrets Manager. One will be the SCIM API token and the other is the read-only user credentials for AD. Table 1 provides details on the secrets created by the AWS CloudFormation template:

Table 1. Stored secrets

AWS Systems Manager

AWS Systems Manager will store four parameters with less sensitive information than the secrets and will control things such as which group defines the set of users to be synced and what AD organizational unit (OU) to search for groups. Table 2 provides details on the parameters created by the AWS CloudFormation template:

Table 2. Stored parameters

AWS IAM to access the secrets and parameters

The PowerShell script will run on a Windows container on AWS Fargate. An IAM role will be created by the AWS CloudFormation template and will be used by the Amazon ECS task running on an AWS Fargate cluster. The IAM role is named IAM-IDC-SCIM-Sync-Role.

Overview of the PowerShell script

• When creating an Identity Center user based on an AD user object, the script captures the SID and applies it to the IAM IDC user object’s externalId This serves as a positive link between the AD User and IAM IDC user so that the script will only operate on IAM IDC users created by the script.
  • Once the user object is created in IAM IDC, the script will then create and/or update any groups and group memberships. The groups to synchronize are determined by the group name prefix stored as the /IAM-IDC/AD-Group-Prefix value in AWS Systems Manager Parameter Store. You should standardize on a group prefix, such as “aws-”. For example, you may have group names like aws-CloudOperations or aws-SecurityOperations.
• What the script does:
  • It creates or updates users in IAM IDC based on membership in the AD group name specified in the AWS Systems Manager Parameter Store value /IAM-IDC/AD-Group-Name and an AD query of the user’s group memberships that match the /IAM-IDC/AD-Group-Prefix and /IAM-IDC/AD-Search-Base
  • Disables users in IAM IDC if they are disabled in AD.
  • It looks for groups in the OU specified by the /IAM-IDC/AD-Search-Base value in AWS Systems Manager Parameter Store and if the AD group has a name prefix that matches the value retrieved from the /IAM-IDC/AD-Group-Prefix (e.g. “aws-”), it then creates the group in IAM IDC if it does not already exist.
  • It adds users to the IAM IDC groups based on the list of group members retrieved from AD and deletes them from the IAM IDC groups if their AD group membership does not list the group.
• What the script does not do:
  • Delete any users in the IAM IDC.
  • Delete any groups created in the IAM IDC.
  • Does not perform any writes to any AD objects.

Walkthrough

The following steps provide a walkthrough of how to implement the solution:

1. Clone the GitHub repository to the machine where you have Docker Desktop installed. This repository contains the PowerShell script, AWS CloudFormation templates, and the Dockerfile used by this solution.
2. Open the AWS Console, navigate to the AWS CloudFormation service, choose to upload a template file, select the json file, and click Next, as shown in Figure 2:

Figure 2: Upload CloudFormation template SecretsManagerAndSSM.json

3. Provide the stack name SecretsManagerAndSSM-SCIMSync and fill in the other values to match your environment, as shown in Figure 3, and then click Next twice, leaving the rest of the settings at their defaults.

Figure 3: Providing the parameter values for the AWS CloudFormation template

4. Once on the CloudFormation review screen (shown in Figure 4), check the box to acknowledge that some IAM resources may be created (a role to retrieve the secrets and parameters) and click the Submit

Figure 4: Review CloudFormation stack details for Secrets Manager and SSM Parameter Store

5. Once the CloudFormation has completed successfully, you will need to build the container image that will run the PowerShell script. Go to the Amazon ECR service in the AWS Console, check the box next to the scimsync repository which was created by the CloudFormation template, and click the View push commands, as shown in Figure 5:

Figure 5: Obtaining the push commands for a container image in Amazon ECR

Open a PowerShell window, switch to the directory where you cloned the GitHub repo, and follow the push command instructions to build and publish the container image to Amazon ECR.

Note that in step 2 of the push instructions, you are building the container image. If this process fails, it could be because the container has no internet access. If that occurs, run the command docker network ls to find the proper network name and then add –network “Network Name” to the end of the command (e.g. docket build -t scimsync . –network “Default Switch”). For the AWS commands to run successfully, you need to be authenticated to the AWS account where the CloudFormation is deployed.

6. After the container image has been published, refresh the Elastic Container Registry Console to see an image published in the repository with an image tag of “latest,” as shown in Figure 5.
7. Now that the image is available in Amazon ECR, go to the AWS CloudFormation service and create a new stack with the json template file.
8. When prompted for the stack name, enter ECSFargate-SCIMSync. Then select the VPC that has access to your on-premises domain controllers and select the two private subnets that are part of the selected VPC. Click Next through the remaining screens, leaving the default values, and check the box to acknowledge that some IAM resources may be created (a role for Amazon ECS Task execution) and click the Submit button, as shown in Figure 6:

Figure 6: Review and submit the CloudFormation for ECS cluster and task creation

9. Upon completion, the CloudFormation stack will create an Amazon ECS Fargate cluster, define an ECS task, and create a task schedule that will run the container image to sync AD with IAM IDC every 12 hours. The task schedule can be adjusted as needed either by editing line 147 in the json CloudFormation template or by editing the scheduled task after it is created, as shown in Figure 7:

Figure 7: ECS scheduled task configured to run every 12 hours

Figures 8 and 9 show examples of users and groups that were created in IAM IDC by the solution.

Figure 8: Users created by SCIM sync process

Figure 9: Groups created by SCIM sync process

Cleanup

To avoid ongoing charges for resources, delete the resources created as a part of this setup:

1. Navigate to the AWS CloudFormation console and delete the ECS Fargate stack called ECSFargate-SCIMSync.
2. Navigate to the Amazon ECR console and delete the container image within the scimsync repository.
3. Navigate to the AWS CloudFormation console and delete the Secrets Manager and SSM stack called SecretsManagerAndSSM-SCIMSync.

Conclusion

AWS IAM Identity Center enables the central management of access to AWS and supports federation with many external identity providers. When automatic user provisioning is enabled through SCIM support, the users and groups are created and kept in sync with an external identity provider if that provider supports SCIM. While ADFS does not support SCIM, it is possible to still have your users and groups automatically synchronize with the IAM IDC by using the SCIM API and PowerShell. Even though this solution focused on a scenario with ADFS and AD, this script could be changed to support other directory services that are LDAP-compatible.

This solution keeps cost and support low by implementing a serverless architecture using Amazon ECS Fargate, AWS Secrets Manager, and AWS Systems Manager Parameter Store, while also allowing DevOps teams to leverage Windows Server tools and services they are already familiar with by implementing Windows containers.

AWS can help you assess how your company can get the most out of cloud. Join the millions of AWS customers that trust us to migrate and modernize their most important applications in the cloud. To learn more on modernizing Windows Server or SQL Server, visit Windows on AWS. Contact us to start your migration journey today.