Automate SAML user provisioning for Microsoft Azure Active Directory and OKTA with Amazon Connect

Businesses automate new employee onboarding processes using a standard service management platform. For example, when a new hire joins an organization, human resource systems feed the directory services (Active Directory, LDAP, Etc.) to create a login identifier for the new hire. It then generates the new employee’s mailbox, and assigns the new user to distribution lists and security groups for automatic access to required resources. This workflow is usually without any human interaction. Provisioning contact centers agents should not be any different.

Amazon Connect offers the ability to use an external directory for user management. It also offers the ability to use a SAML-based identity provider to authenticate users using existing company credentials.

In this blog post, we demonstrate automated user onboarding capability using provisioning API operations within Amazon Connect with two sample identity providers, Microsoft Azure Active Directory and OKTA. The implementation can be extended to other identity providers with minor changes.

Solution Overview

The following diagram represents a high-level architecture for the user provisioning framework:

For automated user provisioning, we leverage SCIM (System for Cross-domain Identity Management) protocol. Most identity providers support SCIM as a baseline, and have developed a SCIM endpoint using Amazon API Gateway, Lambda authorizer, and AWS Lambda. The Lambda function uses Amazon Connect API operations to create, update, or remove users; based on instructions coming from a SCIM enabled identity provider (IdP) such as Azure AD or OKTA. In the following sections, we dive deep into the communication sequence and configuration that will be required depending upon the identity provider’s SCIM API.

The following diagram provides the different requests that are generated by the IdP to the SCIM endpoint.

To create only the selected users in Amazon Connect, we will create a user group that will contain only eligible employees. The sync rules will be based on membership in that group. This approach will allow the solution to work for new and existing employees. As employees become eligible, usually after training, they must be added to the user group to initiate this process. Adding and moving users from user groups is standard business practice at most companies.

Let’s get started!

Deployment walkthrough

Prerequisites
For this blog, you should have the following prerequisites:

• An AWS account
• An Amazon Connect instance
•  Access to the following AWS services:
  • AWS Identity and Access Management(IAM)
  • Amazon S3
  • Amazon API Gateway
  • AWS Lambda
• Amazon Connect SAML configured for SSO with Microsoft Azure Active Directory or Okta identity.
• An API token key is required to verify that a trusted application is accessing the API Gateway. We use Lambda authorizer to verify this token. There are several options to generate the API token.
  • AWS
  • OKTA. Create an API Token.
  • Microsoft.
    •  Personal Access Tokens
    • Access Tokens via Azure Apps

Select one of the preceding four options to generate API token key before proceeding further. Make a note of the API token key.

SCIM endpoint deployment in AWS

In this section, you will deploy the CloudFormation template to deploy the SCIM endpoint the IdP will interact with to provision the Amazon Connect users.

1. Login to your AWS Management Console
2. Confirm that the AWS Region selected is the same region as your Amazon Connect instance.
3. Click to launch a Cloud Formation Stack
   you will see the following screen:
4. Accept the default values and choose Next.
5. Enter a stack name (for example, UserProvisioning) and enter:
   1. Amazon Connect instance ID 
   2. API token (refer to the prerequisites section).
   3. Choose Next.
6.  Scroll down to the bottom of the page, and Choose Next.
7. Acknowledge IAM resources creation, and choose Create stack. This will take a few minutes to provision the required resources.
8. On your AWS Management Console, navigate to CloudFormation, Stacks, select UserProvisioning, and choose Outputs. Make a note of SCIMProvisioningTenantURL.
9. You will need the SCIMProvisioningURL and the API token key for the respective SCIM provisioning applications.The following sections cover the steps to configure user provisioning with two sample IdPs – Microsoft Azure Active Directory and OKTA. Choose one of the two to validate the SCIM provisioning functionality.

OKTA

In the following section, you will set up OKTA identity provider to create a user security group, create a sample app with user provisioning enabled, enter the SCIMProvisioningTenantURL created in the previous step, assign the user security group, and add test users to the group to verify the functionality with Amazon Connect.

