Single Sign-On and Genesys Cloud
Single Sign-On is a critical component to ensure a consistent and accessible login process for agents, supervisors, and administrators using Genesys Cloud. With SSO enabled, users log in with the same credentials they use to log in to the network and other applications.
In addition to providing generic identity provider configuration for SAML 2.0, Genesys supports the following third-party SAML-based identity providers:
- Google Workplace
- Microsoft Active Directory Federation Services (ADFS)
- Microsoft Azure Active Directory (AD) with SAML support
- Okta
- OneLogin
- Ping Identity
- PureConnect
- Salesforce
In this example, we are using Microsoft Azure AD as the third-party SAML-based identity provider. In the majority of organisations, the User Principal Name (UPN) in Azure AD is the same as the user's email address.
This article will explain the steps needed if the customer Azure AD has a different UPN and email; we also include the troubleshooting steps to identify such an issue.
SSO Integration Configuration
User Principal Name and the Email Address are the same
If the UPN and the user's email address are the same, the SSO integration is straightforward by deploying Genesys Cloud for Azure from the Azure AD apps gallery. For the steps, you may refer to this tutorial from Microsoft.
User Principal Name and the Email Address are different
When the UP and the user's email address are different, the SSO integration is more involved, and we recommend planning and implementing according to these steps:
Creating Azure AD Custom Genesys Cloud Application
We recommend creating a custom Genesys Cloud application in Azure AD to provide maximum control and ability to configure.
Follow these steps to create the application in Azure AD
Select 'Enterprise Apps' for the left-hand pane
Select 'New Application' from the top row options
Select 'Non-Gallery App', which can be seen in the legacy app gallery view
In the 'Name' field, give the app a name – such as "Genesys Custom Cloud SSO" and select the 'Add' button.
Azure AD Custom Application Configuration
Once the Azure AD custom application has been created, follow the next steps to configure it for use with Genesys Cloud SSO.
Select 'Setup Single Sign-On'
Select 'SAML'
In the Basic SAML configuration, select 'Edit'.
Configure the 'Identifier (Entity ID)', 'Reply URL', and 'Logout URL'.
The 'Identifier (Entity ID)' can be any value unique to the Azure instance. The 'Reply URL' and 'Logout URL' are based on the AWS region where your Genesys Cloud organisation was created.
AWS Region |
Reply URL |
Logout URL |
|---|---|---|
US East (N. Virginia) |
||
US West (Oregon) |
||
Canada (Canada Central) |
||
EU (Frankfurt) |
||
EU (Ireland) |
||
EU (London) |
||
Asia Pacific (Mumbai) |
||
Asia Pacific (Seoul) |
||
Asia Pacific (Sydney) |
||
Asia Pacific (Tokyo) |
In Attributes & Claims configuration, click 'Edit'.
Enter the following attribute names
| Attribute Name | Attribute Value |
|---|---|
| OrganizationName | Your Genesys Cloud organisation short name |
| user.mail | |
| Unique User Identitier | Can leave this option as default |
Select 'Save'
Next, you may assign the users and groups to the Enterprise App that you've created. The Microsoft Azure AD custom application configuration is now complete.
Configure the SSO Integration on Genesys Cloud
Now that the Azure AD custom application has been configured, you may proceed to configure the SSO integration on Genesys Cloud. The standard process for configuring Genesys Cloud to use Azure AD should be used; this link contains the Genesys guide for this configuration.
SSO Troubleshooting Guide
Gathering Network Logs
Network logs provide visibility into the actions and events on an agent’s computer when problem occurs. It is commonly used to debug network problems or analyse performance. Network logs often contain important error details essential to identify the root cause of the issue you’re facing in Genesys Cloud. In this use case, we are using it troubleshoot any SSO related issues
Step 1: Gather Genesys Console Network Logs
You will need to gather the Genesys Console network logs from the Internet Browser. You may refer to this link for the steps to gather network logs on Chrome.
Step 3: Generate SAML Tracing logs
Log in to Genesys Cloud with SSO by clicking the Microsoft icon. You should see some SAML tracing on the network logs in real-time.
Checking SAML Attributes
Once the Network Logs have been gathered, they can be used to diagnose any issues with SAML attributes.
Step 4: Select the 'SAML request' on the network logs.
Under the Headers section and scroll to the bottom, you should see the SAML Response. Select the data and right-click to copy the data.
Step 5: Go to https://www.samltool.com/decode.php.
Paste the copied value under Deflated and Encoded XML and click on Decode and Inflate XML.
The deflated XML window is small and hard to read; pasting it into a Text Editor make further analysis more accessible.
Analysing the XML, you will be able to identify if the SSO configuration is done correctly on both Azure AD and Genesys Cloud by identifying the attribute value. In the example below, we can look for the configured ADFS issue URI in Genesys Cloud (highlighted in yellow). Also, we can identify the attribute values are configured correctly from the network log. In this example, we can see that the “OrganizationName” is “teXXXXXbal” and “email” is YeeFan.Chan@XXXXXXXXXXXX.com (highlighted in green and orange respectively)
