AWS Contact Center

Configure Single Sign-On for Amazon Connect Using Okta

Securing access to your IT resources is paramount. As the number of web-based applications that your employees use increases, so does the difficulty for them to remember their login credentials. Many companies have turned to single sign-on with a variety of identity providers to streamline access to resources and simplify their employees’ routines. With Amazon Connect, you can use any SAML 2.0 compliant identity provider to provide credentialed access to your contact center. This post walks you through the steps required to use Okta as the identity provider for Amazon Connect.

Okta is one of the most commonly used providers of Single Single-On services using SAML 2.0 authentication. While setting up Okta is mostly the same as configuring any other SAML provider, this post specifically describes the steps for using Okta. This simplifies the general guidance that describes how to configure SAML for identity management in Amazon Connect.

The configuration for the purposes of this post uses:

·       Okta

·       AWS Identy and Access Management (IAM)

·       Amazon Connect

To complete the steps in this post, you need the following:

1.    An active AWS account.

2.    IAM rights to create new IAM roles, policies, and users.

3.    IAM rights to create a new Amazon Connect instance.

4.    An Okta account. For this post, we show the steps using an Okta developer account.

This is functionally no different from a standard account.

Create an Amazon Connect Instance
For Amazon Connect, define the identity management system that is used at instance creation. Once it is chosen, it cannot be changed. As such, you might need to create a new Amazon Connect instance to integrate with Okta. For the purposes of this blog post, most of the details of the Amazon Connect configuration are not be discussed. For more information about how to configure an Amazon Connect instance, see the Getting Started with Amazon Connect section of the Amazon Connect Administrator Guide.

To create a new Amazon Connect instance with SAML 2.0-based authentication:

1.    Open the Amazon Connect Console in the AWS Management Console.

2.    Make sure to select the Region that you would like to use

3.    Do one of the following:

If you have not previously created an Amazon Connect instance in the selected Region, choose Get Started.

If you have previously created an Amazon Connect instance in the selected Region, choose Add an Instance.

4.    For Step 1: Identity management, choose SAML 2.0-based authentication

5.    For Access URL, enter an instance alias for your instance, and choose Next step.

Note: The name that you enter is displayed as the instance alias in the AWS Management Console, and is used as the domain in the access URL when setting up Okta. The alias must be globally unique and cannot be changed after the instance is created.

6.    For Step 2: Administrator, enter the First Name, Last Name, and Username for the account to use as the administrator for your instance, and choose Next step. This should be an account          that already exists in Okta.

Note: It is critical that the user name entered matches the user name in Okta exactly, including the case.

7.    For Step 3: Telephony Options, keep the defaults selected (you can change this later), and choose Next Step.

8.    For Step 4: Data Storage, keep the defaults selected (you can change this later), and choose Next Step.

9.    For Step 5: Review and create, review your settings, and choose Create instance.

10.  After your instance has been created, you can see the Amazon Connect Documentation to complete the setup of you contact center.

Now that your Amazon Connect instance has been created, create AWS Identity and Access Management policies that control what resources Okta has access to.

Create the IAM policies

For the SAML integration to work, create the appropriate policies that grant access to specific resources and rights. Two required policies will be created. The first policy enables federation for all users in a specific Amazon Connect instance. The second allows Okta to list IAM roles and account aliases.

To create the Amazon Connect Federation policy:

1.    Open the IAM Console.

2.    In the navigation pane, choose Policies.

3.    Choose Create policy.

4.    Choose the JSON tab.

5.    Paste the following policy into the editor, replacing the existing content:

{

    “Version”: “2012-10-17”,

   “Statement”: [

        {

            “Sid”: “Statement1”,

            “Effect”: “Allow”,

            “Action”: “connect:GetFederationToken”,

            “Resource”: [

                “**YOUR ARN**/user/${aws:userid}”

            ]

        }

    ]

}

6.    Replace **YOUR ARN** with the ARN for your instance. To find your ARN:

a.    Open a new tab and go to the Amazon Connect Console.

b.    Choose your instance alias.

c.    Copy the value for the instance ARN.

7.    Verify the replacement, and choose Review Policy.

