referance content
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
http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-keys.
Description
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
.- 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.
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.https://support.pubnub.com/support/solutions/articles/14000043626-why-do-i-get-invalid-timestamp-when-i-try-to-grant-permission-using-access-manager- |
- 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. e.g. 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.
If an argument of the grant is not provided, an expected default will be assumed.
|
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.
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.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. |
When the message size exceeds 32KB the server returns the HTTP Error code 500, instead of the correct error code 414. |
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. |
The limit on the total amount of channels that you can pass at once when using grant() is 200 . |
Method(s)
Grant Permissions on a Channel
you can use the following method(s) in the AngularJS V4 SDK:Parameter Type Required Defaults Description Operation Arguments Hash Yes A hash of arguments. 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.authKeys
Array Optional Specifies auth
Key to grant permissions.
It is possible to specify multipleauth
keys as comma separated list in combination with a singlechannel
name.
You can also grant access to a singleauth
key for multiplechannels
at the same time.
Zero or morechannels
with zero or moreauth
tokens are allowed.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 Yes false
Read
permissions are granted by setting totrue
.Read
permissions are removed by setting tofalse
.write
Boolean Yes false
Write
permissions are granted by setting totrue
.Write
permissions are removed by setting tofalse
.manage
Boolean Yes false
Manage
permissions are granted by setting totrue
.Manage
permissions are removed by setting tofalse
.callback
Function Optional Executes on a successful/unsuccessful grant
.
Basic Usage
Pubnub.grant(
{
channels: ['my_channel'],
authKeys: ['my_rw_authkey'],
read: true,
write: true,
ttl: 5
},
function (status) {
// handle state setting response
}
);
Other Examples
-
// grant world read access to all channels Pubnub.grant({ read: true });
-
// grant world read/write to my_channel Pubnub.grant( { channels: ['my_channel'], read: true, write: true }, function (status) { console.log(status); } );
-
// allow user read only access to my_channel Pubnub.grant( { channels: ['my_channel'], authKeys: ['my_ro_authkey'], ttl: 5, read: true, write: false }, function (status) { console.log(status); } );
The above code would return the following response to the client:{ error: false, operation: 'PNAccessManagerGrant', statusCode: 200 }
-
// Allow world read / write access to my_channel-pnpres Pubnub.grant( { channels: ['my_channel-pnpres'], ttl: 5, read: true, write: true }, function (status) { console.log(status); } );
- 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.Pubnub.grant( { channelGroups: [':'], read: true, manage: true }, function (status) { console.log(status); } );
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. e.g. Null parameters for channels and auth-keys can cause accidental application level grants.
Pubnub.grant( { read: true, // false to disallow write: true // false to disallow }, function (status) { console.log(status); } );
-
Pubnub.grant( { channels: ['ch1'], read: true, // false to disallow write: true // false to disallow }, function (status) { console.log(status); } );
-
Pubnub.grant( { channels: ['ch1'], authKeys: ['key1'], read: true, // false to disallow write: true // false to disallow }, function (status) { console.log(status); } );