JWT Authentication

Custom Authentication

The Custom JWT authentication provider allows users to authenticate with an authentication system that is independent from Pingstreams. The external system must return a signed JSON Web Token that contains a unique ID value for the authenticated user.

Pingstreams uses the JWT to identify your application’s users and authenticate their requests but does not impose any restrictions on the external authentication system’s requirements or authentication methods.

To create a Custom JWT Token you must generate a Project Shared Secret as described below.

Note

We provide a full tutorial on Custom Authentication.

Generating a Project Shared Secret

A Project Shared Secret is a security setting, intended to be generated, copied, and pasted into a communication with your engineering team, or directly into your codebase, in a single sitting. It should not be entered into a browser.

To generate the shared secret required for custom authentication you need:

1. Open the Dashboard and go to Project Name > Project Settings.
2. Go to the Visitor Authentication tab and click the Generate button.

Caution

The shared secret is intended to remain secure. As a result, it will only appear in full one time. If you don’t have access to the shared secret and need the full secret to create your token, you can reset the secret by clicking the ‘Generate’ button. Regenerating a new shared secret will revoke the previous token. If you have concerns the shared secret has been compromised, you should regenerate a new one. If you need to rotate the keys, you should schedule it when Chat is offline because regenerating the secret cause visitors to be disconnected from the widget.

Create a Pingstreams JWT token

To create a JWT token you must set the following required fields of the user object:

• _id is the custom unique user identifier of the external authentication system. It must start with <YOUR_PROJECT_ID>_ (example: 5e5f4e220b28440012117be4_12345678)
• sub JWTs describe their subject in the sub claim. For custom authentication sub field must be equal to value userexternal
• aud JWTs describe their audience in the aud claim. For custom authentication must be https://pingstreams.com/projects/<YOUR_PROJECT_ID> whether you use the cloud version of Pingstreams or if you install it on-premise.
• email It’s the user email

Optional fields:

• firstname It’s the user firstname
• lastname It’s the user lastname
• attributes other custom jwt claims.

The external authentication system must create the JWT signing the user object with the Project Shared Secret code.

User object example:

{
  "_id": "5e5f4e220b28440012117be4_12345678",
  "firstname": "Andrea",
  "lastname": "Leo",
  "email": "user@example.com",
  "attributes": {
    "attribute1": "value"
  },
  "sub": "userexternal",
  "aud": "https://pingstreams.com/projects/5c81593adf767b0017d1aa68"
}

Generate JWT Token Server Side

Find the template below that fits your language needs. Customize the sample as needed, making sure to replace the #{details} placeholders with your own information.

If none of these samples match your needs, JWT has a more extensive list of JWT libraries to explore.

NodeJS

Install jsonwebtoken:

npm install jsonwebtoken --save-dev

Then, generate a token using the shared secret:

var jwt = require('jsonwebtoken');
var payload = {
  _id: '#{customerIdentifier}',
  firstname: '#{customerFirstname}',
  lastname: '#{customerLastname}',
  email: '#{customerEmail}',
  sub: 'userexternal',
  aud: 'https://pingstreams.com/projects/#{YOUR_PROJECT_ID}',
};
var token = jwt.sign(payload, '#{yourProjectSharedSecret}');

You can find a NodeJs Custom Jwt Authentication example here.

PHP

Download PHP-JWT:

composer require firebase/php-jwt

Generate a token using the shared secret:

$payload = {
  '_id' => '#{customerIdentifier}',
  'firstname' => '#{customerFirstname}',
  'lastname' => '#{customerLastname}',
  'email' => '#{customerEmail}',
  'sub' => 'userexternal',
  'aud' => 'https://pingstreams.com/projects/#{YOUR_PROJECT_ID}'
};
$token = JWT::encode($payload, '#{yourProjectSharedSecret}');

Java

Authentication with Java is covered with a simple Java (Maven) example on the public repo PingstreamsJavaJWTSign

We use the JJWT library to implement the Pingstreams JWT sign operation.

SignatureAlgorithm signatureAlgorithm = SignatureAlgorithm.HS256;
long nowMillis = System.currentTimeMillis();
Date now = new Date(nowMillis);
byte[] apiKeySecretBytes;
apiKeySecretBytes = SECRET_KEY.getBytes();
Key signingKey = new SecretKeySpec(apiKeySecretBytes, signatureAlgorithm.getJcaName());
JwtBuilder builder = Jwts.builder().setId(id)
    .setIssuedAt(now)
    .setSubject(subject)
    .setIssuer(issuer)
    .claim("firstname", firstname)
    .claim("lastname", lastname)
    .claim("email", email)
    .signWith(signingKey, signatureAlgorithm);
return builder.compact();

Please refer to the above mentioned repo for further details.

Verify the token

You can verify the JWT token using jwt.io following these steps:

1. Paste the secret code
2. Paste the jwt code in the left column
3. Check the “Signature Verified” label

Widget Authentication

See how to setup custom authentication for the widget using the JWT token.