Vue V4 Access Manager API Reference for Realtime Apps
PubNub Access Manager (PAM) extends PubNub's existing security framework by allowing developers to create and enforce secure access to channels and channel groups throughout the PubNub Real-Time Network.
As soon as Access Manager is enabled, no pub/sub-operations can be done without first explicitly providing an authorization token to the PubNub object. If an invalid token is provided, the requesting client will receive a Forbidden Error.
Learn more about Access Manager here.
Grant
Requires Access Manager add-on Requires that the Access Manager add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-
Description
This function establishes access permissions for PubNub Access Manager (PAM) by setting the read
or write
attribute to true
. A grant
with read
or write
set to false
(or not included) will revoke any previous grants with read
or write
set to true
. Permissions can be applied to any one of three levels:
- Application level privileges are based on
subscribeKey
applying to all associated channels. - Channel level privileges are based on a combination of
subscribeKey
andchannel
name. - User level privileges are based on the combination of
subscribeKey
,channel
and auth Key.
Warning
For NTP synchronization, please ensure that you have configured NTP on your server to keep the clock in sync. This is to prevent system clock drift leading to 400 Invalid Timestamp
error response.
When a user attempts to access a PubNub resource, PAM will evaluate any existing rules using the following order of precedence before access to a channel is granted to the user:
Application Level - PAM privileges are always evaluated first at the Application level. If either
read
orwrite
attribute is set totrue
for asubscribeKey
, PAM will immediately grant access for that attribute without proceeding to check permissions at eitherChannel
orUser
levels. If an attribute is set tofalse
at the Application level, PAM proceeds to evaluate the attribute at the next most granular level.Use application level grants with caution
When access is granted on an application level,
all channels and users
will have access.Application level grants can also happen due to a bug in your code. For example, Null parameters for channels and auth-keys can cause accidental application level grants.
Channel Level - After first verifying an attribute at the Application level, PAM evaluates the attribute at the Channel level. If an attribute is set to
true
for a combination ofsubscribeKey
andchannel
, PAM grants access for that attribute at theChannel
level without proceeding to check whether there may beuser
level permissions.User Level - As a final step PAM evaluates the attributes at the
User
level. If an attribute is set totrue
forsubscribeKey
,channel
and auth Key, access is granted for that attribute.
Note
If an argument of the grant
is not provided, an expected default will be assumed.
read
andwrite
arguments default tofalse
- no auth Key results in
channel-level
grant - no
channel
results inapplication-level
grant
No Permissions - If no permissions were granted at any of the three levels, the user will be denied access to the PubNub resource and receive a 403 error message. This is the default behavior for a PAM enabled application.
Important
Note that privileges specifically granted to an application's subscribeKey
always take precedence over privileges granted to channel
or auth Key. Therefore an application that requires authentication at the user
level should not grant access at either the Application
or Channel
levels.
- History To access historical messages you must grant full
read
access at either thesubscribeKey
orchannel
level. When a user has the appropriate permissions they can access any data stored. If they do not have access a403
will be returned by PAM. - Presence To grant access to Presence for a particular channel name you must also allow
read
andwrite
access to the presencechannel
name which is specified by adding the-pnpres
suffix to the name. Also note that aleave
will fail in the case where a user's grant expires while connected. An HTTP403
will be returned. - APNs Standard permissions are required for publishing.
The duration of permission set with grant()
are controlled by setting a time-to-live(ttl
). If a ttl
is not specified it is automatically set to 1440
minutes by default. Once the ttl
associated with an entry in PAM has expired, the read
and write
attributes are immediately set to false
for that entry in the PAM table.
Caution
PAM grant or revoke requests must be less than ~32KB at a time, or the client will return an error. For requests greater than 32KB, break them into smaller batched requests.
Warning
When the message size exceeds 32KB the server returns the HTTP Error code 500, instead of the correct error code 414.
Note
When you init with secretKey
, you get root permissions for the Access Manager. With this feature you don't have to grant access to your servers to access channel data. The servers get all access on all channels.
Note
The limit on the total amount of channels
that you can pass at once when using grant()
is 200
.
Method(s)
To Grant Permissions on a Channel
you can use the following method(s) in the Vue V4 SDK:
grant({Array channels, Array channelGroups, Array uuids, Array authKeys, Number ttl, Boolean read, Boolean write, Boolean manage, Boolean delete, Boolean get, Boolean update, Boolean join},Function callback)
Parameter Type Required Defaults Description authKeys
Array Optional Specifies authKey
to grant permissions. It is possible to specify multipleauth
keys as comma separated list in combination with a singlechannel
name.authKeys
are required for user-level grants. If you don't specify anauthKey
, the permissions will apply to all clients on channel-level or application-level. View the Grant Levels section for more details.channels
Array Specifying either channels
orchannelGroups
is mandatory.Specifies the channels
on which togrant
permissions. If nochannels/channelGroups
are specified, then thegrant
applies to any and allchannels/channelGroups
that have been or will be created for thatpublish/subscribe
key set. Furthermore, any existing or future grants on specificchannels
are ignored, until theall channels
grant is revoked. It is possible togrant
permissions to multiplechannels
simultaneously by specifying thechannels
as a comma separated list.Wildcard notation likea.*
can be used togrant
access on channels. You cangrant
one level deep.a.*
- you can grant on this.a.b.*
- grant will not work on this. If you grant ona.b.*
, the grant will treata.b.*
as a single channel with namea.b.*
.
channelGroups
Array Specifying either channels
orchannelGroups
is mandatory.Specifies the channelGroups
togrant
permissions. If nochannels/channelGroups
are specified, then thegrant
applies to any and allchannels/channelGroups
that have been or will be created for thatpublish/subscribe
key set. Furthermore, any existing or future grants on specificchannelGroups
are ignored, until theall channelGroups
grant is revoked. It is possible togrant
permissions to multiplechannelGroups
simultaneously by specifying thechannelGroups
as a comma separated list.uuids
Array Optional A list of uuids
togrant
permissions to. You can't grant permissions to channels and channel groups in the same request if you decide to useuuids
. This parameter does not support wildcards.ttl
Number Yes 1440 (24hrs)
Time in minutes for which granted permissions are valid. Default is 1440 (24hrs)
, Max is525600
, Min is1
. Settingttl
to0
will apply the grant indefinitely.read
Boolean Optional false
Read
permissions are granted by setting totrue
.Read
permissions are removed by setting tofalse
.write
Boolean Optional false
Write
permissions are granted by setting totrue
.Write
permissions are removed by setting tofalse
.manage
Boolean Optional false
Manage
permissions are granted by setting totrue
.Manage
permissions are removed by setting tofalse
.delete
Boolean Optional false
Set to true
to grantdelete
permissions. Set tofalse
to removedelete
permissions.get
Boolean Optional false
Set to true
to grantget
permissions. Set tofalse
to removeget
permissions.update
Boolean Optional false
Set to true
to grantupdate
permissions. Set tofalse
to removeupdate
permissions.join
Boolean Optional false
Set to true
to grantjoin
permissions. Set tofalse
to removejoin
permissions.callback
Function Optional Executes on a successful/unsuccessful grant
.
Basic Usage
Grant PAM Permissions for channel and auth Key
import PubNubVue from 'pubnub-vue';
const pubnub = PubNubVue.getInstance();
pubnub.grant(
{
channels: [ch1, ch2],
channelGroups: [cg1, cg2],
authKeys: [key1, key2],
ttl: 12313, // 0 for infinite
read: true, // false to disallow
write: true, // false to disallow
manage: true// false to disallow
},
function(status) {
// handle state setting response
}
);
Other Examples
Grant subscribe privileges to all users on all channel(s) with default ttl (1440 minutes):
import PubNubVue from 'pubnub-vue'; const pubnub = PubNubVue.getInstance(); // grant world read access to all channels pubnub.grant({ read: true });
Allow subscribe and publish to a specific channel for all users (no auth Key required) with default ttl (1440 minutes):
import PubNubVue from 'pubnub-vue'; const pubnub = PubNubVue.getInstance(); pubnub.grant( { channels: ['my_channel'], read: true, // false to disallow write: true// false to disallow }, function(status) { console.log(status); } );
Grant subscribe access to a channel only for clients with a specific auth Key with a 5 minute ttl:
import PubNubVue from 'pubnub-vue'; const pubnub = PubNubVue.getInstance(); pubnub.grant( { channels: ['my_channel'], authKeys: ['my_ro_authkey'], ttl: 5, // 0 for infinite read: true, // false to disallow write: false// false to disallow }, function(status) { console.log(status); } );
The above code would return the following response to the client:
{ error: false, operation: 'PNAccessManagerGrant', statusCode: 200 }
Allow access to a specific channel for Presence:
import PubNubVue from 'pubnub-vue'; const pubnub = PubNubVue.getInstance(); pubnub.grant( { channels: ['my_channel-pnpres'], ttl: 5, // 0 for infinite read: true, // false to disallow write: true// false to disallow }, function(status) { console.log(status); } );
Allow access to all channel groups using wildcard:
To perform a first level wildcard grant for channel groups you need to specify
:
(colon) as the parameter forchannelGroups
. This will ensure that users canread
ormanage
all channel groups.import PubNubVue from 'pubnub-vue'; const pubnub = PubNubVue.getInstance(); pubnub.grant( { channelGroups: [':'], read: true, manage: true }, function(status) { console.log(status); } );
Grant access to all channels on all authKeys
This request grants
read
permission to all users on all channel(s) with defaultttl
(1440 minutes). This rule applies on the application level and takes precedence over channel and user-level permissions.Use application level grants with caution
When access is granted on an application level,
all channels and users
will have access.Application level grants can also happen due to a bug in your code. For example, Null parameters for channels and auth-keys can cause accidental application level grants.
pubnub.grant({ read: true });
-
import PubNubVue from 'pubnub-vue'; const pubnub = PubNubVue.getInstance(); pubnub.grant( { channels: ['ch1'], read: true, // false to disallow write: true// false to disallow }, function(status) { console.log(status); } );
Grant access to a channel on an authKey
Grant
read
permission to a channel only for clients with a specificauthKey
with a 5 minutettl
:import PubNubVue from 'pubnub-vue'; const pubnub = PubNubVue.getInstance(); pubnub.grant( { channels: ['ch1'], authKeys: ['key1'], read: true, // false to disallow write: true// false to disallow }, function(status) { console.log(status); } );
-
pubnub.grant( { uuids: ['uuid1'], authKeys: ['key1'], ttl: 60, // 0 for infinite get: true, // false to disallow update: true, // false to disallow delete: true // false to disallow }, function (status) { console.log(status); } );