Skip to content

Integrating Authentication with Pleased Chat Widget ​

This user documentation provides instructions on integrating authentication with the Pleased chat widget using a public key (spki) provided by Pleased. The integration involves setting up a backend API to generate a JWE token using the provided public key and configuring the frontend to handle the authentication flow.

Step 1: Obtain Public Key (spki) from Pleased ​

To obtain the spki public key required for authentication integration, go to Settings / Channels / Chat Widget Setup / Widget Authentication. On this page, click the Reveal button to display the key. Although the key is named "public," it must be stored and used on your backend only and must NEVER be embedded in client-side code. If the key has been compromised, you can generate a new one on the same page. After you generate a new key, the old one stops working immediately. Update the key everywhere it was used before your integration will work again.

Step 2: Setup Backend API ​

To generate the JWE token, follow these steps:

2.1 Backend API Route ​

Set up a backend API route that will handle token generation. The route will receive requests from the frontend to generate a JWE token.

2.2 Token Generation Function ​

Inside the API route, implement a function to generate the JWE token using the provided spki public key and the specified encryption algorithm ("RSA-OAEP-256") and content encryption algorithm ("A128GCM").

Java Example (The following java example uses Nimbus JOSE + JWT to complete the integration):

java
import java.security.KeyFactory;
import java.security.NoSuchAlgorithmException;
import java.security.interfaces.RSAPublicKey;
import java.security.spec.InvalidKeySpecException;
import java.security.spec.X509EncodedKeySpec;


import com.nimbusds.jwt.EncryptedJWT;
import com.nimbusds.jwt.JWTClaimsSet;
import com.nimbusds.jose.EncryptionMethod;
import com.nimbusds.jose.JOSEException;
import com.nimbusds.jose.JWEAlgorithm;
import com.nimbusds.jose.crypto.RSAEncrypter;

import java.time.LocalDateTime;
import java.time.ZoneOffset;

private String buildJweToken(String publicKey) throws JOSEException, NoSuchAlgorithmException, InvalidKeySpecException {
   JWTClaimsSet claims = new JWTClaimsSet.Builder()
       // Please ensure minimum 2 hours expiry from the time of creation for production purposes
       .expirationTime(new Date(LocalDateTime.of(2100,12,31,0,0,0)
               .toInstant(ZoneOffset.UTC).toEpochMilli()))
       .claim("email", "test@user.temo")
       .claim("userId", "client-user-id")
       .claim("phone", "1-X-XXXXXXX-user-phone")
       .claim("name", "Test user")
       // All of the above claim fields are optional.
       .build();

   JWEHeader header = new JWEHeader(JWEAlgorithm.RSA_OAEP_256, EncryptionMethod.A128GCM);
   EncryptedJWT jwt = new EncryptedJWT(header, claims);
   RSAEncrypter encrypter = new RSAEncrypter((RSAPublicKey) loadPublicKey(publicKey));
   jwt.encrypt(encrypter);
   return jwt.serialize();
}

private PublicKey loadPublicKey(String publicKey) throws NoSuchAlgorithmException, InvalidKeySpecException {
    byte[] rsaKey = Base64.getDecoder().decode(publicKey);
    X509EncodedKeySpec spec = new X509EncodedKeySpec(rsaKey);
    KeyFactory kf = KeyFactory.getInstance("RSA");
    return kf.generatePublic(spec);
}

Step 3: Configure Frontend ​

Configure the frontend to call the Pleased JavaScript function pLS('set:callback') with a token generation function that calls the backend API to generate the token. You can learn more about this command and the available authentication options on the Authentication in Pleased Widget page.