Permission Management v2

Access Manager v3

This document describes Access Manager v2 that will soon be deprecated in favor of v3. To read more about Access Manager v3, read the documentation. To upgrade from v2 to v3, see the Migration Guide.

Access Manager v2 allows you to enforce secure controls for client access to resources within the PubNub network. With Access Manager, your servers can grant their clients access to individual PubNub resources for a limited duration, with the ability to extend access or add permissions for additional resources.

With Access Manager enabled, your clients must have permissions to send requests to PubNub. You can grant access to your clients from a secure server using the secretKey. These grants allow you to granularly manage the resources available to each client. For instance, you can make a one-to-one chat room private by only allowing the two users in that chat room to have read and write permissions on the chat room channel. Alternatively, you can make a channel public by allowing all users to have access to it.

Enable the Feature

Access Manager is an optional feature that can be enabled from the Admin Portal.

Authorization Flow

There are three actors involved when working with Access Manager: your server, the PubNub Platform, and client devices. The authorization flow is as follows:

  1. The client application requests authorization from the server during the login process.
  2. Your server issues a grant to allow privileges based on an authKey for the client.
  3. The client application sets PubNub credentials with that authKey and passes it to PubNub to perform API operations.

Client Devices → Your Server → PN Network ← Client Devices

Login

Your server provides a means for clients to log in. When a device is successfully authenticated, the server generates an authKey for that client.

Clients (login) → Your Server (authenticate client

Grant

Your server makes a grant call towards PubNub on that authKey with the list of resources and ttl (time to live) for the grant. Once the grant is successful, the server responds to the client device's authentication request with this authKey.

Your Server (grant permissions) → PN Network (store permissions

PubNub API Request

The client device initializes the PubNub object with the publish and subscribe keys, and the provided authKey. The client receives the authKey from the login request.

Client (PN API requests) → PN Network (validate permissions

Permissions

Access Manager allows permissions to be granted or revoked for the following PubNub resources. There are certain permission flags that are allowed for each resource.

ResourceAvailable Permissions
Channelread, write, delete, get, update, manage, join
Channel Groupread, manage
UUIDget, update, delete

Operations to Permissions Mapping

The following tables show the mappings of API operations to resources and permissions.

Publish/Subscribe

PubNub OperationResourcePermission
Publish on channelChannelWrite
Signal on channelChannelWrite
Subscribe to channelChannelRead
Subscribe to presence channelPresence Channel (-pnpres)Read
Subscribe to channel groupChannel GroupRead
Subscribe to presence channel groupPresence Channel Group (-pnpres)Read
Unsubscribe from channelChannelNone required
Unsubscribe from channel groupChannel GroupNone required

Presence

PubNub OperationResourcePermission
Here NowChannelRead
Where NowChannelnone required
Get StateChannelRead
Set StateChannelRead

Storage

PubNub OperationResourcePermission
History - Fetch MessagesChannelRead
Message CountsChannelRead
Delete MessagesChannelDelete

Files

PubNub OperationResourcePermission
Send file on channelChannelWrite
List filesChannelRead
Download fileChannelRead
Delete fileChannelDelete

Channel Groups

PubNub OperationResourcePermission
Add Channels to channel groupChannel GroupManage
Remove Channels from channel groupChannel GroupManage
List Channels in channel groupChannel GroupManage
Remove channel groupChannel GroupManage
Channel Groups

Channel Groups should only be managed by a secure server, which already has the secret key giving it all permissions on all resources. The only exception might be a client app that acts as an administrator, where that user is manually managing channel groups for other client users.

Objects

PubNub OperationResourcePermission
Set user metadataUUIDUpdate
Delete user metadataUUIDDelete
Get user metadataUUIDGet
Get all user metadataUUIDManaged by a flag on the settings page.
Set channel metadataChannelUpdate
Delete channel metadataChannelDelete
Get channel metadataChannelGet
Get all channel metadataChannelManaged by a flag on the settings page.
Set channel membersChannelManage
Remove channel membersChannelDelete
Get channel membersChannelGet
Set channel membershipsChannel, UUIDChannels: Join
UUID: Update
Remove channel membershipsChannel, UUIDChannels: Join
UUID: Update
Get channel membershipsUUIDGet

Push Notifications

PubNub OperationResourcePermission
Register channel for pushChannelRead
Remove channel's push registrationChannelRead

Message Actions

PubNub OperationResourcePermission
Add Message ActionChannelWrite
Remove Message ActionChannelDelete
Get Message ActionsChannelRead
Get History with ActionsChannelRead

Server-side Operations

To perform grants, your server must first initialize a PubNub object using the secretKey and the publish and subscribe keys.

Initialize with secretKey

The secretKey lets you use the Grant API to grant clients access to PubNub resources. When you initialize PubNub with the secretKey, you get root permissions for the Access Manager. With this feature you don't have to grant access to your servers to access channel data. The servers get all access on all resources.

Secret Key Security

The secret key should only be used within a secure server and never exposed to client devices. If the secret key is ever compromised, it can be an extreme security risk to your application. If you suspect your secret key has been compromised, you have the ability to regenerate a new secret key for the existing PubNub keys set.

var pubnub = new PubNub({
publishKey: 'myPublishKey',
subscribeKey: 'mySubscribeKey',
secretKey: 'mySecretKey',
uuid: 'theServerUUID'
})

Grant Permissions

Use the grant method to grant permissions on authKeys for one or more resources. You may need to make multiple grant calls for one authKey so that you can specify explicit permissions for each channel or channel group resources, but common permissions can be granted to a list of channels and channel groups in a single request.

The ttl parameter is the number of minutes before the granted permissions expire, at which point the client will have to request to be re-granted further access (always generate a new authKey when you extend the permissions). The default is 1440 minutes, which is 24 hours.

Wildcard grants

Wildcard notation allows you to grant permissions to multiple channels at a time and later revoke these permissions in the same manner. You can go one level deep using wildcards. In other words:

  • a.* grants access on all channels that begin with a..
  • * or a.b.* won't work this way. If you grant on * or a.b.*, the grant treats * or a.b.* as a channel name, not a wildcard.

The request below grants read and write permission to the authentication key myAuthKey for 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);
}
);

