Access control & data security

Control who can access resources in your chat app through authentication (identity verification) and authorization (permission management).

Required keyset configuration

To use the getChannels(), getChannelSuggestions(), getUsers(), and getUserSuggestions() methods in the Chat SDKs with Access Manager, you must uncheck the Disallow Get All Channel Metadata and Disallow Get All User Metadata checkboxes in the App Context section of your keyset configuration in the Admin Portal.

User authentication

Authentication verifies user identity. The Chat SDK does not include built-in authentication. Implement your own system using:

• Username/password login
• Token-based authentication
• Single Sign-On (SSO)
• Two-factor authentication (2FA)
• OAuth or external identity providers

User authorization

Authorization controls what authenticated users can do. Use Access Manager to:

• Grant or deny access to channels and users
• Define permissions for reading, writing, and managing data
• Protect private channels and user metadata

For details on client-server-PubNub interactions, see the authorization workflow.

Enable Access Manager

Enable Access Manager on your keyset in the Admin Portal and initialize the Chat SDK with secretKey (server-side) or authKey (client-side).

Data security

Encrypt messages and files using AES-CBC 256-bit encryption (CBC block cipher mode).

Platform support

The crypto module works with web applications and Node.js. React Native is not supported.

Enable encryption

1. Import CryptoModule from @pubnub/chat
2. Add cryptoModule to your configuration
3. Set a cipherKey for encryption/decryption

1// you need to import CryptoModule
2import {Chat, CryptoModule} from "@pubnub/chat"
3

4const chat = Chat.init({
5    publishKey: "demo",
6    subscribeKey: "demo",
7    userId: "myUniqueUserId",
8    cryptoModule: CryptoModule.aesCbcCryptoModule({cipherKey: "pubnubEnigma"})
9})

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).

1// assuming the CryptoUtils class and its decrypt method are defined
2

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

6// fallback mechanism for undecrypted messages
7const decryptedMessagesWithFallback = undecryptedMessages.map((msg) => {
8  if (msg.error && msg.error.startsWith("Error while decrypting message content")) {
9    // fallback for undecrypted messages
10    return {
11      type: "text",
12      files: [],
13      text: "(This message is corrupted or could not be decrypted)",
14    };
15  }
16

17  // message is not undecrypted, return as is
18  return msg;
19});
20

21// use decryptedMessagesWithFallback as needed
22console.log(decryptedMessagesWithFallback);

show all 22 lines

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

Operations-to-permissions mapping

The type of access level you grant on a given resource type defines which operations users can perform in your app. For example, write access given to a user for the channels resource type (either specific channels or channel patterns) lets them send messages to this channel/these channels (calling the PubNub Pub/Sub API underneath and the Chat SDK's SendText() method).

Chat SDK method to required Access Manager permission mapping

For information about which Chat SDK methods require what Access Manager permissions, refer to Security and permissions.