The PubNub Access Manager (PAM) extends PubNub's existing security framework by allowing you to create and enforce secure access to channels. PAM lets you control a user's access to channels and messages using an
authKey that you have generated.
You assign the
authKey to the user from your server, and then grant the key permission to access the channels that the user needs to access. You can also control whether they have read, write, or read-write access to individual channels, and the TTL for which the authKey should be valid.
Access to a resource is granted or denied via the authorization key (the
authKey) set on the client. PAM enables you to generate an arbitrary value for
authKey from your server. This makes it possible to integrate a PubNub application with a pre-existing user authentication scheme or Security Authority.
The authorization flow is as follows:
- Server issues a PAM grant to allow privileges based on a custom
- User application requests authorization from server.
- Server sends
authKeyto user application.
- User application sends credentials with
authKeyto PubNub and subscribes to channel.
- PubNub verifies user privileges and allows the subscribe.
Managing access for users
A server can connect in admin mode by including the
secretKey when it initializes PubNub. 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.
Granting read/write access
The server can grant a user read/write privileges to multiple channels or channel groups with a particular
ttl argument has a default value of
1440 minutes (24 hours). Other common values for
10080 (1 week) and
0 (never expires).
Production grants should always expire
ttl value of 0 (zero) means the grant never expires, which can be helpful for testing. In production, you should never grant with an unlimited TTL.
Granting read-only access
You can grant read-only permissions for anyone trying to perform read actions (such as subscribe and history).
Granting write-only access
You can grant write-only permissions for anyone trying to perform write actions only.
To revoke access permission(s) for one or more users, call
pubnub.grant() and set the appropriate permission(s) to
authKeys parameter to revoke access globally for all users who are subscribed to the channel.
Using wildcards in 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
- Specifying a.b.* doesn't work. If you grant on
a.b.*, the grant treats
a.b.*as a channel name, instead of a wildcard.
Managing access with channel groups
When granting or revoking permissions based on channel groups, use the
channelGroups attribute instead of
channels in your PAM call.
Here are a few important details on working with channel groups:
You can't grant
writepermission on a channel group.
readpermission on a channel group supersedes the read permissions of the underlying channels.
For example, assume you have denied read access on
ChannelOne, and you then add
ChannelOneto channel group
GroupOne. Granting read access on
GroupOneallows the user to read
managepermission allows the ability to add or remove channels from a channel group.
Connecting to PubNub from a client
If Access Manager is enabled on your key, all users need to provide a valid authKey to connect to PubNub. The authKey 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 authKeys 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
authKey from your server.
setAuthKey() (in Swift, update the value of
currentConfiguration().authKey and push the new configuration) to update the authKey for the user.
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. Upon CI/CD deployment phase, the keys will be copied securely to your server code. Alternatively, the key vault may have a fetch endpoint which is accessible inside your VPC.