End-user Authentication

Learn about end-user authentication using JWT, as well as moving between unauthenticated and authenticated conversation

An authenticated conversation has a number of advantages over an unauthenticated one. It gives the agents the benefit of additional context about a user's ongoing conversations and relationship with the brand.

Likewise, it allows the end-user to continue conversations started on other devices without missing any key information that was already relayed during the conversation on another device.

Unauthenticated conversations benefit from being able to occur at any time with any visitor of the website. It's a useful tool for sales where you are onboarding new customers and telling them about products or services before they take the step to make a purchase or sign up.

If your brand requires end-users to be authenticated in order to initiate conversations using Modern Chat, you will need to go through the process of passing a JSON Web Token (JWT) and the user's unique ID within your system of record.

📘

The unique user ID used for end-user authentication should be the same as the unique user ID used for end-user authentication in a native app using the Brand Messenger Legacy's iOS or Android SDKs. This ID must be immutable and should contain no personally identifiable information.

❗️

The JWT consists of a header, payload, and signature. You'll need your Brand Messenger Legacy App Key ID and App Key Secret. Contact Khoros Support for these credentials if you do not have them.

Create a JWT

A JWT can be generated using the methods described in this section.

Important: The token must be generated server-side! This should never be present in the browser because the key_id and secret are extremely sensitive information. In the event that a key_id and secret are exposed, you must contact Khoros Support to generate new ones, and update your backend systems to utilize the new credentials.

In each example:

  • Set the scope to appUser
  • Replace THEIR_USER_ID with the ID of the end user to authenticate
  • Replace KEY_ID with your App Key ID
  • Replace SECRET with your app Key Secret

To authenticate, pass the JWT with your calls to the Brand Messenger Legacy Modern Chat API.

Python

import jwt
token = jwt.encode({'scope': 'appUser', 'userId':'THEIR_USER_ID'}, SECRET, algorithm='HS256', headers={'kid': KEY_ID})

Java

import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import io.jsonwebtoken.impl.crypto.MacProvider;
import io.jsonwebtoken.security.Keys;

import static io.jsonwebtoken.JwsHeader.KEY_ID;

// ...

String jwt = Jwts.builder()
    .claim("scope", "appUser").claim("userId", "THEIR_USER_ID")
    .setHeaderParam(KEY_ID, "KEY_ID")
    .signWith(
        Keys.hmacShaKeyFor("SECRET".getBytes()),
        SignatureAlgorithm.HS256
    )
    .compact();

.NET

The following examples have been tested on macOS Mojave and Windows 10.

Example GenerateJwtShort.cs

using System;
using JWT.Builder;
using JWT.Algorithms;

// ... namespace and class ... //
static void Main(string[] args)
{
    var kid = "<application key id>";
    var secret = "<application secret>";
    var userId = "<user SSO id>";

    var token = new JwtBuilder()
            .WithAlgorithm(new HMACSHA256Algorithm())
            .WithSecret(secret)
            .AddHeader(HeaderName.KeyId, kid)
            .AddClaim("scope", "appUser")
            .AddClaim("userId", userId)
            .Encode();

    Console.WriteLine(token);
    // Render an HTML page with the JWT and userId 
    // embedded for use with window.KHOROS_CONFIG
}

Example GenerateJwt.csproj

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="JWT" Version="5.3.1" />
  </ItemGroup>

</Project>

Moving from Unauthenticated to Authenticated During a Conversation

login logs a user in Modern Chat, retrieving the conversation the user already had on other browsers and/or devices.

Here is an example:

Brandmessenger.login('userId', 'jwt');

📘

You don't need to call this after init if you passed the user ID and JWT already, it's done internally. This returns a JavaScript Promise object that resolves when the Web Messenger is ready again.

If a conversation is already in progress, the conversation will continue without any changes for the end-user. For the agent, the end-user's name and other information will update with the authenticated identity.