PubNub Access Manager Getting Started Guide

 

Table of Contents Access Manager Overview Access Manager Sample Use­Cases Demo and Source Code Tutorial Overview Setting up Access Manager 

Installing Initialization 

Admin Mode User Mode 

Granting users access to channels Granting all users access to all channels Granting all users access to a single channel 

Revoking user access (“Kick” or “Ban”) Monitoring user permissions Granting access to PubNub presence channels Additional  Resources 

Technical articles and tutorials API References 

 

 

Access Manager Overview  Access Manager extends PubNub’s existing security framework by allowing developers to create and enforce secure access to channels throughout the PubNub Data Stream Network.   Access Manager enables the following functions:  

● Syndicating streams by authorizing users to read/write messages on one or more channels 

● Granting/revoking permissions for your realtime streams at the user/device, channel, or key level 

● Working with Auth tokens from any existing authentication system: OAuth (Facebook Connect, Twitter, Google, GitHub, etc.), LDAP, or homegrown solutions 

Access Manager Sample Use-Cases  Access Manager is critical for social apps and chat rooms where secure real­time communication is peer­to­peer, with the option to monitor and intervene in user interactions when needed (e.g. ban a user, change privileges on a private chat room, etc.).  IoT / Home Automation Device management, where secure real­time data is streaming bi­directionally between registered devices, allows users to get device status and control devices such as light bulbs, door locks, temperature sensors, and security cameras.  Subscription services allow companies to offer subscription­based streams (e.g. financial services, trading signals, data feeds, consumer subscriptions) and enforce user limits and data access by granting and/or revoking privileges to the data streams based on what access the user has purchased.   Multiplayer gaming for real­time interaction, where players are granted access to restricted area, stages, etc.  And many more ­ nearly every use case that needs PubNub’s Data Stream Network could also benefit from using Access Manager. 

Demo and Source Code  To get started, check out the live demo that shows Access Manager in action and download the source code from GitHub:  Live Demo: https://pubnub­auth­chat.herokuapp.com/ Source Code: https://github.com/pubnub/auth­chat­demo  This simple light­weight demo is written in JavaScript for both the client (Web Browser) and server (Node.js). This example is good for a small­scale chat app, and merely one way to authorize users’ read/write access to familiarize you with Access Manager APIs.   Let’s get started.   

The Simple Chat App Scenario:  

1. Authenticate User: When a user accesses the web app (client) for the first time, the user is asked to sign in using a GitHub credential. 

2. Use auth_key to Grant Access: Once the user logs in, the user is given an auth token from OAuth. The token is used as an auth_key that the "admin" (server) can reference to grant read/write permission to the user. 

3. Send Messages: the client sends the message with a digital signature. Digital signatures are fingerprints with embedded secure cryptographic hashes of key components of the message payload, and used to block spoofers. 

4. Receive Messages: Simultaneously, web clients of all users on the chat channel subscribe the message from PubNub stream. Messages are displayed only when the messages are verified authentic. 

 

  

Tutorial Overview  Access Manager allows you to manage granular permissions for your realtime apps and data streams, create multiple permission levels, grant and revoke access, and audit user access. This guide walks through how to use Access Manager by providing code samples from the demo app outlined above.   

Setting up Access Manager  

To use Access Manager, you need to enable Access Manager in the Admin Dashboard.Caution: Once you enable Access Manager, you must grant permissions before any data can be sent or received.  

  

   

Installing  Access Manager APIs are included in pubnub.js, so you can include either pubnub.js or pubnub.min.js, with a specific version, in your HTML file as usual:  <script src="http://cdn.pubnub.com/pubnub-[version number].js"></script>

 Be sure to include the latest version, which is available in the JavaScript documentation. 

 If you are using PubNub JavaScript SDK version 3.6 or older, in addition to the pubnub.js file (pubnub-[version].min.js), you also need to include:  

<script src="https://cdn.pubnub.com/pubnub-crypto.min.js"></script>   

Initialization  When using Access Manager, use admin mode for administrative users who have access to grant/deny a user permission, and general user mode for the rest of the users.  

Admin Mode  To initialize your instance with an administrative function, you need to include your secret_key, which you should be able to find in the Admin portal along with your subscribe and publish keys: 

 

All the admin actions (setting secret_key, grant, revoke, etc.) should be done on the server side, since you don’t want to expose the secret_key on the client side.   The example below is in node.js:  var pubnub = require('pubnub').init({ subscribe_key: 'sub-c-f762fb78-...', publish_key: 'pub-c-156a6d5f-...', secret_key: 'sec-c-M2U0N...' });

User Mode Initialize your client with auth_key to identify each subscriber.  var pubnub = PUBNUB.init({ subscribe_key: 'sub-c-f762fb78-...', publish_key: 'pub-c-156a6d5f-...', auth_key: 'my_auth_key_from_login' });

 The arbitrary auth_key should be unique. It can be a uuid, or an authentication token from OAuth (Facebook Connect, Twitter, Google, GitHub, etc.), LDAP, RADIUS, or any other authentication system. The admin uses the auth_key to control and monitor users.  In the demo, we use an OAuth token from a GitHub login as an auth_key.  If at any point during runtime you need to reset the auth key, you can call the auth() method to set it again:  pubnub.auth('my_new_auth_key');   

Granting users access to channels Only an admin can grant access to a user. This operation should only be done on the server side.  With Access Manager, you can grant access:  

● on a global level 

● on a channel/channel group level  ● on a channel/channel group + auth key level  

 For example, when you are creating a chat app, you can manage chat rooms (= channels) or users (= auth keys).  If you are creating a home automation system, you might grant write access to the light bulbs to send their status data and read access so a user can control them remotely via a smartphone app. In other words, you would grant read access to users who will receive data, and write access to users who have permission to control the light’s operations.     

