PubNub Access Manager Getting Started Guide
Table of Contents Access Manager Overview Access Manager Sample UseCases 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 realtime communication is peertopeer, 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 realtime data is streaming bidirectionally 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 subscriptionbased 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 realtime 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://pubnubauthchat.herokuapp.com/ Source Code: https://github.com/pubnub/authchatdemo This simple lightweight demo is written in JavaScript for both the client (Web Browser) and server (Node.js). This example is good for a smallscale 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 (timetolive) 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 reallife scenario for an application in production, you should use a public key infrastructure (PKI) to create digital certificates and manage publickey 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 “mychat”, the presence channel name is “mychatpnpres”. 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/webjavascript/pamsecurity
● Knowledge Base: http://www.pubnub.com/knowledgebase/categories/accessmanager ● Tutorial: Adding Access Control to a Private Chat Channel:
http://www.pubnub.com/blog/javascriptprivatechatapiwithaccesscontrol/ ● Chat Security: User Identification with Digital Signature Message Verification
http://www.pubnub.com/blog/chatsecurityuseridentificationwithdigitalsignaturemessageverification/
API References
● Grant https://www.pubnub.com/docs/webjavascript/apireference#grant ● Audit https://www.pubnub.com/docs/webjavascript/apireference#audit ● Set Authentication Key https://www.pubnub.com/docs/webjavascript/apireference#auth