cidp-express-sdk

CIDP NODE SDK

A library for application built using node js. Is used to integrate with identity server for authentication and authorization.

Features:

• node library
• integration tests for the library
• a demo application using express web framework that consumes the library
• a demo application using kraken web framework that consumes the library

Common tasks are present as npm scripts:

• npm run build to build the library
• npm run start:express to run a server with the demo app using express
• npm run start:kraken to run a server with the demo app using kraken
• npm run integration run integration tests

In UI management make sure client exists:

• clientId:node_client
• scopes:openid profile
• grantType:authorization_code
• tenant:CIDP
• redirectUri:http://localhost:6100/oidc
• postLogoutUri:http://localhost:6100/
• cors:http://localhost:6100

What's in the CIDP NODE SDK?

demo/
   └── express
   └── kraken
lib/
   ├── index.ts
   └── services/
        └── cidpService.js
        └── userService.js

Files inside lib/ "belong" to library, while demo/ contains demo applications that loads the library.

Libraries do not run by themselves, so it's very useful to have this "demo" apps while developing to see how your library would look like to consumers.

The build step

You can build the library by running npm run build. This will generate a dist/ directory with all the entry points described above.

All the logic for creating the build can be found in ./gulpfile.js. It consists of:

• Identify any security vulnerabilities
• Clean dist folder.
• Transpile with babel.
• Copy the source to dist folder.
• Deploy to github.

Testing

The CIDP NODE SDK includes a directory called demo\express\e2e containing end-to-end tests to verify it works.

To run the integration tests, do npm run integration which does the following:

• Install dependencies.
• Build library.
• Enter the demo\express app's directory.
• Test the app using Protractor testing framework.

Using in the node application

Install node package in your app : npm install cidp-express-sdk --save

Import the module in your app. Set the oidcSettings properties to match the server configuration.

var express = require('express');
var router = express.Router();
var cidp = require('cidp-express-sdk');

var app = express();

var oidcSettings = {
  authority_url: "https://demo.identityserver.io",
  client_id: "server.code",
  client_secret: "secret",
  response_type: "code",
  scopes: "openid profile email api offline_access",
  session_cookie_name:"sessionCookieName" // if not specified the default name is "identity"
  ui_locales:"fr-FR", // used for login page localization, by default en-GB culture is used
  redirect_uri: "/profile",
  post_logout_redirect_uri: "/",
  error_url: "/error?errMsg=",
  clock_tolerance: 30 //(default 60) It is possible the RP or OP environment has a system clock skew, to set a clock tolerance (in seconds)
  onSignOutCallback:function(){} // callback function executed on signle sign out event. When user is signed out from CIDP the node client is notified and current user session is removed. We can use this callback to perform any other clean up.
  httpOptions: // optional http options for http requests
  {
    "rejectUnauthorized": false
  },
  custom_params: [{ key: "firstname", value: "first" },{ key: "lastname", value: "last" }] // additional query string key used to send custom data to CIDP. In the query string it will be represented as ?firstname=first&lastname=last
  //The custom param will not be available directly in query string on login page, there is a redirectUrl that contains custom params
  //Following javascript code can be used to read custom_params on CIDP side:
  //let paramsString = decodeURIComponent(window.location.search);
  //let searchParams = new URLSearchParams(paramsString);
  //searchParams.get('firstname');
  //searchParams.get('lastname')
};

Use library middlewares to setup session and connect to CIDP(Collinson Identity Provider) server:

// use Cidp middleware. The app wide middleware that:
// 1.Connects to CIDP server
// 2.Creates identity cookie session
// 3.Handles authentication callbacks

app.use(cidp.cidpMiddleware(oidcSettings));

Use library middlewares to handle login, logout requests:

//isAuthenticated route middleware allows only authenticated users to access a resource
//isAuthenticated() accept optional settings param in case you need to ovveride ui_locales,redirect_uri
router.post('/login', cidp.isAuthenticated(ui_locales:'fr-FR'}));


router.post('/logout',cidp.signOut());

//on success, CIDP redirect to oidcSettings.redirect_uri with identity information attached on request
router.get('/profile',cidp.isAuthenticated({ui_locales:'fr-FR'}), function (req, res, next) {
  var identity = req.identity; // use session_cookie_name if provided in oidcSettings
  // Identity contains information about resonse_type like identity token and access token
  // access_token:"eyJhbGciOiJSUzI1NiIsImtpZC"
  // id_token:"eyJhbGciOiJSUzI1NiIsImtpZC"
  // token_type:"Bearer",
  // expires_at:1500561170,
  // ....
  }

//on error, CIDP redirect to oidcSettings.error_url with errMsg in query string
router.get('/error*', function (req, res, next) {
  var message = req.query.errMsg;
  res.render('error', {
    message: message,
    error: {}
  });
});

//redirect user to CIDP change password page
//returnUrl - optional relative path to return after changing the password, if not defined, the oidcSetting.redirect_uri will be used as default
router.get('/changePassword',cidp.changePassword(returnUrl));

//redirect user to CIDP Login History page where the user can track his Login-Logout information
router.get('/loginHistory',cidp.loginHistory(returnUrl));

Cidp service also provides a user helper cidp.getUser(req.identity) with following properties available:

• expired:boolean - check if token not expired
• authenticated:boolean - check if token exist and not expired
• identityClaims:keyvaluepair - get list of claims from identity token
• accessClaims:keyvaluepair - get list of claims from access token