Step 1: Identity provider portal – Create a user security group called Amazon-Connect-Agents in the identity provider.

1. 1. Enter login credentials (notional representation only)
   2. Navigate to Directory -> Groups, and choose Add Group. Enter the following values in the fields.
      • Name: Amazon-Connect-Agents
      • Description: Used to onboard Connect Users
   3. Choose Save.

Step 2: Create an application in the identity provider that will leverage SCIM
We will now create a custom application in the identity provider portal where users and security groups can be assigned to. The provisioning framework built in the application will automatically initiate the API calls to interact with the Amazon API Gateway and the underlying Lambda functions.

1. For OKTA, choose Browse App Catalog and search for “SCIM 2.0 Test App (Header Auth)”
2. Choose Add integration
3. Provide a unique name AmazonConnectProvisioningApp and make the application invisible to users in the Application visibility settings.

Step 3: Enable provisioning
We will use the outputs that were noted while creating the stack using the CloudFormation template in the above steps, and the API token to enable provisioning within the SCIM application.

Note – Each identity provider expects different format in the base URL that we will enter:

1. 1. Navigate to Integration under Provisioning tab.
      • For Base URL, enter the Amazon API Gateway URL.
      • Enter API Token generated.
      • Choose Test API credentials to validate that the provisioning is successfully communicating with the Amazon API Gateway URL.
   2. Upon successful validation, Choose Save.

Step 4: Group Assignment to Applications

1. Under Assignments, choose Assign, and then choose Assign to Groups.
2. Assign Amazon-Connect-Agents to the application.

Step 5: Attribute Mapping for User Onboarding Verification
In this post, we assume that the identity provider uses Microsoft based Active Directory for Directory Services. The solution uses default attribute mapping, and the user attributes created within Microsoft Active Directory. Amazon Connect users are created based on the following LDAP attributes – username, user.email, and user.department (used for assigning Amazon Connect security profile). The Lambda function provided in this solution uses these specific attributes. If the directory does not provide these attributes, the Lambda function must be modified.

1. Under Provisioning, verify that the following user attributes are active.
2. The following screenshot shows the three user attributes that will be taken as inputs to onboard users into Amazon Connect:

Step 6: Turn on Provisioning

1. Under Provisioning Tab, choose To App
2. Verify that Create User, Update User Attributes, and Deactivate Users are enabled (Enabled by Default).

Step 7: Test Provisioning

1. Navigate to Directory -> Groups, and select Amazon-Connect-Agents
2. Choose Assign People
3. Add users, and choose Save.
4. Navigate to the Amazon Connect Console -> User Management, Verify that the newly added users have been added to Amazon Connect. 
5. To demonstrate the de-provisioning of users inside Amazon Connect, remove a user from the group.
6. In the OKTA management portal, Directory->Groups-> Choose Amazon-Connect-Agents, choose Assign People.
7. Remove one of the users, and choose Save.
8. Notice that the user has been removed from Amazon Connect. 

Microsoft Azure

In the following section, you will set up Microsoft Azure Active Directory identity provider to create a user group, create a sample app with user provisioning enabled, enter the SCIMProvisioningTenantURL created in the previous step, assign the user group and add test users to the group to verify the functionality with Amazon Connect.

Step 1: Log in to the Microsoft Azure Portal
Enter Login Credentials (Notional representation only)

Step 2: Select Azure Active Directory

Step 3: Identity provider Portal – Create a User security group called Amazon-Connect-Agents in the identity provider

Step 3: Create an application in the identity provider that will leverage SCIM

1. Choose Enterprise Applications.
2. Choose + New Application.
3. Choose Create your own application
4. Provide a name for the application (AmazonConnectProvisioningApp), and Choose Create.

Step 4: Enable Provisioning
We will use the outputs that were noted while creating the stack using the CloudFormation template in the above steps, and the API token to enable provisioning within the SCIM application.

1. Choose Provisioning on the navigation pane.
2. Choose Get Started
3. Toggle Provisioning Mode to Automatic. Enter the SCIM Endpoint URL in the Tenant URL field. Enter API Token key generated earlier.
4. Choose Test Connection.
5. Choose Save.