Granting all users access to all channels This example grants read and write privileges to all users for 60 minutes (functionally equivalent to disabling PubNub Access Manager for a short time):  pubnub.grant({ read: true, write: true, ttl: 60, callback: function(m){console.log(m)}, error: function(m){console.error(m)} });

 The default ttl (time­to­live) value is 24 hours (1440 minutes). When you set ttl as 0, it grants access forever and never expires.  Admin calls should always include an error handler. These functions are especially sensitive to some conditions such as clock drift. Be sure to install and properly configure your servers to prevent this specific error case.  

Granting all users access to a single channel  When you specify a channel name (or group), you can grant all users access to the specific channel (or group) only. This example uses the default ttl:  pubnub.grant({ channel: 'public-room', read: true, write: true, callback: function(m){console.log(m)} });

 

Granting a user access to a private channel  This example grants 60 minute read and write privileges on a channel to a user, who is associated with a particular auth_key: 

pubnub.grant({

channel: 'private-83659357',

auth_key: 'abcxyz123-auth-key',

read: true,

write: true,

ttl: 60,

callback: function(m){console.log(m)}

});

 If the auth_key param is not included, a global grant is issued to all users who are subscribed to the channel.  Example  In this chat room example, the admin only grants users, who has signed in with GitHub login, using the OAuth token as an auth_key.  var channel = ‘auth-chat’;

 pubnub.grant({

channel: channel,

auth_key: '9ae4c23e1a8c6654efddf98c2b8ab5fba3f', // OAuth token read: true,

write: true,

callback: function(m){console.log(m)}

});

 When a user types a message in a form field and clicks a “Send” button on the browser, the message is published with a digital signature.  

  Publishing a simple message in the client looks like this:  

send.addEventListener('click', function(e) { pubnub.publish({ channel : channel, message : {text: input.value} }); }, false);

Note: In the real­life scenario for an application in production, you should use a public key infrastructure (PKI) to create digital certificates and manage public­key encryption to eliminate spoofing, however, we are not discussing the subject in this tutorial. To learn more about security, please refer Chat Security: User Identification with Digital Signature Message Verification article, and take a look at the source code on GitHub to see how the demo chat app uses Elliptic curve cryptography (ECC).  If a user (let’s say the user has an auth_key, xyz789) has never granted the write access, and tries to publish in the manner, the user get a 403 error with this log:  ["PUBLISH ERROR",{"message":"Forbidden","payload":{"channels":["my-chat"]}}]     

Revoking user access (“Kick” or “Ban”) Only an admin can revoke access from a user. The easiest way to deny read and write access is to use the revoke() method. Using the grant() method with read and write set to false will have the same effect. This operation should be done on the server side.  The next two code examples have the same result:  pubnub.revoke({...}); 

or  pubnub.grant({ read: false, write: false, ...

});  

 When you are revoking access from a particular user for a particular channel, use the user’s auth_key.  pubnub.revoke({ channel : channel, auth_key : '9ae4c23e1a8c6654efddf98c2b8ab5fba3f...' });

If the auth_key param is not included, access is revoked on that channel globally for all users.  

Monitoring User Permissions  Access Manager allows you to audit access rights by revealing existing permissions for any combination of subscribe_key, channel, auth_key.  To get the list of all permissions set, use the audit() method.   To get a list of all permissions at the global level, you could call audit() like this: 

pubnub.audit({callback : function(m){console.log(m)});

Or you can audit on a specific auth_key: 

pubnub.audit ({ channel: channel, auth_key: '9ae4c23e1a8c6654efddf98c2b8ab5fba3f...', callback : function(m){console.log(m)} });

Example  When you audit using Node.js:  pubnub.audit({ callback: function(m){ console.log(util.inspect(m, false, null)); }

});  Console will log something like this for the callback: 

{ channels: { 'my-chat': { auths: { '94e4cc3e1-user-auth': { r: 1, m: 0, w: 0, ttl: 1440 }, '619f8945a4f-admin-auth': { r: 1, m: 0, w: 1, ttl: 1440 } } }, 'my-chat-pnpres':

{ auths: { '619f8945a4f-admin-auth': { r: 1, m: 0, w: 0, ttl: 1440 } } } },

subscribe_key: 'sub-c-981...', objects: {}, 'channel-groups': {}, level: 'subkey' }   

Granting Access to PubNub Presence Channels  When you are using PubNub Presence in your app (e.g. displaying how many users are online), you need to grant users access to particular presence channels in order to read the corresponding presence data.  You can allow read access to the presence channel name which is specified by adding the -pnpres suffix to the original channel name. For example, when the channel name is “my­chat”, the presence channel name is “my­chat­pnpres”.  pubnub.grant({ channel: channel+'-pnpres', auth_key: 'user-auth', read: true, write: false, callback: function(m){console.log(m);} , error: function(err){console.log(err);} });   

Additional Resources  

Technical articles and tutorials  

● JavaScript Security with Access Control, AES & TLS/SSL Encryption for Realtime Apps: https://www.pubnub.com/docs/web­javascript/pam­security 

● Knowledge Base: http://www.pubnub.com/knowledge­base/categories/access­manager ● Tutorial: Adding Access Control to a Private Chat Channel: 

http://www.pubnub.com/blog/javascript­private­chat­api­with­access­control/ ● Chat Security: User Identification with Digital Signature Message Verification 

http://www.pubnub.com/blog/chat­security­user­identification­with­digital­signature­message­verification/ 

 

API References  

● Grant https://www.pubnub.com/docs/web­javascript/api­reference#grant ● Audit https://www.pubnub.com/docs/web­javascript/api­reference#audit ● Set Authentication Key https://www.pubnub.com/docs/web­javascript/api­reference#auth