Azure AD authentication module for express-based node.js apps
Last updated 10 months ago by tpain323 .
Apache-2.0 · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install @jet.com/express-ad 
SYNC missed versions from official npm registry.

Microsoft Active Directory Authentication Module for Express-based node apps


  1. First install this package in your electrode app

    yarn add @jet.com/express-ad
  2. Add the following in your express app's /config folder. Make sure to import the express-ad module:

        "authentication": {
            "module": "express-ad",
            "options: { 
                "host": XXX,
                "clientID": YYY,
                "clientSecret": ZZZ

Note that host, clientID and clientSecret are required properties. See the end of this document for a list of other optional properties and their default values.

  1. In your /src/server/express-server.js file, add the following helper method to inject authentication into the express pipeline:
const setUpAuth = () => new Promise((resolve, reject) => {
    const authModule = require((defaultConfig.$("authentication.module")));
    const authConfig = defaultConfig.$("authentication.options");
    const authDisabled = defaultConfig.$('authentication.disabled') || false;

    if (!authDisabled) {
        const authSetup = authModule(authConfig);

and then in the express server function, add then(setUpAuth) right before the setRouteHandler call:


Authentication flow

On page load

When user opens a page that falls under protected path mask, the module will check if user is authenticated. If so, the page will open as intended. Otherwise, the user will be redirected to 'https://login.microsoftonline.com' website in order to sign into the application. After signing in the user will be redirected to the configured redirectUrlPath.

On ajax call (e.g. API call)

If user is not authenticated at the time of request and refresh_token was never obtained before, the module will return 401 with Location header set to login page url. Otherwise the module will check if access_token was not expired. If it was expired, then the module will obtain a new one using the existing refresh token (which is valid for 90 days) and pass it to the api. The user won't notice anything except a small lag due to an additional request being made to https://login.microsoftonline.com. Once the access_token is renewed, all API calls will go through until it's expired again.

Cookie storage

The module stores both access_token and refresh_token in cookies, on user's machine. Both of these tokens are encrypted before being sent to the client. On each request to server the module will decrypt these cookies. Decryption affect each request and takes around 20 microseconds on a Quad Core 2.8 GHz Intel Core i7. Encryption affects token refreshes and in average takes around few hundreds microseconds on the same CPU.

Configuration Properties


The path to be protected by authentication module.

Default: /*


Required. The client ID of your application in AAD (Azure Active Directory)


Required. Must be a https url string, unless you set allowHttpForRedirectUrl to true (which it is by default). Production environments should always use https for redirectUrl.


Required. The application secret that you created in the app registration portal for your app.


Tells the module when access_token should be considered expired. This value will be substracted from the token's expires_in property returned from Azure AD. Basically, it allows to consider the token as expired some time in advance before it will expire on Azure.

Default: 600000 // 10 minutes


Specifies lifetime of refresh_token.

Default: 7776000000 // 90 days


The metadata endpoint provided by the Microsoft Identity Portal that provides the keys and other important information at runtime

Default: 'https://login.microsoftonline.com/jetecommerce.onmicrosoft.com/.well-known/openid-configuration'


Must be 'code', 'code id_token', 'id_token code' or 'id_token'. For login only flows you can use 'id_token'; if you want access_token, use 'code', 'code id_token' or 'id_token code'.

Default: 'id_token'


Must be 'query' or 'form_post'. This is how you get code or id_token back. 'form_post' is recommended for all scenarios.

Default: 'form_post'


This is the reply URL path registered in AAD for your app.

Default: '/auth/openid/return'


Required to set to true if you want to use http url for redirectUrl like http://localhost:3000

Default: true


Whether you want to use req as the first parameter in the verify callback.

Default: false


State/nonce cookie expiration in seconds

Default: 600


Max amount of state/nonce cookie you want to keep (cookie is deleted after validation so this can be very small)

Default: 5


Use cookie, not session

Default: true


Encrypt/decrypt key and iv. Please manually set your cookieEncryptionKeys in setting.js. We recommend that you implement a secure secrets management tool such as hashicorp vault instead of hardcoding security values or other secrets in your configuration files.

Default: [ { key: '', 'iv': '' }]


The secret used to sign the JWTs and the cookies that hold them

Default: 'Going down to queso town'


Time in ms before expiration to renew the JWT.

Default: 1e3 * 60 * 10 - 10 minutes

Current Tags

  • 3.0.2                                ...           latest (10 months ago)

2 Versions

  • 3.0.2                                ...           10 months ago
  • 3.0.1                                ...           2 years ago
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 2
Last Month 3
Dependencies (8)
Dev Dependencies (0)
Dependents (0)

Copyright 2014 - 2016 © taobao.org |