Account linking for Web Client and Facebook

You can let users on the Web Client (webchat) and Facebook channels log into their third-party account. The third-party system will authenticate their login credentials, and provide a login page.

Overview

You can use an interaction to prompt the user to log into a third-party account. The interaction for account linking needs:
  • The Requires account linking option to be set (on its Advanced tab)
  • An Link button that configures the URLs of the account linked login page and back-end instance.
The login page for account linking is displayed in a separate browser tab or pop-up window from the chat session. After successful authentication, Communicate will close the tab or pop-up window.

The bot will automatically parse the returned query string to extract the authorization code to use in subsequent API calls to the back-end system. For more information, see Using the returned authorization code.

The following diagrams provide an overview of the account linking process.

Account linking and the Web Client

Account linking and the Web Client

Account linking and Facebook Messenger

Account linking and Facebook Messenger

Setting up a login page for account linking

This section describes what is required on the account linked login page.

Note: For background information, see Account linking.

Required functions

You need to implement the following functions to:

  • Extract a given parameter from the current URL. The browser will use this to obtain the URL of the back-end instance. The instance URL is passed in the instance query parameter.
  • Perform an HTTP redirect to the Communicate authorize endpoint that will close the tab or pop-up after successful authentication, using the encoded redirect URL and the authorization code or token given by the back-end system.
  • Get the credentials entered by the user, and request authentication from the instance configured in the Account Link button.
Example

This example outlines how you might implement these functions. In this example <bot URL> is the URL of the server hosting the bot, such as https://designer.converse.pitneybowes.com.

<script >
function getParameterByName(name) {
	var match = RegExp('[?&]' + name + '=([^&]*)').
exec(window.location.search);
	return match && decodeURIComponent(match[1].
replace(/\+/g, ' '));
}

function doRedirect(authCode) {
	var uri = decodeURIComponent(getParameterByName
("redirect_uri"));
	window.location.replace("<bot URL>/authorize?
redirect_uri=" 
                                + encodeURI(uri + 
"&authorization_code=" + authCode));
}

function getAuthentication(){
        var body = {
            //get user credentials from login page
        }
        var url = getParameterByName("instance")

        //set up request etc
}
</script>

Using the returned authorization code

After a user successfully links their account on the Web Client or Facebook, an authorization code exists in the session.

EngageOne™ Communicate will assign the authorization code to a variable that is available in the context object:

  • authCode for single tokens
  • authCodeParts for multi-part tokens that are a string with the parts delimited with the | character.

The authorization should be passed in the body of REST API calls to the third-party system as shown below.

This example is for a system that authenticates using SAML SSO and returns a single key-value pair as a JSON object. Use it like this in the body of the REST API call:

{
   "saml": "{{authCode}}"
}

The following example is for a system that returns a multi-part token. Use it like this in the body of the REST API call:

{ 
    "my_auth_token": {{authCodeParts[0]}}
}

For REST API calls, you enter this as part of the Action interaction, in the Body field on the action's Settings tab.

Note: As an alternative to authCode or authCodeParts, you can create a custom variable to parse the returned authorization code or token. Use an Action interaction of type Set Variable.

Handling login page URLs containing request parameters

Note: This topic applies to channels such as Web Client and Facebook.
Third-party systems that use Auth0 for authentication will have a login page URL that contains request parameters. This section explains which parameters are supported by EngageOne™ Communicate and what the expected values should be. Here is an example of a login page URL for an Auth0 server:
https://designerui.converse.pitneybowes.com/?response_type=
code&client_id=123456789abcdefgh&state={sessionId}&
redirect_uri=https%3A%2F%2Fmycompany.com%2Fauthorize%2Fredirect

The request parameters are as follows:

Parameter Value Description
response_type code Communicate only supports the code grant type. It therefore expects that the response will include an authorization code. This parameter is always:

response_type=code
client_id Auth0 client ID The ID configured in your Auth0 implementation. For example: client_id=123456789abcdefgh
state {sessionId} The session ID set by Communicate and used to identify the session. This is returned to Communicate as part of the redirect_uri. This parameter is always:

state={sessionId}
redirect_uri Redirect URL in encoded format The redirect URL is:

https://<your hostname>/authorize/redirect

It needs to be in an encoded format. For example: 
redirect_uri=https%3A%2
F%2Fmycompany.com
%2Fauthorize%2Fredirect

See also Session details.