Managing User Permissions

PubNub Access Manager (PAM) allows you to enforce secure controls for client access to resources within the PubNub Data Stream Network. With PAM, your servers can grant clients access to individual PubNub resources (channels and channel groups) on a token for a limited duration, with the ability to extend access or add permissions for additional resources.

If Access Manager is enabled on your key set, you need to grant permissions to clients so they can access PubNub APIs. An admin server with secretKey access can grant permissions for object resources using the grant API. You can grant clients access to all resources, or to a limited set of resources, depending on your application logic.

Tip

Enable Access Manager from the Admin Portal. For more details on working with Access Manager, refer to the Access Manager tutorial.

Authorization Flow

Object model diagram

The authorization flow is as follows:

  1. The server issues a PAM grant to allow privileges based on a custom authKey.
  2. The client application requests authorization from the server.
  3. The server sends an authKey to the client application.
  4. The client application sets PubNub credentials with that authKey.
  5. Thereafter, PubNub verifies the client permissions on all API calls from the client.

Connecting from a server

A server can connect to PubNub in admin mode by including the secretKey when it initializes the PubNub object. In admin mode, the server has access to all channels forever. Once connected, you can perform Grant and Revoke operations to manage channel permissions for users.

Warning

Anyone with the secret key can grant and revoke permissions to your app. Never let your secret key be discovered, and only exchange and deliver it securely. Only use the secret key on secure environments, such as Node.js applications or other server-side platforms.

Obtain your secret key from the Admin Portal.

Granting permissions

The server can grant a user read/write privileges for multiple channels or channel groups with a particular authKey. Since you can't publish on channel groups, you can't grant write permission on a channel group. The read permission on a channel group overrides the read permissions of the underlying channels.

Wildcard Grants

Wildcard notation makes granting access on multiple channels more efficient. You can go one level deep using wildcards. In other words:

Specifying a.* grants access on all channels that begin with a..

Specifying a.b.* doesn't work. If you grant on a.b.*, the grant treats a.b.* as a channel name, not a wildcard.

The request below grant read and write permission to the chats.room1 and chats.room2 channels:

pubnub.grant(
  {
    "channels": ["chats.room1", "chats.room2"],
    "authKeys": ["myAuthKey"],
    "ttl": 1440,
    "read": true,
    "write": true
  },
  function (status) {
    console.log(status);
  }
);

Grant read and write permission to the chats.room1 and chats.room2 channels:

pubnub.grant()
  .channels(Arrays.asList("chats.room1", "chats.room2"))
  .authKeys(Arrays.asList("myAuthKey"))
  .write(true)
  .read(true)
  .ttl(1440)
  .async(new PNCallback<PNAccessManagerGrantResult>() {
    @Override
    public void onResponse(PNAccessManagerGrantResult result, PNStatus status) {
      System.out.println(result);
      System.out.println(status);
    }
  });

Grant read and write permission to the chatroom channels:

pubnub.Grant()
  .Channels(new string[]{"chats.room1", "chats.room2"})
  .AuthKeys(new string[] {"myAuthKey"})
  .Write(true)
  .Read(true)
  .TTL(1440)
  .Execute(new PNAccessManagerGrantResultExt(
    (result, status) => {
      // handle result/status
    }
  ));

Grant read and write permission to the chatroom channels:

pubnub.grant()\
  .channels(["chats.room1", "chats.room2"])\
  .auth_keys(["myAuthKey"])\
  .read(True)
  .write(True)\
  .sync()

Grant read and write permission to the chatroom channels:

res, status, err := pn.Grant()
  .Channels([]string{"chats.room1", "chats.room2"})
  .Read(true)
  .Write(true)
  .AuthKeys([]string{"myAuthKey"})
  .TTL(1440)
  .Execute()

fmt.Println(res, status, err)

Revoking permissions

To revoke permissions for one or more users, call the Grant method and set the appropriate permissions to false.

pubnub.grant({
  channels: ['chats.room1'],
  channelGroups: ['cg_user123']
  authKeys: [authKey],
  read: false, // false to disallow
  write: false, // false to disallow
}, (status) => {
  // handle status
});
pubnub.grant()
  .channels(Arrays.asList("chats.room1", "chats.room2"))
  .channelGroups(Arrays.asList("cg_user123"))
  .authKeys(Arrays.asList(authKey))
  .write(false) // prevent those keys from writing
  .read(false) // prevent those keys from reading the subscribed feed
  .async(new PNCallback<PNAccessManagerGrantResult>() {
    @Override
    public void onResponse(PNAccessManagerGrantResult result, PNStatus status) {
      // PNAccessManagerGrantResult is a parsed and abstracted response from server
    }
  });
pubnub.Grant()
  .Channels(new string[]{ "chats.room1", "chats.room2" })
  .ChannelGroups(new string[]{ "cg_user123" })
  .AuthKeys(new string[] { authKey })
  .Write(false) // prevent those keys from writing
  .Read(false) // prevent those keys from reading the subscribed feed
  .Execute(new PNAccessManagerGrantResultExt(
    (result, status) => {
      // PNAccessManagerGrantResult is a parsed and abstracted response from server
    }
  ));
pubnub.grant()\
  .channels(["chats.room1", "chats.room2"])\
  .channel_groups(["cg_user123"])\
  .auth_keys([authKey])\
  .read(False)\
  .write(False)\
  .sync()
res, status, err := pn.Grant()
  .Channels([]string{"chats.room1", "chats.room2"})
  .ChannelGroups([]string{"cg_user123"})
  .AuthKeys([]string{authKey})
  .Read(false)
  .Write(false)
  .Execute()

fmt.Println(res, status, err)

Client-side Operations

If Access Manager is enabled on your key set, all users need to provide a valid authKey to subscribe to channels and channel groups. The auth key can be a random string generated and managed by your server. It can also be a UUID, or an authentication token from OAuth, Facebook Connect, or another authentication service.

Don't share auth keys between users if you need to manage separate access for individual users, or if you need to revoke access for a single user.

To learn more about key management, including auth keys and API keys, refer to the appropriate design pattern.

←Managing UsersUser Presence→