Have A Question?

< All Topics
Print

Configuring Single Sign On

Introduction

This how-to guide describes the process to set up a NEON instance with Single-Sign-On (SSO) federation to a SAML provider, specifically Azure Active Directory.

For instruction set to other Identity Providers (IDPs) please contact our support email address sales@cloudwave.com.au.

Design/Implementation Considerations

The following are key considerations for setting up NEON with SSO federation:

  1. Each NEON Instance can only point to one IDP instance – it is possible to configure multiple federations against Amazon Connect, however only one app-initiated IDP flow can be configured.
  2. IDP/ attribute mappings/translations – usernames in Amazon Connect must 100% match (including case) the mapped field/translation within the IDP. Ensure consideration is made towards username format that will appear in Amazon Connect, thus propagate any integration, including WFM etc.
  3. When a new Instance of NEON is created, a ‘First User’ in NEON is created. This user must be already existing in Connect, and ideally you should ensure this is working before creating the NEON instance.

Pre-Requisites

  • An AWS account, as well as:
    • A user in the account with permission to create and modify IAM resources
  • An Amazon Connect instance set up with SAML 2.0, as well as:
    • A user in the instance that will act as the initial Amazon Connect / Neon administrator, that has the Admin security group
    • The ARN, region, and instance ID of the Amazon Connect instance (the instance ID is the text after the last forward-slash in the ARN)
  • An Azure AD subscription, as well as:
    • A user in Azure AD to act as the initial Amazon Connect / Neon administrator, with the exact UPN as the login of the user in the Amazon Connect instance
    • A user in Azure AD with permission to create and modify Enterprise Applications
  • A NEON instance deployed for the Amazon Connect instance, as well as:
    • The initial user for the NEON instance configured to match the user set up in Amazon Connect and Azure AD.

Configuration

1. Creating the Azure AD Enterprise Application

  1. In Azure AD, navigate to Enterprise Applications.
  2. Select All applications, then New Application.
  3. In Browse Azure AD Gallery, search for and select AWS Single Account Access, name the application Amazon Connect Federation or similar, then choose Create.
  4. Select Single sign-on and choose SAML, then select Yes in the Save single sign-on setting pop-up.
  5. Select Edit in the Basic SAML Configuration pane.
  6. Fill out the Relay State field with the following URL: https://<regionid>.console.aws.amazon.com/connect/federate/<instance-id>?destination=%2Fconnect%2F, where <regionid> is the region of the Amazon Connect instance (e.g. ap-southeast-2) and <instanceid> is the instance ID of the Amazon Connect instance.
  7. If required (if there are multiple AWS SAML apps in this Azure AD) append a hash followed by a unique ID to the Identifier (Entity ID) field (e.g. #1)
  8. Choose Save then close the pane and click the Download link next to Federation Metadata XML in the SAML Certificates pane.


2. Creating the IAM resources

Resources must be created in AWS IAM and Azure AD to enable federation between the two services. These resources allow each service to access

Creating the IAM Identity Provider

Create an IAM identity provider with SAML as the provider type, and azure_connect_idp or similar as the provider name. Upload the metadata.xml generated by Azure AD earlier in the Metadata Document section. Follow the prompts to finish creating the resource.

Federation IAM Policy

Create an IAM policy from the following JSON, replacing **YOUR ARN** with the ARN of your connect instance:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Statement1",
            "Effect": "Allow",
            "Action": "connect:GetFederationToken",
            "Resource": [
                "**YOUR ARN**/user/${aws:userid}"
            ]
        }
    ]
}

Name the policy azure_federation_policy or similar.

Azure AD Access IAM Policy

Create an IAM policy from the following JSON:

{
    "Version": "2012-10-17",
    "Statement": [
        {
          "Effect": "Allow",
          "Action": [
              "iam:ListRoles",
              "iam:ListAccountAliases"
          ],
          "Resource": "*"
        }
    ]
}

Name the policy azure_cli_policy or similar.

Azure AD Access IAM User

  1. Create an IAM user with username azure_cli_user or similar
  2. Do not check Provide user access to the AWS Management Console.
  3. In the Set permissions section, choose Attach policies directly, and choose the azure_cli_policy.
  4. Follow the remaining prompts, then when returned to the users list select the new user.
  5. Select Security credentials, then Create access key.
  6. Select Application running outside AWS and follow the remaining prompts. Download the CSV file before selecting Done.

Federation IAM Role

  1. Create an IAM role, and select SAML 2.0 federation in the Select type of trusted entity section.
  2. Select the Identity Provider created earlier in the SAML provider section, and choose Allow programmatic and AWS Management Console access.
  3. Choose Next then select both policies created earlier.
  4. Follow the remaining prompts, and name the role azure_federation_role or similar, then choose Create Role.

3. Configuring the Federation relationship

Configuring the Enterprise Application with the IdP

  1. In Azure AD, navigate back to the Enterprise Application created earlier.
  2. Select Provisioning on the left then Get started.
  3. Set the Provisioning Mode dropdown to Automatic, then fill the clientsecret and Secret Token fields in the Admin Credentials section with the Access key ID and Secret access key (respectively) in the credentials.csv file created earlier.
  4. Select Test Connection, then Save.

Assigning users

  1. In Azure AD, navigate to the Users and Groups section of the Enterprise Application created earlier.
  2. Select Add user, then select the user that was configured in Amazon Connect and NEON as the initial administrator.
  3. In Select Role, select the Federation role created earlier. If no role is selectable, the handshake between Azure AD and AWS IAM may still be in progress. This may take up to 40minutes depending on your environment. Note, provisioning must be started and monitored (via the ‘start’ button). View logs and await role syncs
  4. Select Assign.

4. Testing

It is advised that testing should be carried out against the Amazon Connect instance, before configuring NEON with SSO. This is achieved by visiting https://myapplications.microsoft.com and selecting the enterprise application configured above. You should be taken to the base Amazon Connect page.

In case of any issues, see this link for troubleshooting https://docs.aws.amazon.com/connect/latest/adminguide/troubleshoot-saml.html

5. Configuring NEON

  1. In Azure AD, navigate to the Properties section of the Enterprise Application created earlier.
  2. Copy the User access URL.
  3. In NEON Admin, navigate to your instance and select Customise.
  4. Select Integrations.
  5. Paste the User access URL into the Single Sign On field, and toggle the feature on.
  6. Test the integration by navigating to your instance URL or clicking the Contact Centre Link in your instance summary page.

Further Reading

Table of Contents
Go to Top