Introduction
The SAML federation is usually initiated by the service provider (in LivePerson's case, by the Conversational Cloud). The Conversational Cloud redirects the user to authenticate using the brand's IDP which redirects the user back to the Conversational Cloud with a SAML assertion containing information about the user identity and the authentication metadata for completing the login flow.
Is this feature relevant to me?
Your Conversational Cloud account needs to be migrated to the Advanced Login System in order to use SAML SSO.
Please read this to check if your account is already migrated.
Configuration
Create a SAML Application in your IDP application setup
* Before you start, please note that the configuration steps below refer to an SP-Initiated application. The application could not be launched from your IDP hub (as an IDP-initiated app) without an adjustment. For more information, please read the next section.
The explanation below is generic for creating the configuration for your identity provider. If you are using one of these providers; Azure, PING, OKTA, then please check out refer to the specific user guides.
1. Application Callback URL (also known as redirect URL/URI, Single Sign-On (SSO) URL, Direct Relay State, or Assertion Consumer Service (ACS) URL):
Two variables structure the callback URL:
- See: Login_Tenant_Domain , Full_Connection_Name
- It looks like this:
https://<Login_Tenant_Domain>/login/callback?connection=<Full_Connection_Name>
For example, an account 1234 with the connection name My-brand-name-Okta will be: https://auth-z1.liveperson.net/login/callback?connection=SAML-1234-my-brand-name-okta
2. SAML Assertion Structure
1. loginName attribute
Your SAML Response must contain the loginName attribute.
➡️ Please note that the attribute names, such as “loginName” are case sensitive
The loginName value must be equal to the Conversational Cloud Login Name for the requester user.
2. ‘Audience’ attribute (optional) If your IDP SAML Response contains the ‘Audience’ attribute, it is the Full_Connection_Name.
3. Encrypted SAML Assertion (optional)
You can sign or encrypt both your requests and your responses in the SAML protocol.
For encrypting your SAML content, you need to download our login service’s public key.
The public key can be found here in different formats:
➡️ Please note, in the URLs below, you need to use "?cert=connection" literally and not replace "connection" with the above <Connection Name> or the <Full Connection Name>.
Configure a Conversational Cloud account to authenticate its Agents using a SAML SP-Initiated flow
1. Login to the Conversational Cloud using your admin user
2. From the sidebar menu, browse to Manage-> Management Console
3. Search for the Account Access Control page and open it up
4. Open the Single Sign-ON (SSO) Settings tab
5. Click on the + Add Connection card
6. Choose the SAML connection type and click next
7. Create a SAML Connection
- Enter a unique Connection name (this name will be used to represent this SAML connection)
- Enter your IDP's SAML Sign In URL
- Upload your IDP’s SAML Signing Certificate (.pem or .cer files)
- Click Create connection
8. Now, you will be able to see your connection in the Identity Providers gallery. Note, this is where you can manage it in the future (enable/disable or update the certificate).
Accessing the Conversational Cloud
After completing the configuration parts, your users can use SSO to login to the Conversational Cloud using the SP-Initiated flow.
There are two ways to do this:
- Access the Conversational Cloud login page directly
- The user goes to https://authentication.liveperson.net/
- Enter your account number
- The user will automatically redirected to the Conversational Cloud with a session or to your IDP to complete the login
- Access the brand's IDP dashboard (hub)
- The user opens the brand's hub SSO portal
- The user clicks the Conversational Cloud application
- The user will be redirected to the Conversational Cloud.
➡️ In order to accomplish the above user experience in an SP-initiated flow, there is a need to imitate an IDP-initiated with a bookmark app in your IDP service. If you need help with configuring that, you can read the following example by Okta
➡️ In order for the mock IdP-initiated bookmark link to work, the Local Login feature must be disabled, and only a single SSO (if there is more than one) connection should be enabled.
The link to be used for this bookmarked app is: &prompt=none">https://authentication.liveperson.net/accountSelection.html?stId=<ACCOUNT_ID>&prompt=none
Login tenant domains
Full connection name structure
* The Connection name is defined by you when you register the SAML Connection in the Conversational Cloud
SAML-<account id>-<connection name>
For example SAML-122334-my_conection
IdP integration - Azure
Azure
IdP integration - Okta
Okta
IdP integration - AD FS
This section walks you through the process to integrate Security Assertion Markup Language (SAML) Single Sign-On (SSO) to Conversational Cloud. By using Active Directory Federation Services (AD FS) as your Identity Provider (IdP), you enable your agents to log in to Conversational Cloud with their existing corporate credentials, making access much easier and more secure.
➡️ If a metadata.xml file is requested, edit the XML as described in Appendix A, which is farther below.
Start the integration
In MMC → AD FS, right-click Relying Party Trusts, and choose “Add relying Party Trust.”
Welcome step
Choose Claims aware,” and press “Start.”
Select data source.
Choose Enter data about the relying party manually.
Specify display name
Enter any display name to describe this integration.
Configure certificate
Click Next. (Encryption can be added later.)
Configure URL
There are two parameters with a similar name that you need to construct in order to fill in the service URL:
- Connection name - The connection name is the one used later to call the integration on the LivePerson Conversational Cloud side, but you need to decide what it will be. For example, “ADFSTest.”
- Full connection name - The full connection name includes the connection name above, and is formatted as follows: SAML-<account id>-<connection name>
For example SAML-12345678-ADFSTest
The callback URL has this format:
https://<Login_Tenant_Domain>/login/callback?connection=<Full-Connection-Name>
Add your account ID, and choose from the list below the relevant domain according to your account’s location:
- Alpha - auth-z1-a.liveperson.net
- North America - auth-z1.liveperson.net
- Europe - auth-z2.liveperson.net
- Asia Pacific - auth-z3.liveperson.net
For example, if account 12345678 is in the North America region, this will be the full URL:
https:/auth-z1.liveperson.net/login/callback?connection=SAML-12345678-ADFSTest
Check Enable support for the SAML 2.0 WebSSO Protocol, and enter the service URL with the callback URL constructed above:
➡️ In the image above, account 81785735 in region Alpha and connection name ADFSTest are used.)
Configure identifiers
Enter the Full Connection Name as a “Relying party trust identifier.”
Choose access control policy
Choose the relevant Access Control Policy, or click Next to permit everyone:
Ready to add trust
Click Next.
Finish
Make sure Configure claims issuance policy for this application is checked, and click Close.
The Edit Claim Issuance Policy for your application dialog will open. (Minimize the console a bit to see it.)
Click Add Rule…
If the user name that corresponds to the “Login” value for users in the Conversational Cloud UI is defined in your LDAP, just press Next:
The user name should be sent to Liveperson in two fields:
- NameID
- an attribute called loginName (capital “N” important)
Choose the source of the username on the left (SAM-Account-Name, User-Principal-Name or any other), and on the right choose Name ID (notice the space):
Choose the same username source in the second line, and enter “loginName” for the outgoing claim:
Choose Active Directory for the Attribute store, click Finish, and then click OK:
In order to extract the signing certificate, navigate to AD FS → Service → Certificates.
Click on the Token-signing certificate, and choose View Certificate.
Click the Details tab, choose Copy To File, and save the certificate with any name in the Base64-encoded X.509 format.
In the Conversational Cloud UI, navigate to Management Console → Admin & Security → Account Access Control → Single Sign-On (SSO) Settings tab.
Click Add Connection, and choose “SAML.”
For Connection name, enter the connection name (not the full connection name) defined above (ADFSTest in our example).
Sign-in URL: https://<Your AD FS domain>/adfs/ls
For example: https://adfs.contoso.com/adfs/ls
Upload the signing certificate that was saved in the previous step, and click Create connection.
Logout and try to login again, this time by clicking the Continue with <Connection Name> button.
Appendix A - metadata.xml (optional)
Below is a template for metadata.xml.
If needed, edit the entityID and the Location fields.
For connection_name, use a string, such as “BrandNameSPtest,” but this string must be the connection name defined in the LivePerson Conversational Cloud UI configuration.
<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="SAML-<account id>-<connection name>" validUntil="2024-09-02T23:59:59.000Z">
<md:SPSSODescriptor WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat> <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://<Login_Tenant_Domain>/login/callback?connection=<Full_Connection_Name>" index="0" isDefault="true" />
</md:SPSSODescriptor>
</md:EntityDescriptor>