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.
The authorization flow is as follows:
- Server issues a PAM grant to allow privileges based on a custom authKey.
- Client application requests authorization from the server.
- Server sends authKey to the client application.
- Client application sets PubNub credentials with an authKey.
- PubNub verifies client permissions on all API calls from the client.
Below is the list of resources to which you can grant a client permissions, along with the access they get when the permission is granted. A complete mapping of permissions to PubNub operations can be found here.
Channel permissions are:
read: subscribe to a channel, fetch messages from history, and call presence operations
write: publish messages to a channel
delete: delete messages in a channel
Channel Group permissions are:
read: subscribe to channel groups
manage: add and remove channels from channel groups
This section outlines how to connect to PubNub in admin mode from a server, and how to grant and revoke permissions.
Connect to PubNub 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.
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 PubNub Dashboard.
The server can grant a user read/write privileges for multiple channels or channel groups with a particular authKey. The
ttl argument has a default value of 1440 minutes (24 hours), and another common value is 10080 minutes (1 week).
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 notation makes granting access on multiple channels more efficient. You can go one level deep using wildcards. In other words:
a.* grants access on all channels that begin with
a.b.* doesn't work. If you grant on
a.b.*, the grant treats
a.b.* as a channel name, not a wildcard.
To revoke permissions for one or more users, call the Grant method and set the appropriate permissions to
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.
Handling "permission denied" errors
Once your grants are in place, if during normal operation the client is denied access to a resource due to a PAM issue, the user application receives a
403 Permission Denied response. At this point, the user application should request another auth key or token from your server.
To authenticate and provide access to PubNub's network for your users, you need to provide them API keys. The client is able to perform the permitted activities such as Read/Write/Admin/Manage.
To retrieve the API keys it needs (for publishing, subscribing, authentication, and encryption), your app should authenticate itself by calling a secure endpoint with access credentials.
Don't hard-code keys in an app
Hard-coding your API keys for access to PubNub is a security risk, and doesn't let you rotate keys. Key migration is a poor, labor-intensive substitute for proper key rotation.
After successful authentication, the endpoint returns access tokens for only the necessary data channels. PubNub includes authentication endpoints that you can use if you don't have your own. You can program a PubNub Functions endpoint to authenticate the user and pass the all the needed access keys including the AuthKey. Your organization's policies may also require key rotation periods and short session IDs.
Auth keys are temporary access tokens, similar to a session ID, and you should create them with an appropriate TTL value. Don't offer an unlimited TTL when creating an auth key for your users. A one-time unlimited TTL auth key may be appropriate in some limited debugging or testing situations, but you should never grant unlimited TTLs to your users.
Storing secret keys
Always keep your keys secret. Never expose your secret key to ANYONE. Ideally, you should keep your secrets in an encrypted vault system. In the CI/CD deployment phase, the keys will be copied securely to your server code. Alternatively, the key vault may have a fetch endpoint accessible from within your VPC.
PubNub Operations/Permissions Mapping
|Subscribe to channel||channel||read|
|Publish on channel||channel||write|
|Signal on channel||channel||write|
|Unsubscribe from channel||channel||read|
|Where Now||channel||read on presence channel|
|Storage & Playback|
|Add Message Action||channel||write|
|Remove Message Action||channel||write|
|Get Message Actions||channel||read|
|Get History with Actions||channel||read|
|Subscribe to channel group||channelGroup||read|
|Unsubscribe from channel group||channelGroup||read|
|Add Channels to channel group||channelGroup||manage|
|Remove Channels from channel group||channelGroup||manage|
|List Channels in channel group||channelGroup||manage|
|Remove channel group||channelGroup||manage|