Quick start: Node.js web apps

Video tutorial

Check out the following video to see how you can use App ID to protect a simple Node.js web application. All the information that is covered in the video can also be found in written form on this page.

Don't have an app that you can try out the flow with? No problem! App ID provides a simple Node.js web sample app.

Before you begin

Before you get started with App ID in your Node.js web applications, you must have the following prerequisites.

• An instance of the App ID service
• NPM version 4+
• Node version 6+

This SDK uses the log4js package for logging. By default, the logging level is set to info. To create your own logging configuration, add a log4js.json file and set the process.env.LOG4JS_CONFIG environment variable to your JSON file.

Register your redirect URI

A redirect URI is the callback endpoint of your app. During the sign-in flow, App ID validates the URIs before clients are allowed to participate in the authorization workflow, which helps to prevent phishing attacks and grant code leakage. By registering your URI, you're telling App ID that the URI is trusted and it's OK to redirect your users.

1. Click Manage Authentications > Authentication Settings.

2. In the Add web redirect URI field, type the URI. Each URI must begin with http:// or https:// and must include the full path, including any query parameters for the redirect to be successful.

3. Click the + symbol in the Add web redirect URIs box.

4. Repeat steps one through three until all possible URIs are added to your list.

Obtain your credentials

You can obtain your credentials in one of two ways.

• By navigating to the Applications tab of the App ID dashboard. If you don't already have one, you can click Add application to create a new one.

• By making a POST request to the /management/v4/<tenantID>/applications endpoint.

  Request format:
  
  ```sh {: codeblock}
  curl -X POST \  https://us-south.appid.cloud.ibm.com/management/v4/39a37f57-a227-4bfe-a044-93b6e6060b61/applications/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <IAMToken>' \
  -d '{"name": "ApplicationName"}'
  ```
  Example response:
  
  ```json {: screen}
  {
    "clientId": "xxxxx-34a4-4c5e-b34d-d12cc811c86d",
    "tenantId": "xxxxx-9b1f-433e-9d46-0a5521f2b1c4",
    "secret": "ZDk5YWZkYmYt*******",
    "name": "app1",
    "oAuthServerUrl": "https://us-south.appid.cloud.ibm.com/oauth/v4/xxxxx-9b1f-433e-9d46-0a5521f2b1c4",
    "profilesUrl": "https://us-south.appid.cloud.ibm.com",
    "discoveryEndpoint": "https://us-south.appid.cloud.ibm.com/oauth/v4/xxxxxx-9b1f-433e-9d46-0a5521f2b1c4/.well-known/openid-configuration"
  }
  ```
  

Initialize the SDK

The easiest way to work with App ID is to take advantage of the Node.JS SDK.

1. By using the command line, change into the directory that contains your Node.js application.

2. Install the following NPM requirements.

   npm install --save express express-session passport log4js pug
   

3. Install the App ID service.

   npm install --save ibmcloud-appid
   

4. Add the following requirements to your server.js file.

   const express = require('express'); 								// https://www.npmjs.com/package/express
   const log4js = require('log4js');                                   // https://www.npmjs.com/package/log4js
   const session = require('express-session');							// https://www.npmjs.com/package/express-session
   const passport = require('passport');								// https://www.npmjs.com/package/passport
   const WebAppStrategy = require('ibmcloud-appid').WebAppStrategy;	// https://www.npmjs.com/package/ibmcloud-appid
   

5. Set up your application to use express-session middleware by using the credentials that you obtained in step 1. You can choose to format your redirect URI in one of two ways. Manually, by using a new WebAppStrategy({redirectUri: "...."}) or by setting the value as an environment variable as shown in the example code.

   const app = express();
   const logger = log4js.getLogger("testApp");
   app.use(session({
      secret: '123456',
      resave: true,
      saveUninitialized: true
   }));
   app.use(passport.initialize());
   app.use(passport.session());
   passport.serializeUser((user, cb) => cb(null, user));
   passport.deserializeUser((user, cb) => cb(null, user));
   passport.use(new WebAppStrategy({
      tenantId: "<tenantID>",
      clientId: "<clientID>",
      secret: "<secret>",
      oauthServerUrl: "<oauthServerURL>",
      redirectUri: "<redirectURI>"
   }));
   

   You must configure the middleware with the proper session storage for production environments. For more information, see the express.js docs.

Protect your application

Now that you have App ID installed, you're ready to protect your application. You can choose to protect your entire application or only specific resources by defining a web app strategy.

1. Configure the callback endpoint. The callback finishes the authorization process by retrieving access and identity tokens from App ID and redirecting the user to one of the following locations:

   • The original URL of the request that triggered the authentication, as persisted in the HTTP session as WebAppStrategy.ORIGINAL_URL.
   • Specifying a redirect in the event of a successful authentication.
   • The application root (/) as shown in the next step.

   app.get(CALLBACK_URL, passport.authenticate(WebAppStrategy.STRATEGY_NAME));
   

2. Set a sign-in endpoint that always redirects a browser to the Login Widget. Be sure to add a success redirect option so that you don't end up in an endless authentication loop.

   app.get('/appid/login', passport.authenticate(WebAppStrategy.STRATEGY_NAME, {
      successRedirect: '/',
      forceLogin: true
   }));
   

Personalize your app

You can pull information that is provided by your identity providers to personalize your app experience.

1. Configure your application to obtain user information. protected is a place holder variable that you can change to match the endpoint for your application.

   app.get("/protected_resource", passport.authenticate(WebAppStrategy.STRATEGY_NAME), function(req, res){
      res.json(req.user);
   });
   

   For example, in the sample application you can see how to obtain the users name to personalize your application.

   app.get('/api/user', (req, res) => {
      // console.log(req.session[WebAppStrategy.AUTH_CONTEXT]);
      res.json({
         user: {
               name: req.user.name
         }
      });
   });
   

Test your configuration

To test your authorization configuration, navigate to the URL that your server is listening on as defined in your application. Try signing in, try signing out. Ensure that the configuration is working as you expected.

When you're ready to move to the next step, you can try enabling multifactor authentication for Cloud Directory or adding custom attributes to further personalize your app.