8.    Name your policy okta_federation_policy, or something similar.

9.    Optionally, provide a description for the policy.

10.  Choose Create policy.

To create the Okta access policy:

1.    Open the IAM Console.

2.    In the navigation pane, choose Policies.

3.    Choose Create policy.

4.    Choose the JSON tab.

5.    Paste the following policy into the editor, replacing the existing content:

{

    “Version”: “2012-10-17”,

    “Statement”: [

        {

          “Effect”: “Allow”,

          “Action”: [

              “iam:ListRoles”,

              “iam:ListAccountAliases”

          ],

          “Resource”: “*”

        }

    ]

}

6.    Verify the replacement, and choose Review Policy.

7.    Name the policy okta_cli_policy, or something similar.

8.    Optionally, provide a description for the policy.

9.    Choose Create policy.

Once the policies have been created, create the IAM user that has programmatic access to AWS resources. This lets Okta to retrieve the appropriate resources from your AWS account.

To create the user:

1.    Open the IAM console.

2.    In the navigation pane, choose Users.

3.    Choose Add user.

4.    In the Set user details section, provide a User name, such as okta_cli_user.

5.    In the Select AWS access type section, choose Programmatic access.

6.    Choose Next: Permissions.

7.    In the Set permissions section, choose Attach existing policies directly.

8.    In the search field, enter okta. The available policies filter.

9.    Choose the policy that you created previously.

10.  Choose Next: Tags.

11.  Optionally, add tags, and choose Next: Review.

12.  Choose Create user.

13.  On the success page, download the credentials.csv file that contains your user credentials.

Now that the user has been created, add the Amazon Web Services app to Okta and build the IAM Identity provider simultaneously. This is required, as each depends on information from the other. You start with the Okta Amazon Web Services App.

To add the Amazon Web Services application to Okta and create the Identity Provider:

1.    Login to your Okta administrator account.

2.    If you are in the developer dashboard, switch to the Classic UI by choosing Classic UI from the drop-down in the upper right-hand corner.

3.    Choose Applications.

4.    Choose Add Application.

5.    In the search bar, enter Amazon Web Services

6.    Choose Add next to the Amazon Web Services application.

7.    For the Application label, enter Amazon Connect Administrator.

8.    In the Your AWS Login URL, enter https://console.aws.amazon.com/.

9.    Keep the defaults for all other boxes, and choose Next.

10.  On the Sign-On Options page, in the Sign On Methods section, choose SAML 2.0.

11.   In the SAML 2.0 section, for the Default Relay State, enter the URL as follows:

https://region-id.console.aws.amazon.com/connect/federate/instance-id 

Replace the region-id with the Region name where you created your Amazon Connect instance, such as us-east-1 for US East (N. Virginia). Replace the instance-id with the instance ID for your instance.

To find your instance ID:

a.    Open a new tab and go to the Amazon Connect Console.

b.    Choose your instance alias.

c.    The instance ID is everything after the last / in the Instance ARN. For example:

       arn:aws:connect:us-west-2:123456789:instance/00aa11b2-c333-4d55-e6f7-888g9999hh0

12.  Right-click Identity Provider metadata, and save the target file to your computer as metadata.xml.

13.  Do not close this tab. You need to continue the setup shortly.

14.  Open a new tab and go to the IAM Console.

15.  In the navigation pane, choose Identity Providers.

16.  Choose Create provider.

17.  Choose SAML as the Provider Type.

18.  For Provider Name, enter Okta_Connect_Admin.

19.  In the Metadata Document section, choose the metadata.xml document that you saved in step 12.

20.  Choose Next step.

21.  Validate the provider information, and choose Create.

22.  Once the creation completes, choose Okta to view the details.

23.  Copy the Provider ARN and paste it to a text file for future use.

24.  In the IAM console, in the navigation pane, choose Roles.

25.  Choose Create role.

26.  Choose SAML 2.0 federation.

27.  In the SAML provider section, choose Okta_Connect_Admin.

28.  Choose Allow programmatic and AWS Management Console access.

29.  Choose Next: Permissions.

30.  In Filter policies, enter okta.

31.  Select both policies that you created earlier.

