node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »



Build Status

Lightweight ws-federation middleware for express.js (using JSON Web Tokens), for use with Windows Azure ACS. The goal was to try and implement the bare minimum to work with ws-federation using the Passive protocol and to try to limit the number of dependencies.


$ npm install node-wsfed --save

Configure node-wsfed

In order to use the library, you will need to setup a "namespace" in Windows Azure ACS and then configure the corresponding options for the library.

ACS Configuration

When setting up a Relying Party in ACS, the important bits are as follows:

  • Realm: this needs to be unique within your namespace and is used by ACS to determine which Relying Party to authenticate with, I usually use a urn, e.g. urn:my-realm.
  • Return Url: this is where ACS will post the token after authentication. This should correspond to the wsfed endpoints configured below (ends with /signin). This is different from the wctx that can be used to redirect a user to a deep link on your site after autheticating.
  • Rules: start with a simple passthrough rule to begin with, you can then look into the claims that are returned and tweak as appropriate.

node-wsfed Configuration

You can configure the options for node-wsfed like so:

// ws-federation options
var options = {
    realm: '[Enter the realm/audience]',
    namespace: '[Enter ACS namespace here]',
    key: '[Enter security key here]',
    expiry: 20,
    ip: 'Live', // Using the Windows Live Identity Provider
    bunyan: { name: 'wsfed' } // Use the internal bunyan logger

The options are relatively straighforward and match up with those settings in ACS:

  • realm: should match the realm set up in ACS for your relying party.
  • namespace: this is the root Access Control Namespace that you create in the Azure Management portal.
  • key: this is either the symmetric key that you create/assign as the Token Signing Key, or is the public key that corresponds with the X.509 Certificate that you uploaded for token signing.
  • expiry: the number of minutes that you would like your token to be valid - this should be in line with the expiry set for the token in your Relying Party.
  • ip: this is used to select the identity provider to use and determines the URL to redirect to for authentication.
  • bunyan: to configure bunyan logging, enter the normal bunyan configuration here; if you don't put any bunyan settings, logging will be disabled.
  • logger: if you want to use your own logger, add a field pointing to it. The logging assumes bunyan's interface.
  • loginUrl: this should be a function that takes a URL to return to (deep link/current page) and returns the URL to be redirected to for authentication.

Augment the Options with acs-login-url

The following code demonstrates how to use the acs-login-url library to provide custom links to Windows Live ID or Facebook.

var loginUrl = require('acs-login-url');
// Initialise the ACS Login URL
options = loginUrl.initialize(options);

Configure Express.js App to Use the library

Finally, you will have to use two middleware functions to setup ws-federation.

var wsfed = require('node-wsfed'),
    express = require('express');
var app = express();
// Add ws-federation endpoints
// Configure site to use federated security
// Configure secure area processing
app.get('/secure', wsfed.requireAuthentication(options), 
    function(req, res) {
        body = 'You are authenticated and in the secure area!';
        body += '<br/>Identity Provider: ' +;
        body += '<br/>ID:' +;

In this sample, the wsfed.endpoints function configures two endpoints:

  • /signin: this should match the Relying Party Return Url. This extracts a token received from ACS and adds it as a fedAuth cookie for further processing.
  • /signout: this is an optional endpoint that is only really supported for Windows Live. Currently acs-login-url doesn't support the logout URL (yet).

The wsfed.enableAuthentication function adds middleware to process fedAuth cookies and verify the contents. This allows processing of claims information in all areas of the site (if a user is authenticated).

Finally, the wsfed.requireAuthentication function forces un-authenticated users to be automatically redirected to the Identity Provider for authentication (thus protecting any secure areas).


See the example Express.js web server in the code and the tests to get a better idea for how to use the library.


As this is a simple implementation, but the following may be in future updates:

  • Improve the XML Namespace handling, either by updating the xml library used, or maybe even dumbing it down and just "grep'ing" the relevant bits out and not using an xml library.
  • Provide the ability to plug-in other token handling libraries.