Access control & data security

Authentication and authorization mechanisms in your chat app let you decide who can access what resources based on identity and permissions.

Additonal security measures let you send and receive messages and files through your chat app, preventing unauthorized users from accessing that data.

User authentication

In your chat app, you need to have a process of verifying the identity of all users, ensuring that they are who they claim to be.

Chat SDK doesn't provide a built-in authentication mechanism, and you'll need to implement user verification in your app on your own. Typically, this could involve a login system where users provide their credentials (username and password), token-based authentication, Single Sign-On (SSO), two-factor authentication (2FA), or external authentication services like OAuth.

User authorization

A chat app will require an authorization mechanism granting or denying access to specific PubNub resources or functionalities based on the authenticated user's permissions and privileges.

This way, you don't let your chat users delete or modify each other's metadata, publish messages on private channels, or remove messages that other chat members wrote.

Chat SDK provides authorization in your chat app through Access Manager - a secure, token-based permission administrator that lets you regulate clients' access to such PubNub resources as channels and users. By making a single call to Access Manager API, you can define multiple user permissions saying who can do what with your client or server app data.

Depending on whether you create a client or server app, there are three possible actors involved in the authorization cycle: PubNub (server), your own server, and a client device. For more details, read the authorization workflow.

Enable Access Manager

Access Manager is not enabled by default. To use it in your app, you must allow it on your app's keyset in the Admin Portal and then initialize the Chat SDK with secretKey.

Data security

Chat SDK lets you fully encrypt and decrypt all messages and files on all channels in your chat app through the PubNub server using the AES-CBC 256-bit (CBC block cipher mode) encryption module.

Limited framework support

AES-CBC 256-bit crypto module is designed and intended to work with web applications and Node.js. However, it is not compatible with React Native.

To secure your chat app data with the crypto module, specify and register the crypto module as part of the PubNub configuration when you create a Chat SDK instance:

  1. Import CryptoModule from @pubnub/chat.
  2. Add the cryptoModule parameter to your configuration.
  3. Specify a cipherKey that will be used to encrypt/decrypt all messages and files in your app across all client devices.
// you need to import CryptoModule
import {Chat, CryptoModule} from "@pubnub/chat"

const chat = Chat.init({
publishKey: "demo",
subscribeKey: "demo",
userId: "myUniqueUserId",
cryptoModule: CryptoModule.aesCbcCryptoModule({cipherKey: "pubnubEnigma"})

Once you registered a crypto module in the configuration, you don't have to explicitly specify it in any method as they are automatically added to methods when:

  • Encrypting messages with files when they are sent (sendText()).
  • Decrypting messages with files both when they are received (connect()) and retrieved from history (getHistory()).

The Chat SDK automatically encrypts message and file data before it's uploaded to the storage service. The receiving client decrypts the data upon receiving it using the same key before it is displayed in the end-user application.

If you didn't use the correct cipher key to decrypt the message (for example, you changed the encryption cipher key), you'll get an Error while decrypting message content: {details} error. This error is added as a value to the error field in the received message instance.

In such cases, you can do the following:

  • Manually decrypt the message or file using our decrypt() utility method and the original cipher key that you used to encrypt the message.
  • Set an error fallback message shown to the end-users each time the message cannot be decrypted (otherwise, end-users will see a human-unreadable string instead of a message).
// assuming the CryptoUtils class and its decrypt method are defined

// sample history of messages with potential decryption errors
const undecryptedMessages = /* ... */; // provide the undecrypted messages here

// fallback mechanism for undecrypted messages
const decryptedMessagesWithFallback = => {
if (msg.error && msg.error.startsWith("Error while decrypting message content")) {
// fallback for undecrypted messages
return {
type: "text",
files: [],
text: "(This message is corrupted or could not be decrypted)",
show all 22 lines

For a general overview of PubNub encryption/decryption concepts, refer to Message encryption, File encryption, and JavaScript SDK crypto module.

Last updated on