Repository files navigation

This tutorial will show you how to integrate OAuth.io in your Node.js backend with a web front-end, using the server-side flow.

This tutorial uses both the OAuth.io front-end JavaScript SDK and the OAuth.io Node.js SDK.

This tutorial is based on a git repository that you can clone. You can follow the instructions by yourself or checkout each step of the tutorial, which are marked by tags in the git repository.

In this tutorial, we'll have to implement the server-side flow. This flow includes the following steps :

• The client asks the backend for a state token through GET
• The backend gives a state token
• The client runs the OAuth flow (popup or redirect) with that token
• OAuth.io responds with a code
• The client gives that code to the backend through POST
• The backend sends that code to OAuth.io and is given an access_token in return
• The backend saves the access_token in the session for future use from other endpoints

Running the server

Whenever you want to test the code, you can run the command :

$ node app.js

This will launch the server on the port3000. Then you can access the page of the tutorial in your browser. This page contains a login button and is supposed to display the user's basic information (name, email and avatar) once everything's finished.

You'll have to run it again everytime you change the backend.

You'll be able to see on the right which endpoint has already been coded or not.

The tutorial thus contains the following steps :

Part 1 : server-side code

• step-0 Getting the code (taggedstep-0)
• step-1 Initializing OAuth.io server-side (taggedstep-1)
• step-2 Adding a state token retrieval endpoint server-side (taggedstep-2)
• step-3 Adding an authentication endpoint server-side (taggedstep-3)
• step-4 Adding a request endpoint server-side (taggedstep-4)

Part 2 : client-side code

• step-5 Initializing OAuth.io client-side (taggedstep-5)
• step-6 Adding a call to retrieve the state token (taggedstep-6)
• step-7 Adding a call to authenticate the user (taggedstep-7)
• step-8 Adding a call to the request endpoint to get user info (taggedstep-8)

To be able to follow the tutorial, you need to be registered onoauth.io, and to have an application containing the providerFacebook, which must be set onserver-side flow.

In this part you'll have to get the code from our Github repository, and fill up gaps in it to complete the tutorial.

The project in the repository is a really simple webserver written in Node.js with expressjs, that serves a single static page. That page must allow a user to login through Facebook, retrieve his basic information (name, email, avatar), and finally display them on the page.

Everything that doesn't concern OAuth.io's integration has already been written to gain time.

Step 0 : Getting the code

To checkout tutorial Github repository, just run the following commands :

$ git clone https://github.com/oauthio/sdk-node-tutorial

To get the beginning point and start coding, checkout thestep-0 tag :

$ git checkout step-0

Then you need to runnpm install to install all the dependencies of the project.

$ npm install

You are now all set to follow the tutorial !

Step 1 : Initializing OAuth.io server-side

The first thing you need to do is to install the OAuth.io Node.js SDK and save it to the project's dependencies in the package.json :

$ npm install oauthio --save

Once that's done, you can initialize the framework server-side in theapp.js file. This file holds the whole server side to simplify things. The backend is based on express.js.

In that file, you'll find comments defining placeholders for the different steps of the tutorial.

Here we need to initialize the SDK. To do that, you need to note the key and secret of the app you want to use on OAuth.io (in that case an app with the providerFacebook).

Once you have them, take a look at theconfig.example.js. This file holds a configuration that we will use in the app.js file, and will enable us to store the key and secret efficiently.

You'll have to fill the gaps, and rename the file asconfig.js.

module.exports={key:'your_app_key',secret:'your_app_secret'};

Then, we will use this file to initialize the backend inapp.js. You will find in that file a comment placeholder for the initialization part :

/* Requiring the lib */// Require oauthio here (done in step-1)[...]/* Initialization */// Initialize oauthio here (done in step-1)

Replace the// Require oauthio here (done in step-1) comment with :

varoauth=require('oauthio');

Replace the// Initialize oauthio here comment with :

try{varconfig=require('./config.js');oauth.initialize(config.key,config.secret);}catch(e){console.log(e);}

That's it for step 1.

If you want to get the code from step 1, just run the following command:

$ git checkout step-1 --force

Note that any change you made will be discarded and replaced by the code shown in this tutorial (except for your config.js file, that is ignored and will remain there).

step-2 Adding a state token retrieval endpoint server-side

Now that the SDK is initialized, we need to add an endpoint to generate unique state tokens. In theapp.js file, you'll find the following placeholder :

// Add a .get endpoint for the state token here (/oauth/token) (done in step-2)

Replace it with the following code :

