Implementing Three-Legged OAuth with Digital Streams

It's quite common for cloud services (and webtail vendors) to integrate with a digital identity platform, such as Google+ or Facebook; the reasons for doing so are very well documented. The beaten path for this type of integration is to use three-legged OAuth. But when implementing a real-time solution, there are additional touchpoints to consider for a more cohesive integration.

In traditional two-legged authentication, the resource owner (AKA the user) simply supplies a username and password to the application. The application then stores and forwards those credentials on to the identity provider. In turn, the authentication provider allows access to protected resources.

While two-legged authentication works for rich integrations, like those found on mint.com, three-legged authentication provides a much more secure authentication. For one, it removes the need for your application to manage third-party user credentials. It also preserves the end user's ability to constrain and revoke access to your app as needed.

How it Works

1. The application makes a request for a protected resource to Github.
2. Github redirects the application to an authentication URL.
3. The user is prompted to authenticate and authorize the app.
4. GitHub issues an auth_code and invokes your configured OAuth callback.
5. The application exchanges the auth_code for an access_token.

OAuth and Digital Streams

With digital streams like PubNub's pub/sub, the protected resource is the channel. Channels ensure data is transferred from the origin/publisher to channel subscribers. They are dynamic and identified by a simple string (i.e. the channel name).

In non-secure applications, simply initializing PubNub, subscribing, and publishing messages to a collection of channels is trivial. However, if you need to secure your application you will need some way to provision users as they log in. To do this you will need a traffic cop that can identify the request sent from the client application and ensure that client is authorized.

This role is typically done by a fourth component: a Security Authority (SA). It’s usually a collection of HTTP endpoints that are responsible for mapping an identity to a set of permissions. The HubBub server includes a node-based express app which makes it a great Security Authority, as its primary responsibility is to interact with Access Manager. We will address how to implement that later, but first let's review what three-legged authentication looks like with the addition of Security Authority.

Three-Legged OAuth + Security Authority

The Access Manager allows you to grant access based on person, device, or channel. For our purposes, we are performing grants at the user level . The main difference here, in comparison to three-legged OAuth, is that the SA is invoked by Github.

1. The application makes a request for a protected resource to Github.
2. Github re-directs your app to the proper endpoint that prompts the user for authentication.
3. The application navigates to that URL, the user is prompted to authenticate and authorize the app.
4. GitHub issues an auth_code that is exchanged for an access_token by the Security Authority.
5. The Security Authority calls pubnub.grant(..), granting the access_token permissions on the required channels

Setting up the Security Authority

Focusing on ‘HubBub,' and in particular the HubBub server’s security authority, you can access the code for this solution here.

Before we go any further, there are a few steps you will need to take to get your environment up and running:

1. Create your PubNub keyset and enable Access Manager.
2. Register and configure your application on GitHub.
3. Clone the HubBub repository and configure the Security Authority.

Enabling Access Manager

1. Log into the PubNub Customer Portal.
2. Create a new app.
3. Select the new application.
4. This creates a new default development keyset; select that key.
5. Enable access manager.
6. Note your publish key, subscribe key, and secret key as they are needed for configuring the HubBub Security Authority.

Create an Application on Github

GitHub allows you to register your application to use GitHub as an Identity Provider. The application name is any name you like. The other two values are much more significant and must match the values you send to github during the authentication process. These two values are:

1. Homepage URL – This is the main entry point into your application.
2. Authorization Callback – GitHub will use this endpoint after the user has authenticated and authorized your app. The payload will contain the auth_code that can be exchanged for an access_token. The URL MUST match the redirect URL that you supply in your initial call from your application.

Log into GitHub and select your profile dropdown in the top right corner of the screen. From there, select OAuth applications in the left panel. Then select “Developer Applications” and fill out the app registration form. The Homepage URL and Authorization URL’s will be the same for HubBub.

Configure the HubBub Server

1. Clone the HubBub repository.
2. In the “server” directory, copy the sample.env file to ./.env.
3. Edit the .env file supply the proper values for the following:

1. Initialize PubNub as a Security Authority. This simply means the init'ing an instance of PubNub with a secret key
2. Next we need an endpoint to accept the auth_code from GitHub downstream of the user authenticating
   

Conclusion

As you can see, it is possible to leverage any standards-based OAuth 2.0 Identity platform to secure access to your real-time solution. As we outlined in this tutorial, with the HubBub server acting as a Security Authority and the integration point with GitHub, this could have easily been implemented to use other Identity Platforms like Facebook or Google+. All you need is a standards based OAuth 2.0 identity platform that supports three-legged web server flow.