Managing User Permissions

Access Manager allows you to regulate clients' access to PubNub resources, such as channels, channel groups, and other users' metadata. For instance, you can make a one-to-one chat room private by only allowing one user to be able to read and write messages in this channel.

To use Access Manager, you must first enable it on the Admin Portal by navigating to your keyset and turning on the ACCESS MANAGER option under the CONFIGURATION tab. Once enabled, the server with the secretKey access needs to request PubNub to grant proper permissions to clients using the grant API. This way PubNub will accept only the requests made by an authorized client (authorized_uuid) and return requested results that fall within the limits of the permissions granted.

Authorization Flow

To understand how the communication between the client, server, and PubNub works, see an example of the authorization flow initiated by a client trying to access the PubNub network:

Client Devices → Your Server → PN Network ← Client Devices

  1. Upon login, the client device requests authorization to be able to send requests to PubNub.

  2. The server issues a token request to PubNub by defining the permissions it needs to give to a specific authorized uuid.

  3. PubNub reads these permissions and returns a signed, self-contained, and time-limited access token to the server.

  4. The server passes the token to the client device as part of the login response.

  5. The client device adds the token to the client's SDK configuration.

  6. When the client device later makes PubNub API calls, the SDK passes the configured token. It can continue to do so until the token's ttl expires, at which point it needs to request a new token to be issued.

Connecting from a server

When a server connects to PubNub by including the secretKey during the PubNub object initialization, it operates in admin mode. In this mode, the server has unlimited access to all channels and can perform grant operations to manage channel permissions for users.

Secret key security

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

Granting permissions

The server can grant a user permissions for multiple channels, channel groups, or other users' metadata, like names or avatars. These grant requests can be issued:

  • For a limited period of time (preferably between 10 and 60 minutes).
  • By specifying permissions for a list of resources or resource patterns in the form of (regular expressions).
  • For one user (called authorized_uuid) that is later solely authorized to use the granted token to perform various operations on PubNub APIs.
  • In a single API request, even if permission levels differ (read to channel1 and write to channel2).

The following request shows a grant request that gives user-1 the read and write permissions to channel-a and channel-b for a time limit of 15 minutes.

Go to SDK

pubnub.grantToken(
  {
    ttl: 15,
    authorized_uuid: "user-1",
    resources: {
      channels: {
        "channel-a": {
          read: true,
          write: true
        },
        "channel-b": {
          read: true,
          write: true
        }
      }
    }
  }, function(status, token) {
    console.log(token);
  }
);

Go to SDK

channels = [
    Channel.id("channel-a").read().write(),
    Channel.id("channel-b").read().write()
envelope = pubnub.grant_token()
    .channels(channels)
    .ttl(15)
    .authorized_uuid("user-1")
    .sync()

Go to SDK

pubnub.grantToken()
    .ttl(15)
    .authorizedUUID("user-1")
        .channels(Arrays.asList(
                ChannelGrant.name("channel-a").read().write(),
                ChannelGrant.name("channel-b").read().write()))
        .async(new PNCallback<PNGrantTokenResult>() {
            @Override
            public void onResponse(@Nullable PNGrantTokenResult result, @NotNull PNStatus status) {
                if (status.error()) {
                    // Handle error
                }
                else {
                    // Handle result
                }
            }
        });

Go to SDK

pubnub.grantToken(
    ttl = 15,
    authorizedUUID = "user-1",
    channels = listOf(
        ChannelGrant.name(name = "channel-a", read = true, write = true),
        ChannelGrant.name(name = "channel-b", read = true, write = true)
    )
)
    .async { result, status ->
        if (status.error) {
            // Handle error
        } else {
            // Handle result
        }
    }
Revoking permissions

Access Manager doesn't support revokes yet. For now, you can override existing access by requesting a new token with changed permissions and using that token in the subsequent requests. Previous access will be removed once the original token expires. For this reason, it's recommended to use short-lived tokens with ttl between 10 and 60 minutes. If your application requires to have an option to revoke existing permissions, contact support for assistance.

Client-side operations

Upon receiving a token from the server, the client needs to update its configuration and set the new token with a setToken() method (name may vary). From then on, it needs to provide a valid token in every request made to the PubNub. When a client makes an API request using a token that has expired, PubNub API will respond with a 403 at which point the server needs to create another grant request for a new token to be generated. To debug any token issues or simply check privileges embedded in the token, use the parseToken() method.

Read more about both methods and all client-side operations in the Access Manager feature description.

←Managing UsersUser Presence→