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 (users, spaces, 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 user, space, and membership 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 or token.
- Client application requests authorization from the server.
- Server sends authKey or token to the client application.
- Client application sets PubNub credentials with an authKey or token.
- PubNub verifies client permissions on all API calls from the client.
User Roles and Permissions
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 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
User and Space permissions are:
- create: create a user or space
- read: retrieve the user or space
- write: update the user or space
- manage: update membership for the user or space
- delete: delete the user or space
Standard User Permissions
A standard user can be granted read, write, and manage permissions for their own user record. They can also be granted read access on all users and spaces so they can fetch the entire list of records from the database.
Access on individual spaces:
Admin User Permissions
An admin user can be granted read, write, and manage access to all users and spaces, or admin access to individual spaces so they can add and remove members. Admins also typically have the ability to create and delete records in the database.
Access on individual spaces:
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.
Grant access to channels and channel groups
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 commonly-used value is 10080 (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.
Grant access to users and spaces
Use the Grant Token method to grant clients read, write, manage and delete access to users and spaces. The method returns an auth token that should be sent to the client and added to the Token Management System (TMS).
The auth token has permissions for each user and space resource embedded inside the token. Therefore, the size of the token should be managed so the PubNub API request does not exceed 32KiB. One option is to create a token per resource to keep it small in size. Another option is to include a limited set of resources in a token to limit the size of a token and generate new tokens for more resources.
The token schema is documented here.
The Grant Token method supports regex patterns that can be passed as parameters to grant access for multiple users and spaces.
Currently, PubNub supports only one regex pattern for users, and one pattern for spaces. Calling Grant Token again with new user and space patterns will overwrite the existing patterns.
Revoke access to channels and channel groups
To revoke access permissions for one or more users, call the Grant method and set the appropriate permissions to
Setting authKey for Channels and Channel Groups
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.
Token Management for Users and Spaces
The Token Management System (TMS) in the SDK allows you to store access tokens obtained via the Grant Token method. If a particular PubNub method requires authentication, the TMS performs a lookup to select an appropriate access token, and attaches it to the request in question as the authKey query parameter.
Stores a single token in the Token Management System for use in API calls.
Performs a lookup and returns a token for the specified resource type and ID. If no token is found for the supplied resource type and ID, the TMS checks for a pattern token at the resource type level. Returns null if no token is found.
Returns a map of all tokens stored by pubnub.setToken() or pubnub.setTokens().
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
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
PubNub Operations for Channels and Channel Groups
|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|
PubNub Operations for Users and Spaces
|Get all users||user||read on all users|
|Get all spaces||space||read on all spaces|
|Get space memberships for a user||space||read|
|Get space memberships for a user||user||read|
|Update space memberships for a user||user||write|
|Add space memberships for a user||user and space||write and manage permissions on the user.|
read permissions on the space
|Delete space memberships for a user||user||write|
|Get members in a space||space||read|
|Add members in a space||space||write and manage|
|Remove members in a space||space||write and manage|
|Update members in a space||space||write and manage|