Authenticated Visitors (Non-MS Portals)

You can set up an engagement to pass contact information from an existing CRM record to an Agent when the visitor is authenticated.

High-Level Sequence

1. The user must authenticate against your Web Service.
2. Your web application must query your CRM instance and determine the Contact GUID.
3. Your web application must build and sign a JsonWebToken.
4. The JWT must be available in your visitor's browser.
5. When the user clicks engage a chat initiates.
6. Live Assist calls a named method to retrieve the JWT to retrieve the participant's GUID
7. Live Assist contacts the CRM with the participant's GUID
8. When the Agent accepts the chat, can pop the correct contact record.

Preparing your Web Application

To prepare your Web Application to build an OAuth Token:

1. Generate an RS256 public and private key pair.
   • These are used to build the JWT that Live Assist receives.

     Important: Live Assist only supports RS256 signed JWTs.

     
     

     openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048
     openssl rsa -pubout -in private_key.pem -out public_key.pem

Setting up Live Assist for Authenticated Chats

Log in to the Engagement Portal and navigate to the Campaign Builder.  Beneath the campaigns list, you will see a paragraph containing several hyperlinks.  Click on the link labeled "Data Sources".

You'll need to configure the Authenticated Server, so click on the "Integrations" tab and "Configure" button next to 'Consumer Identity Providers'.

The Customer Portal uses the Implicit oAuth 2.0 authentication type, so select this item from the radio button list.

This will reveal some additional fields that you'll need to specify. Live Assist needs the following configuration:

Configure your site to pass the customer identity to the Live Assist API (Messaging platform only)

To enable targeting for the engagement, your site or application must pass the customer identity to the API using the identities array and identify function. The information in this array should match the values assigned to the user when they authenticate on your site or application. This is not used for visitor authentication, but as a trigger for Live Assist monitoring services to start targeting and sending relevant engagements and/or notifications to the visitor.

To do this, add the following javascript snippet to all of the web pages that contain your Live Assist tag or to the application. For best performance, add this close to the Live Assist tag snippet in your code. 

<scripttype="text/javascript">
lpTag.identities=[];
lpTag.identities.push(identityFn);
function identityFn(callback) {
    callback({
        iss: “ replace with issuer ”,
        acr: “loa1”,
        sub: “ replace with customerID ”
    });
}
</script>

Important: Please pay close attention in the snippet to what you need to replace with your own information. (See "iss" and "sub" in the code.)

Building the JWT

Your application must produce a signed JsonWebToken (JWT) that contains the GUID of the Contact Record for the authenticated visitor. Live Assist will retrieve the JWT from the client and use it to retrieve the GUID.

To build and sign the JWT your web application must perform the following:

1. Find the appropriate GUID stored on the Contacts Table within your CRM.
   

   Important: Your web application must manage this process and it is outside of the scope of this guide to provide steps retrieving the information from the CRM.

2. Your web application must construct a JSON payload, substituting the GUID, as follows:
   

    payload = { 
       "sub" : "36-Character-Hyphenated-Contact-GUID",
       "given_name" : "Contact's first Name",
       "family_name" : "Contact's family Name",
       "iss" : "FQDN of your website",
       "iat" : DateTime.now.strftime('%Q').to_i / 1000,
       "exp": (DateTime.now.strftime('%Q').to_i + 7200) / 1000
    }
   

   Note: The iat and exp claims are required to be in seconds rather than milliseconds. They should also be provided as numbers and NOT as strings (in quotes).

3.  Your application must build the JWT. 
   For example, if your web application is Ruby the code may do the following:
   

   private_key_file = 'private.pem';
   @my_payload = payload;
   @private_key = OpenSSL::PKey::RSA.new(File.read(private_key_file))
   
   //Use a jwt library from https://jwt.io/ to encode the GUID payload
   //For example: gem install jwt
   @token = JWT.encode @my_payload, @private_key, 'RS256'
   

4. Your application must pass this token to the participant's client application.
   

   Note: Performing this step is outside of the scope of the article.

Client application code

Browser or Javascript Clients

function authoriseChatWithCallback(callback) 
{
    console.log("Get JWT");
    try
    {
        console.log("JWT from Web Application: " + "<YOUR JWT STRING>");
        callback("<JWT STRING HERE>");
    }
    catch (e)
    {
        console.error(e);
        callback(null, "Unable to generate key");
    }
};

Troubleshooting

The two most common issues are related to the JWT format and the correct use of the Public key. If authentication is not working correctly you can test the JWT in the following ways:

1. On the web page, the chat will be taken from login ready to start an authenticated chat.
2. Right-click anyway on the page and select Inspect to open the Chrome dev tools.
3. Call the defined JS Method Name outputting the content to console. In our example authoriseChatWithCallback(console.log
   
4. Go to the website https://jwt.io  and in the debugger section select  Algorithm RS256.
5. Copy the output of the JWT from point 3 into the Encoded panel on the https://jwt.io  website ensuring no metadata is attached (e.g date or file stamps)
6. You will see the plain text payload data in one of the right-hand panels. Ensure it is the exact format as discusses in point 2 of the Building the JWT section above.
7. To ensure the JWT is valid from the point of view of your configuration take the single line JWT Public Key you added to the engagement portal and put it between BEGIN and END PUBLIC KEY tags and overwrite the default public key on the https://jwt.io page. If valid the JWT will be marked as  Signature Verified
   
   

iOS Clients

If you are following Live Assist for 365 and iOS SDK, the method name is: authoriseChatWithCallback.

The authString attribute requires your visitor's JWT.

For a partial implementation see: iOS Authenticated Chat Example

Android Clients

If you are following Live Assist for 365 Android SDK, the method name is: authoriseChatWithCallback.

The jwt attribute requires your visitor's JWT.

For a partial implementation see: Android Authenticated Chat Example

Agent Pop-out