Configuring Single Sign-on (SSO) for Users and Agents
Overview
This configuration guide relates to the setup of Single Sign-On for your end users/agents when using the Symbee Connect desktop UI for contact servicing and call handling. If you are looking for instructions on set up of Single Sign On to your Symbee Connect Administration Portal for administration users, refer to here.
Symbee Connect delegates the initial user authentication to the Amazon Connect instance it is configured for use with. When the user clicks sign-in on the Symbee Connect UI, Amazon Connect pops its Login window requesting the user and password for authentication, and then once authenticated Symbee Connect closes the window and loads.
User single sign-on into Symbee Connect can be achieved by using an external SAML-compliant Identity Provider (IdP) (such as OKTA, Shibboleth, Azure AD, ADFS, Duo, etc.) as your primary user directory, configuring that IdP as a SAML provider to your AWS Console and to Amazon Connect, and then using this configuration reference within Symbee Connect.
In general, if your SAML compliant IdP supports the concept of providing an embeddable URL for a configured SAML SSO App, that can be used outside the actual IdP user console, then SSO with Symbee Connect should be able to be achieved. Each solution refers to these URL’s with differing terminology – common references are: Deep URL, Deep Link, Embeddable URL, etc.
Note: This document is focused on providing general steps for the implementation of Single Sign-On, not solution specific instructions as there are number of SAML-compliant IdPs available in the market. Additionally, given the primary step for all of them is first to configure SAML federation to the AWS Console, and then into Amazon Connect, actual steps for this are provided in AWS documentation and related blogs
Click here for Common Terms relevent to this document.
Setting up your Symbee Connect Single Sign On
Refer to the Configure SAML with IAM for Amazon Connect documentation for step by step instructions.
Note: this documentation here identifies additional information where appropriate.
1. Configure your Amazon Connect instance to use SAML as its User identity mechanism
In Amazon Connect, define the user identity mechanism to use during initial Instance creation.
Important: You cannot change (either to or from) SAML after you have already created/configured your instance.
2. Set up SAML federation between your IdP and your AWS Account
Within AWS, setting up federation with an external IdP is a function of the Identity and Access Management (IAM) AWS service.
See the AWS IAM documentation here for step by step instructions for configuring your external IdP solution to be federated with AWS using SAML.
Before you begin:
-
In general, within the context of this document (setting up SSO for Amazon Connect and Symbee Connect), the federation established between your IdP and AWS is designed to allow users that don’t otherwise have or need access to your AWS console, the ability to use specific services (e.g. Amazon Connect) inside your AWS account, without having to create individual IAM users for all your Connect users. That said, you still need to declare the users within Amazon Connect (to match the same user in your IdP)
-
When following the document above, you will need to update your IdP configuration and your AWS IAM configuration at the same time, as they are dependent on each other:
- To declare a new IdP within your AWS IAM service, you will need to upload a SAML Metadata Document (an XML file) that describes your IdP configuration. This file needs to be generated/downloaded from your IdP.
-
In order to download the SAML Metadata Document from your IdP, you will at least have to begin the configuration for the AWS SAML federation within your IdP first. However, you will likely not be able to complete your IdP configuration prior to completing the AWS IAM IdP and related IAM Roles and Policies configuration first.
-
When configuring your IdP system for AWS federation, AWS plays the role of the SAML Service Provider in the relationship. When you are asked for the AWS SAML Metadata Document (sometimes called Service Provider SAML Metadata document) within your IdP configuration, it can be downloaded from here.
-
When configuring (or troubleshooting) your IdP system for AWS federation, if you are asked for the AWS Sign-In SAML endpoint URL (or possibly referred to as the Service Provider Sign-In SAML endpoint), it can be downloaded here.
-
When you configure the AWS federation in your IdP, it is usually part of the definition of an Application in your IdP that will be assigned to users so they can click on it in an IdP portal or console.
- User access within AWS is controlled through one or one IAM Roles defined and associated with your IDP's declaration in IAM.
- Each IAM Role has polices defined to it declaring exactly which resources can be accessed when using that Role.
- In support of having multiple different IdP federation Roles assigned/available, many IdP’s have a configuration section that allows the IdP to retrieve a list of available roles for populating drop-down lists in the IdP configuration GUI, or providing a picklist in the IdP portal to the user if they have privileges assigned that allow multiple roles to be used.
- To achieve the above, the IdP documentation may ask you to create an IAM User inside your AWS account. Note: the IAM User does not represent an actual user in your organization (and it shouldn’t), it is a system defined user that your IdP uses for access to the IAM service in your AWS account to pull a list of IAM Roles assigned to its IDP definition in IAM.
- For further information, check out the Enabling SAML 2.0 federated users to access the AWS Management Console
3. Configure an SSO Application in your IdP for the Amazon Connect CCP
Modify, or add to your setup performed step 2, to have an Application definition in your IdP that logs you into your AWS Account and specifically lands you within the Amazon Connect service. More specifically, the Amazon Connect CCP (Contact Control Panel – the default Amazon Connect Agent UI)
If the details of the linked documents from Step 1 and 2 have been followed successfully, technically you should already be at the point where you have an Application defined in your IdP portal, that results in single sign-on into Amazon Connect and the agent/user CCP (Contact Control Panel) web UI being loaded.
Key Notes:
- If SAML federation between your IdP and the AWS console is set up, and the related IAM Role in your AWS account provides correct Policy access to your Amazon Connect service, but you are still not arriving all the way through to the Amazon Connect CCP, check the destination parameter of your SAML RelayState property - Amazon Connect uses this to determine where you land.
- For AWS, you can optionally set the destination in the SAML RelayState in your IdP configuration, to indicate what page or AWS service to be redirected to after the initial AWS Console authentication is complete – in this case you want to go to the Amazon Connect CCP URL /connect/ccp.
See Use destination in your relay state but consult the documentation of your IdP for how exactly to set this up in your IdP configuration, as each IdP is different.
Once you have an Application definition in your IdP that results in SSO all the way into the Amazon Connect CCP, locate and copy the IdP deep-link URL that represents this App definition (you will use it in Step 4 ) – this is a URL that when clicked or used outside of the IdP portal, causes the SAML SSO steps to be executed and results in the CCP window.
Note: Each IdP solution refers to these deep URL’s with differing terminology – common references are: Deep URL, Deep Link, Embeddable URL, etc.
4. Configure Symbee Connect for SSO using IdP deep-link of Amazon Connect SSO application
With the deep-link URL obtained in Step 3 above, follow the steps below for the remaining configuration performed within Symbee Connect:
- Log into the Symbee Connect Administration Portal.
- If you have more than one Environment configured within your Company in Symbee Connect, ensure you select the appropriate Environment you are configuring. This can be located on the top Navigation bar.
- Then click on the main Function menu in the top navigation bar and the select Amazon Connect Integration located under the Company Environment Configuration section. The following view will be displayed, providing the settings specific to your Amazon Connect instance integration:
- Tick the check box on Amazon Connect Single Sign-On Behavior enabled.
- Paste your deep-link URL obtained in Step 3: Configure an SSO Application in your IdP for the Amazon Connect CCP into the Amazon Connect Single Sign-On URL field.
- Tick the check box on Auto-Close Amazon Connect Window during Sign-On.
- Save your changes.
Verify by testing your user/agent Symbee Connect URL provided on the home page. If everything is configured correctly, the Symbee Connect UI will display, and clicking “Sign-in” should result in you being automatically signed in without being prompted for user and password (assuming you are already signed in to your IdP).
5. Hide Amazon Connect SSO application icon from your IdP console(Optional)
If your IdP solution supports it, we recommend you hide the Amazon Connect SSO application icon from your IdP console so the user can’t see it, and instead configure a short-cut to your Symbee Connect URL in your IdP console. Please note, some IdP solutions do not support this, which is why we class this as optional.
With everything configured correctly, your agents should no longer need to directly access the Amazon Connect App defined in your IdP portal (the one you configured in Steps 2 and 3).
Instead they should use the Symbee Connect User/Agent URL (the URL provided on the Home page of your Symbee Connect Administration portal).
Some IdPs allow you to configure an Application, assign it to Users (in terms of allowing them privileges to use it), but then also allow the application to be “hidden” (not visually displayed to the user on the IdP portal). If your IdP allows this, you can “hide” the Amazon Connect CCP SSO Application from the user’s portal.
If your IdP also allows the option of simple Shortcut or Bookmark URL’s (Applications that are really just a URL link) to be configured and assigned to user portal pages, configure a “shortcut” Application that simply loads the Symbee Connect User/Agent URL.
Common Terms
| Term | Definition |
|---|---|
| SSO | Single Sign-on The ability to log into one system, and then use another system without being re-prompted for security/authentication credentials again. |
| IdP, IDP | Identity Provider An Identity Provider is a system where you can maintain your master list of Users and their primary authentication credentials and offers “user authentication as a service” to other applications in your enterprise. |
| Federation, Identity Federation, Federated Identity |
In the contexts of SSO, user identity, and user authentication, Federation in general implies an agreement to allow users logged in (i.e. authenticated) to one system, to be trusted by another (or multiple other) systems, such that the user is not prompted for authentication again when using the other systems, after having logged in to the first. |
| SAML | Security Assertion Markup Language (SAML) Security Assertion Markup Language (SAML) is an open standard for sharing security information about a users’ identity, authentication and authorization, between different systems. |
Troubleshooting issues with IDP SAML Federation into AWS
The following document provides a good description of each of the possible errors you might see when testing your IDP integration into AWS, and the likely reason for each error condition:
Troubleshooting SAML 2.0 federation with AWS
Notes on Common Identity Providers
Microsoft Azure Active Directory (AD)
The following AWS posted blog provides a very good step by step set of instructions walking you through the configuration of an Enterprise Application definition within Azure AD, and the respective configuration required in IAM in your AWS account.
Configure single sign-on using Microsoft Azure Active Directory for Amazon Connect
Note: There is one key step missing/not explained well in the above blog...
After you have completed all the steps in the above, if when testing your final URL, you land on an AWS page with the message "Your request included an invalid SAML response", its likely because the 3 SAML Claims required by AWS are not configured within your Azure Enterprise Application.
In Azure, within the new Enterprise Application created above, under Manage, Single sign-on, SAML (the Setup Single Sign-On with SAML page):
- Click to edit the User Attributes & Claims
- Confirm the following Claims exist, and if not, you will need to configure them manually (using the + Add new claim button):
| Claim Name | Namespace | Source Attribute |
|---|---|---|
| RoleSessionName | https://aws.amazon.com/SAML/Attributes | user.userprincipalname |
| Role | https://aws.amazon.com/SAML/Attributes | user.assignedroles |
| SessionDuration | https://aws.amazon.com/SAML/Attributes | Enter a static value of 36000 (10 hours, in seconds) |
Okta
The following AWS posted blog provides a good step by step set of instructions walking you through the configuration of an Application definition within your Okta account, and the respective configuration required in IAM in your AWS account.
Configure Single Sign-On for Amazon Connect Using Okta