Managing Permissions and Access Controls
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
The authorization flow is as follows:
- The server issues a PAM grant to allow privileges based on a custom authKey.
- The client application requests authorization from the server.
- The server sends an authKey to the client application.
- The client application sets PubNub credentials with that authKey.
- Thereafter, PubNub verifies the client permissions on all API calls from the client.
Connecting 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.
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.
Revoking permissions: To revoke permissions for one or more users, call the Grant method and set the appropriate permissions to false.
To learn more about connecting to PubNub in admin mode from a server, and how to grant and revoke permissions, refer to Authentication & Permission Granting for more details. That page also contains a complete mapping of permissions to PubNub operations.
TODO move the following note to Server SDK Grants on platform docs.
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.
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.