The request below grants the read permission to the authentication key myAuthKey for alerts.* channels using wildcards and to the cg_user123 channel group:

pubnub.grant(
{
channels: ["alerts.*"],
channelGroups: ["cg_user123"],
authKeys: ["myAuthKey"],
ttl: 1440,
read: true
},
function (status) {
console.log(status);
}
);

The request below grants get, update and delete permission to the authentication key myAuthKey for uuid1. Note that you must send UUID grants in separate requests than channel and channel group grants.

pubnub.grant(
{
uuids: ["uuid1"],
authKeys: ["myAuthKey"],
ttl: 1440, // 0 for infinite
get: true, // false to disallow
update: true, // false to disallow
delete: true // false to disallow
},
function (status) {
console.log(status);
}
);

Revoke Permissions

To revoke permissions, use the grant method with resource permissions set to false. The ttl parameter is not applicable and if a resource does not have a permission, it is ignored.

Wildcard revokes

You can revoke permissions from multiple channels using wildcards only if you previously granted permissions using the same wildcards. Wildcard revokes, similarly to grants, only work one level deep, like a.*.

The request below revokes read and write permission from chats.room1 and chats.room2 channels and cg_user123 channel group:

pubnub.grant({
channels: ["chats.room1"],
channelGroups: ["cg_user123"]
authKeys: ["myAuthKey"],
read: false, // false to disallow
write: false, // false to disallow
}, (status) => {
// handle status
});

Client-Side Operations

Your login code may exist elsewhere in your app, but it's most commonly executed at app startup. If Access Manager is enabled, your clients are required to initialize the PubNub instance with an authKey.

PubNub uses the provided authKey to check for proper permissions before it allows the request to be executed. If the permissions exist for the requested operation on the channel, then the request is allowed to execute. If the proper permissions aren't found, the PubNub network responds with a 403 Forbidden response.

function login() {
// calls your server and returns the authKey
return authKey;
}

const authKey = login();

var pubnub = new PubNub({
publishKey: "myPublishKey",
subscribeKey: "mySubscribeKey",
uuid: "theClientUUID"
authKey: authKey
});

Your code in the callback function must use the status and response parameters to take necessary actions, whether it's to alert the client about the permission error, or to request the server to re-grant the permissions (on a new auth key), for example.