How to bulk import users and groups from CSV into AWS IAM Identity Center

September 12, 2022: This blog post has been updated to reflect the new name of AWS Single Sign-On (SSO) – AWS IAM Identity Center. Read more about the name change here.

When you connect an external identity provider (IdP) to AWS IAM Identity Center using Security Assertion Markup Language (SAML) 2.0 standard, you must create all users and groups into AWS IAM Identity Center before you can make any assignments to AWS accounts or applications. If your IdP supports user and group provisioning by way of the System for Cross-Domain Identity Management (SCIM), we strongly recommend using SCIM to simplify ongoing lifecycle management for your users and groups in AWS IAM Identity Center.

If your IdP doesn’t yet support automatic provisioning, you will need to create your users and groups manually in AWS IAM Identity Center. Although manual creation of users and groups is the least complicated option to get started, it can be tedious and prone to errors.

In this post, we show you how to use a comma-separated values (CSV) file to bulk create users and groups in AWS IAM Identity Center.

How it works

AWS IAM Identity Center supports automatic provisioning of user and group information from an external IdP into AWS IAM Identity Center using the SCIM protocol. For this solution, you use a PowerShell script to simulate a SCIM server, to provision users and groups from a CSV file into AWS IAM Identity Center. You create and populate the CSV file with your user and group information that is then used by the PowerShell script. Next, on your Windows, Linux, or macOS system with PowerShell Core installed, you run the PowerShell script. The PowerShell script reads users and groups from the CSV file and then programmatically creates the users and groups in AWS IAM Identity Center using your SCIM configuration for AWS IAM Identity Center.

Assumptions

In this blog post, we assume the following:

You already have an AWS IAM Identity Center-enabled account (free). For more information, see Enable AWS IAM Identity Center.
You have the permissions needed to add users and groups in AWS IAM Identity Center.
You configured a SAML IdP with AWS IAM Identity Center, as described in How to Configure SAML 2.0 for AWS IAM Identity Center.
You’re using a Windows, MacOS, or Linux system with PowerShell Core installed.
If you’re not using a system with PowerShell Core installed, you’re using a Windows 7 or later system, with PowerShell 4.0 or later installed.

Note: This article was authored and the code tested on a Microsoft Windows Server 2019 system with PowerShell installed.

Enable automatic provisioning

In this step, you enable automatic provisioning in AWS IAM Identity Center. You use the automatic provisioning endpoints for AWS IAM Identity Center to connect and create users and groups in AWS IAM Identity Center.

To enable automatic provisioning in AWS IAM Identity Center

1. On the AWS IAM Identity Center Console, go to the IAM Identity Center page and then go to Settings.
2. Change the provisioning from Manual to SCIM by selecting Enable automatic provisioning.

Figure 1: Enable automatic provisioning

1. Copy the SCIM endpoint and the Access token (you can have up to two access token IDs). You use these values later.

Figure 2: Copy the SCIM endpoint and access token

Bulk create users and groups into AWS IAM Identity Center

In this section, you create your users and groups from a CSV file into AWS IAM Identity Center. To do this, you create a CSV file with your users’ profile information (for example: first name, last name, display name, and other values.). You also create a PowerShell script to connect to AWS IAM Identity Center and create the users and groups from the CSV file in AWS IAM Identity Center.

To bulk create your users from a CSV file

1. Create a file called csv-example-users.csv with the following column headings: firstName, lastName, userName, displayName, emailAddress, and memberOf.

Note: The memberOf column will include all the groups you want to add the user to in AWS IAM Identity Center. If the group you plan to add a user to isn’t in AWS IAM Identity Center, the script automatically creates the group for you. If you want to add a user to multiple groups, you can add the group names separated by semicolons in the memberOf column.

1. Populate the CSV file csv-example-users.csv with the users you want to create in AWS IAM Identity Center.

Note: Before you populate the CSV file, take note of the existing users, groups, and group membership in AWS IAM Identity Center. Make sure that none of the users or groups in the CSV file already exists in AWS IAM Identity Center.

Note: For this to work, every user in the csv-example-users.csv must have a firstName, lastName, userName, displayName, and emailAddress value specified. If any of these values are missing, that user isn’t created. The userName and emailAddress values must not contain any spaces.

Figure 3: Create the CSV file and populate it with the users to create in AWS IAM Identity Center

Next, create a create_users.ps1 file and copy the following PowerShell code to it. Use a text editor like Notepad or TextEdit to edit the create_users.ps1 file.

Replace <SCIMENDPOINT> with the SCIM endpoint value you copied earlier.
Replace <BEARERTOKEN> with the Access token value you copied earlier.
Replace <CSVLOCATION> with the location of your CSV file (for example, C:\Users\testuser\Downloads\csv-example-users.csv. Relative paths are also accepted).

#Input SCIM configuration and CSV file location
$Url = "<SCIMENDPOINT>"
$Bearertoken = "<BEARERTOKEN>"
$CSVfile = "<CSVLOCATION>"
$Headers = @{ Authorization = "Bearer $Bearertoken" }