32.  Choose Next: Tags.

33.  Choose Next: Review.

34.  For Role name, enter Okta_Role.

35.  Choose Create Role.

36.  Return to the Okta tab.

37.  In the Advanced Sign-On Settings section, paste the Identity Provider ARN that you copied into the Identity Provider ARN field.

38.  Choose Done.

Now that the app is built, give it access to AWS. To do this, you need the credentials file you downloaded earlier.

To provide Okta with programmatic access:

1.    While logged in to Okta Administrator, choose Applications.

2.    Choose Amazon Connect Administrator.

3.    Choose Provisioning.

4.    Choose Configure API Integration.

5.    Choose Enable API Integration.

6.    In the Access Key field, paste the access key from your credentials.csv file.

7.    In the Secret Key field, paste the secret key from your credentials.csv file.

8.    Choose Test API Credentials.

9.    After the credentials are verified successfully, choose Save.

10.  Choose To App.

11.  Choose Edit.

12.  Enable Create Users.

13.  Click Save.

14.  After the page refreshes, scroll to the bottom of the page to the Amazon Connect Administrator Attribute Mappings section. You should see a list of attributes.

 

After you have provided Okta with programmatic access, you are ready to assign the application to users. Complete this in the Okta administrator.

To assign the new application to your admin user:

1.    While logged in to Okta Administrator, choose Directory.

2.    Choose the admin user that you configured when you built your Amazon Connect instance.

3.     Choose Assign Applications.

4.    Choose Assign next to Amazon Connect Administrator.

5.    In the Role drop-down, select Okta_Role.

6.    Choose the SAML User Role Okta_Role.

7.    Choose Save and Go Back.

8.    Choose Done.

To test the application:

1.    Login to Okta as your configured Amazon Connect administrator.

2.    Choose Amazon Connect Administrator.

3.    A new tab opens. Perform the authentication, then redirect to Amazon Connect.

4.    You should now be logged in to Amazon Connect as the administrator.

You now have an Amazon Connect Administrator app that uses SAML Authentication from Okta to login to Amazon Connect. To build a second application that launches the Amazon Connect Contact Control Panel (CCP), you would perform the many of the same steps, not including the Amazon Connect instance creation.

In summary:

1.    Create a new Application in Okta.

2.    Create a new Identity Provider in IAM.

3.    Create a new IAM role that uses the new Identity Provider.

4.    Complete the application setup using a modified relay URL that points to the CCP specifically using the following example:

https://us-east-1.console.aws.amazon.com/connect/federate/instance-id?destination=%2Fconnect%2Fccp

5.    Configure API access for the app.

6.    Enable provisioning.

7.    Assign the app to users.

8.    Create the Agent users in Amazon Connect.

NOTE: It is critical that the user name entered matches the username in Okta exactly, including case sensitivity.

How This Works
Using a federation application like Okta allows users to navigate and log into Amazon Connect with the proper credentials, permissions, and security controls.

SAML requests go through the following steps:

1.    The user either launches the Okta App or navigates to the URL Okta generates.

2.    Okta requests authentication from the organization’s identity store.

3.    The identity store authenticates the user and returns the authentication response to the federation service.

4.    When authentication is successful, the federation service posts the SAML assertion to the user’s browser.

5.    The user’s browser posts the SAML assertion to the AWS sign in SAML endpoint (https://signin.aws.amazon.com/saml). AWS sign-in receives the SAML request, processes the request, authenticates the user, and forwards the authentication token to Amazon Connect.

6.    Using the authentication token from AWS, Amazon Connect authorizes the user and opens Amazon Connect in their browser.

Conclusion

This post walked you through the creation and configuration of the Okta app, the configuration of the AWS Identity Provider and Amazon Connect.  This allows users and administrators at your company to log in to Amazon Connect using a familiar and secure process through the Okta interface.

If you are using a SSO product other than Okta, the same principals and AWS configurations apply, but the configuration of the SSO application varies depending on the application.

For more information about Amazon Connect Single Sign configuration, see Configure SAML for Identity Management in Amazon Connect.  For more information about Amazon Connect, see the Amazon Connect documentation.