Configuring Single Sign-on (SSO) for Users and Agents


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:

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:

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.

With the deep-link URL obtained in Step 3 above, follow the steps below for the remaining configuration performed within Symbee Connect:

  1. Log into the Symbee Connect Administration Portal.
  2. 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.
  3. 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:
  4. Tick the check box on Amazon Connect Single Sign-On Behavior enabled.
  5. 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.
  6. Tick the check box on Auto-Close Amazon Connect Window during Sign-On.
  7. 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.
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):

Claim Name Namespace Source Attribute
RoleSessionName user.userprincipalname
Role user.assignedroles
SessionDuration Enter a static value of 36000 (10 hours, in seconds)


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