#janrain-git

To enable social login and registration you need to have a free, pro, or enterprise account with Janrain and setup your providers i.e. Facebook, Twitter, etc. Next you need to provide a callback endpoint that Janrain can POST back to. Once Janrain POSTS to your site you can use the Janrain API to validate the credentials and request a normalized version of their profile, contact list, etc.

You can signup for a free, pro, enterprise account at Janrain.

The signup process uses their social login so you will need to have an account with Facebook, Google, Twitter, etc to start. You will need to confirm your information and create your account. You will need to pick your application's name. This name is visible by your users and will be presented to them each time they grant access to their 3rd party account i.e. Facebook and Twitter. Check out the image on the right hand side to see what your application name will look like when your users try to connect.

Great! You should be at your dashboard and if not go to your dashboard. You can keep clicking the button in the upper right hand corner labeled "account" or "dashboard" and this will toggle you between your account and dashboard--- how clever. Step 1 is to click on the "Sign-In for Websites" under the "Quick Links" on the right-hand side. This will take you to the wizard to help you get the javascript code to put on your site.

Before you do that, you need to choose and configure the providers that you want to offer to your users. To do this, skip the "Get the Widget" step by clicking on the "Choose Providers" this is labeled as Step 2. If you pick providers that require additional configuration i.e. ones that have a gear next to them you will be prompted to configure them.

Step 3 is to configure the providers. You will need to follow the steps in the wizard and copy the key/secret from the providers into Janrain setup wizard. Above is an example of Facebook and Twitter providers. Janrain will help you configure all your providers if you have a pro or enterprise account.

Now that you have picked your providers and configured them click on the wizard step labeled "Handle Tokens" copy the "apiKey" value this is your api key and SHOULD be kept secret. You can also get this value on your main dashboard page. We will need this later when we write our server code so keep it handy. 

If you want to test your configuration you can optionally click on the "Test Tool" under the "Resources" on the right hand side. This will simulate the Janrain sign-in widget and show you what data is returned when someone connects to your site.

We are almost done. The final step is to go to your dashboard and click on "Settings" under the "Quick Links" on the right-hand side. If you plan to use Janrain on a domain other than localhost you will need to add that domain to the "Token URL Domains". There are also many different settings like "Provider Configuration" on the dashboard page. I would recommend exploring them later after you get your code up and running.

Let the fun begin, now install the Janrain node.js package you can do this using npm or visit https://github.com/demetriusj/janrain to manually install the package. We are also going to need to build a barebone site to demo all our cool work so lets use connect because it makes it so much easier. If you do not have connect installed use "npm install connect"

$ npm install janrain-api

Now that you have the package installed you will need to create a folder for the project. We need to make a host demo site and RPX callback hook. This is just a place Janrain can POST back to.

Now create a file app.js in the folder. You will need to update the {YOUR_API_KEY}, {YOUR_APP_NAME}, and optionally localhost:8080 if you are going to run the application on a different domain than localhost. The {YOUR_API_KEY} should be replaced with your api key found in your Janrain account. The {YOUR_APP_NAME} is the name you gave your Janrain account.

var connect = require('connect'), janrain = require('janrain-api'), express = require('express'); var engageAPI = janrain('{YOUR_API_KEY}'); var app = express.createServer(); app.get('/', function(req, res){ res.render('index.jade', { locals: { app_name:'{YOUR_APP_NAME}', domain:'localhost:8080' }, layout:false }); }); app.post('/rpx', connect.bodyDecoder(), function(req, res){ // We will cover this in the next session! }); app.listen(8080);

Create a view lets use jade because that is what all the cool kids are using. Lets call the file views/index.jade and copy the code below.

!!! 5 html(lang="en") head title Janrain Web app :javascript | var rpxJsHost = (("https:" == document.location.protocol) ? "https://" : "http://static."); | document.write(unescape("%3Cscript src='" + rpxJsHost + "rpxnow.com/js/lib/rpx.js' type='text/javascript'%3E%3C/script%3E")); :javascript | RPXNOW.overlay = true; | RPXNOW.language_preference = 'en'; body a.rpxnow(onclick='return false;', href="https://" + locals.app_name + ".rpxnow.com/openid/v2/signin?token_url=http%3A%2F%2F" + locals.host + "%2Frpx") login

Now lets fire up the demo.

$ node app.js

If you open a browser up and go to http://localhost:8080 you should see a link "login" and if you click on it you should see the Janrain popup. We are almost done and all we need to do is wire up the callback so Janrain can pass us the identiy and we can validate it and sign in the user. To do this we need to write the RPX callback and we will do that next. Just stop node running and edit the app.js file and replace the app.post with the code below.

app.post('/rpx', connect.bodyDecoder(), function(req, res){ // STEP1: Get the token sent by the widget // and validate it. var token = req.body.token; if(!token || token.length != 40 ) { res.send('Bad Token!'); return; } // STEP2: get the auth info using the Janrain API. // Janrain will validate the request and return the profile // details using a secure channel. engageAPI.authInfo(token, true, function(err, data) { if(err) { res.send(err.message + ( data ? (' -- ' + JSON.stringify(data)) : '')); return; } /* check if we assigned a unique identifier to this user and if so they user is a return user if not we need to create a account in our user management system. You can also make other API calls to get the user contact list, friends, etc. if(data.profile.primaryKey) { signInUser(data.profile.primaryKey); } else { var uid = create a new user in your management system. engageAPI.map(data.profile.identifier, uid, function(err, data) { if(err) {res.send(err.message); return;} signInUser(uid); }); } */ res.send(JSON.stringify(data)); }); });

Just write your own signInUser function. This function will login the user into your site. This can be done using cookies or a variety of techniques. Notice that we also have sample code that lets you map the user to your user management system. So next time Janrain identifies the user it will identify them with your unique ID not the provider's ID. Its that simple now you can let your user sign in and register with any provider. Check out all the data that comes back from the authInfo call at Janrain API Docs. 

If you look at the view you will see I am manually creating the href that starts the Janrain popup. The rpx.js script helps wire-up all the magical UI. It looks for an href on the page with a css class "rpxnow"and uses the href to tell the widget what Janrain account to link to and what is the callback url. Looking at the url you will see the format is {application name}.rpxnow.com/openid/v2/signin and has a query string "token_url" that tells the widget where to POST the callback hook. If you remember in the Janrain wizard where we setup the providers their was a tab for "Get the Widget" on this tab it create sample code that you can cut/copy/paste but here in the example we just hide it into the template.