Step 5:  Assign User Security Group

1. Choose Users and groups -> Add user/group.
   
2. Search for Amazon-Connect-Agents group and choose Select.

Step 6: Attribute Mapping for User Onboarding
In this post, we assume that the identity provider uses Microsoft based Active Directory for Directory Services. The solution uses default attribute mapping, and the user attributes created within Microsoft Active Directory. Amazon Connect users are created based on the following LDAP attributes – username, user.email, and user.department (used for assigning Amazon Connect security profile). The Lambda function provided in this solution uses these specific attributes. If the directory does not provide these attributes, the Lambda function must be modified.

1. Navigate to Provisioning -> Edit Attribute Mappings
2. Select Provision Azure Active Directory Users
3. Verify that the following User Attributes are enabled:

Step 7: Turn on Provisioning

Step 8: Test Provisioning.

1. Add Users to Security Group
2. Verify that users are added to Amazon Connect. by navigating to User Management.
3. Verify de-provisioning by removing a user from the security group.
4. Verify that user is removed from Amazon Connect by navigating to User Management 

Cleanup

1. Navigate to the AWS Management Console -> CloudFormation (SCIM endpoint deployment section), and delete the CloudFormation stack deployed.
2. For the respective identity providers, follow the steps following –
   • Login to the identity portal.
   • Unassign the user security group to the SCIM provisioning application created.
   • Delete the user security group Amazon-Connect-Agents.
   • Delete the SCIM provisioning application (the steps may vary from OKTA and Microsoft Azure Active Directory).

Other Considerations

In this section, we cover the implementation changes to extend the pattern for other identity providers:

1. 1.  Identity provider and SCIM endpoints URL. In this blog, we demonstrated Microsoft Azure Active Directory and OKTA. The identity providers have specific guidelines for the URLs and base URL format. For Example,
      • OKTA – https://ovrmrd42xi.execute-api.us-east-1.amazonaws.com/Users?filter=userName%20eq%20%22test.user
      • Microsoft Azure Active Directory – https://ovrmrd42xi.execute-api.us-east-1.amazonaws.com/scim/
   2. Identity provider-specific Communication. Refer to the IdP API documentation for the identity provider for SCIM. For example, Microsoft Azure sends a GET before a PATCH request. The communication sequences vary from provider to provider.
   3. Scalability considerations. Provisioning is handled uniquely by IdPs. For example, Microsoft Azure Active Directory maintains a 40-minute interval (default) where incremental updates are sent to the SCIM endpoint. You can use PowerShell framework blog developed to accelerate this interval.To handle exponential backoff retries, introduce Amazon Simple Queue Service (Amazon SQS) with the API Gateway, and modify the Lambda function.
   4. Attribute Passing. In this blog, we are using LDAP attributes such as user.email and user.department to pass specific parameters (Amazon Connect user name and security profiles). You can send additional attributes and modify Lambda code based on requirements. If user.department is not set in the LDAP attributes, the blog post implementation automatically assigns Agent as the default Security profile for the user in Amazon Connect.
   5. Enhancements. Additional enhancements can be done in the SCIM endpoint implementation to handle additional use cases (for example: users in multiple user security groups, additional attribute handling etc.)

Conclusion

In this blog post, we demonstrated how to deploy a SCIM provisioning portal and integrate with two sample identity providers for onboarding and managing Amazon Connect users. This integration allows automated management of contact center agents through the identity provider portal, and avoids bulk import or manual management of Amazon Connect users. We have shared additional considerations for scaling and enhancing the solution to meet your specific requirements.

Should you need help with implementing these best practices, you can get assistance from AWS professional services. You can also seek assistance from Amazon Connect partners available worldwide.

Reference documentation

The following reference documentation were used to develop the blog:

• OKTA SCIM Concepts
• OKTA SCIM Provisioning and Integration
• Microsoft Azure Active Directory User SCIM to provision users and groups.