#Get users from CSV file and store in variable
$Users = Import-Csv -Delimiter "," -Path "$CSVfile"

 #Read groups in CSV and groups in AWS IAM Identity Center
    
    $Groups = $Users.memberOf -split ";"
    $Groups = $Groups | Sort-Object -Unique | where {$_ -ne ""}

    foreach($Group in $Groups){
         $SSOgroup = @{
            "displayName" = $Group.trim()
            }

    #Store group attribute in json format

    $Groupjson = $SSOgroup | ConvertTo-Json

    #Create groups in AWS IAM Identity Center

    try {
    
        $Response = Invoke-RestMethod -ContentType application/json -Uri "$Url/Groups" -Method POST -Headers $Headers -Body $Groupjson -UseBasicParsing
        Write-Host "Create group: The group $($Group) has been created successfully." -foregroundcolor green

    }
    catch 
    {
    
      $ErrorMessage = $_.Exception.Message

       if ($ErrorMessage -eq "The remote server returned an error: (409) Conflict.")
       {
         Write-Host "Error creating group: A group with the name $($Group) already exists." -foregroundcolor yellow
       }
       
       else 
       {       
         Write-Host "Error has occurred: $($ErrorMessage)" -foregroundcolor Red
       }
    }
    }

#Loop through each user
foreach ($User in $Users)
{

    #Get user attributes from each field
    $SSOuser = @{
            name = @{ familyName = $User.lastName.trim(); givenName = $User.firstName.trim() }
            displayName = $User.displayName.trim()
            userName = $User.userName
            emails = @(@{ value = $User.emailAddress; type = "work"; primary = "true" })
            active = "true"
            }

    #Store user attributes in json format
    $Userjson = $SSOuser | ConvertTo-Json

    #Create users in AWS IAM Identity Center

    try {
    $Response = Invoke-RestMethod -ContentType application/json -Uri "$Url/Users" -Method POST -Headers $Headers -Body $Userjson -UseBasicParsing
    Write-Host "Create user: The user $($User.userName) has been created successfully." -foregroundcolor green

    }
    catch 
    {
    
      $ErrorMessage = $_.Exception.Message

       if ($ErrorMessage -eq "The remote server returned an error: (409) Conflict.")
       {
         Write-Host "Error creating user: A user with the same username $($User.userName) already exist" -foregroundcolor yellow
       }
       
       else 
       {       
         Write-Host "Error has occurred: $($ErrorMessage)" -foregroundcolor Red
       }
    }   

#Get user information
    $UserName = $User.userName
    $UserId = (Invoke-RestMethod -ContentType application/json -Uri "$Url/Users`?filter=userName%20eq%20%22$UserName%22" -Method GET -Headers $Headers).Resources.id
    $Groups = $User.memberOf -split ";"

#Loop through each group and add user to group
    foreach($Group in $Groups){

If (-not [string]::IsNullOrWhiteSpace($Group)) 
{
#Get the GroupName and GroupId
    $GroupName = $Group.trim()
    $GroupId = (Invoke-RestMethod -ContentType application/json -Uri "$Url/Groups`?filter=displayName%20eq%20%22$GroupName%22" -Method GET -Headers $Headers).Resources.id

#Store group membership in variable. 
    $AddUserToGroup = @{
            Operations = @(@{ op = "add"; path = "members"; value = @(@{ value = $UserId })})
            }
            
    #Convert to json format
    $AddUsertoGroupjson = $AddUserToGroup | ConvertTo-Json -Depth 4

    #Add users to group in AWS IAM Identity Center
    
        try {
    $Responses = Invoke-RestMethod -ContentType application/json -Uri "$Url/Groups/$GroupId" -Method PATCH -Headers $Headers -Body $AddUsertoGroupjson -UseBasicParsing
    Write-Host "Add user to group: The user $($User.userName) has been added successfully to group $($GroupName)." -foregroundcolor green

    }
    catch 
    {
    
      $ErrorMessage = $_.Exception.Message

	if ($ErrorMessage -eq "The remote server returned an error: (409) Conflict.")
       {
         Write-Host "Error adding user to group: The user $($User.userName) is already added to group $($GroupName)." -foregroundcolor yellow
       }
       
       else 
       {       
         Write-Host "Error has occurred: $($ErrorMessage)" -foregroundcolor Red
       }
    }
   }        
  }
}

Use Windows PowerShell to run the script create_users.ps1, as shown in the following figure.

Figure 4: Run PowerShell script to create users from CSV in AWS IAM Identity Center
Use the AWS IAM Identity Center console to verify that the users and groups were successfully created. In the AWS IAM Identity Center console, select Users from the left menu, as shown in figure 5.

Figure 5: View the newly created users in AWS IAM Identity Center console
Use the AWS IAM Identity Center console to verify that the groups were successfully created. In the AWS IAM Identity Center console, select Groups from the left menu, as shown in figure 6.

Figure 6: View the newly created groups in AWS IAM Identity Center console

Your users, groups, and group memberships have been created in AWS IAM Identity Center. You can now manage access for your identities in AWS IAM Identity Center across your own applications, third-party applications (SaaS), and Amazon Web Services (AWS) environments.

How to run the PowerShell scripts on Linux and macOS

While this post focuses on running the PowerShell script on a Windows system. You can also run the PowerShell script on a Linux or macOS system that has PowerShell Core installed. You can then follow the steps in this post to create the required CSV files for creating a user and group and adding a user to a group. Then, on your Linux or macOS system, you can run the PowerShell script using the following command.

pwsh -File <Path to PowerShell Script>

Conclusion

In this post, we showed you how to programmatically create users and groups from a CSV file into AWS IAM Identity Center. This solution isn’t a replacement for automatic provisioning. However, it can help you to quickly get up and running with AWS IAM Identity Center by reducing the administration burden of manually creating users in AWS IAM Identity Center.

If you have feedback about this post, submit comments in the Comments section below.

Want more AWS Security how-to content, news, and feature announcements? Follow us on Twitter.

AWS Security Blog