app.get('/oauth/token',function(req,res){// This generates a token and stores it in the sessionvartoken=oauth.generateStateToken(req);// This sends the token to the front-endres.json({token:token});});

That's it for step 2. If you want to get the code right away, just run the following command :

$ git checkout step-2 --force

step-3 Adding an authentication endpoint server-side

In this step we'll add an authentication endpoint in the backend so that the front-end can give it the code retrieved from OAuth.io.

Inapp.js, you'll find the following placeholder :

// Add a .post endpoint for the state token here (/oauth/signin) (done in step-3)

Just replace this comment with a POST endpoint :

app.post('/oauth/signin',function(req,res){varcode=req.body.code;// This sends the request to OAuth.io to get an access tokenoauth.auth('google',req.session,{code:code}).then(function(r){// Do something with r.access_token,// or r.get|post|put|delete|patch|me()// Or just send a success message :res.send(200,'Success');}).fail(function(e){// Handle an errorconsole.log(e);res.send(500,'An error occured');});});

That's it for step 3. If you want to get the code right away, just run the following commands :

$ git checkout step-3 --force

step-4 Adding a request endpoint server-side

In this step we'll add a final endpoint to our server which will allow the front-end to get information about the user.

Inapp.js you'll find the following placeholder :

// Add a .get endpoint for the request here (/me) (done in step-4)

Just replace this comment with the following code :

app.get('/me',function(req,res){// Here we first build a request object from the session with the auth method.// Then we perform a request using the .me() method.// This retrieves a unified object representing the authenticated user.// You could also use .get('/plus/v1/people/me') and map the// results to fields usable from the front-end// (which waits for the fields 'name', 'email' and 'avatar').oauth.auth('google',req.session).then(function(request_object){returnrequest_object.me();}).then(function(r){// r contains the response from OAuth.io's mapping of the// /plus/v1/people/me endpoint on googleres.json(r);}).fail(function(e){// Handle an errorconsole.log(e);res.send(500,'An error occured');});});

That's it for step 4. If you want to get the code right away, just run the following command :

$ git checkout step-4 --force

step-5 Initializing OAuth.io client-side

In this step we'll initialize the OAuth.io client-side JavaScript SDK. The SDK is already pointed by thepublic/index.html file. That file also points topublic/src/script.js where we'll put our code.

Open thepublic/src/script.js file. You'll find placeholders for each remaining step. You just have to fill functions that are called in the right order at the end of the file like this :

$('#login_button').click(function(){// called when the user clicks on the login button// calls your function to init the SDKinit_oauthio();// calls your function to retrieve a token from your endpointretrieve_token(function(err,token){// calls your function to launch a popup with the state token// and call the authentication endpoint with the resulting codeauthenticate(token,function(err){if(!err){// calls your function to call your request endpointretrieve_user_info(function(user_data){// fills elements in the page with the user info$('#name_box').html(user_data.name)$('#email_box').html(user_data.email);$('#img_box').attr('src',user_data.avatar);});}});})});});

In this step, you just have to fill the initialization function :

functioninit_oauthio(){// Add the code to initialize OAuth.io here}

Fill that function like this :

functioninit_oauthio(){OAuth.initialize(credentials.key);}

Thecredentials object has to be created first. Theindex.html page also points to asrc/credentials.js file in which we can setup that object. You need to rename thesrc/credentials.example.js tosrc/credentials.js and fill the key with your OAuth.io app key.

That's it for step 5. To get the code right away, just run the following command :

$ git clone step-5 --force

step-6 Adding a call to retrieve the state token

In this step you'll have to fill theretrieve_token function to get a token from the backend. This is a simple GET request, that we'll perform thanks to jQuery'sajax method.

Just replace the placeholder :

functionretrieve_token(callback){// Add the code to retrieve the state token here}

with this code :

functionretrieve_token(callback){$.ajax({url:'/oauth/token',success:function(data,status){callback(null,data.token);},error:function(data){callback(data);}});}

This allows us to handle the token from elsewhere in a callback. If an error occurs, we give it as a first argument tocallback.

That's it for step 6. If you want to get the code right away, just run the following command :

$ git checkout step-6 --force

step-7 Adding a call to authenticate the user

In this step, you need to add code to launch a popup from the OAuth.io client-side SDK, giving it the state token you got from the previous step.

Once the user will have logged in the provider's website and accepted the asked permissions, you'll be given a code from OAuth.io that will allow your backend to retrieve the provider access token.

You then need to send the code to the authentication endpoint you created in your backend previously.

To do all that, just replace the placeholder :

functionauthenticate(code,callback){// Add the code to authenticate the user here}

with :

functionauthenticate(token,callback){// Launches a popup showing the provider's website// for the user to login and to accept permissionsOAuth.popup('google',{state:token}).done(function(r){// Sends the code to the authentication endpoint// we created earlier$.ajax({url:'/oauth/signin',method:'POST',data:{code:r.code},success:function(data,status){// Here the user is authenticated.// We can call a request endpoint to retrieve information// in the callback.callback(null,data);},error:function(data){callback(data);}});}).fail(function(e){console.log(e);});}

That's it for step 7. If you want to get the code right away, just run the following command :

$ git checkout step-7 --force

step-8 Adding a call to the request endpoint to get user info

Now we can finally retrieve the user's information through our/me endpoint.

To do that, we need to make a GET request to that endpoint. Just replace the following placeholder :

functionretrieve_user_info(callback){// Add the code to perform a user request here}

with the following code :

functionretrieve_user_info(callback){$.ajax({url:'/me',success:function(data,status){// Here the callbaxk just gets the name, email and avatar field and// fills the elements of the page.callback(data);},error:function(data){console.log(data);}});}

That's it for step 8. If you want to get the code right away, just run the following command :

$ git checkout step-8 --force

Testing

You can now launch the server and access the page onlocalhost:3000. You can click on the login button, which will show the popup, retrieve your info and display it on the page.