passport-azure-ad

What is passport-azure-ad?

The passport-azure-ad npm package provides authentication and authorization strategies for integrating with Microsoft Azure Active Directory (Azure AD) using the Passport.js framework. It supports various authentication flows including OAuth2, OpenID Connect, and SAML.

What are passport-azure-ad's main functionalities?

OAuth2 Bearer Strategy

This feature allows you to authenticate users using OAuth2 Bearer tokens issued by Azure AD. The code sample demonstrates how to configure and use the BearerStrategy with Passport.js.

const passport = require('passport');
const BearerStrategy = require('passport-azure-ad').BearerStrategy;

const options = {
  identityMetadata: 'https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration',
  clientID: 'your-client-id',
  validateIssuer: true,
  issuer: 'https://sts.windows.net/{tenant-id}/',
  passReqToCallback: false
};

passport.use(new BearerStrategy(options, (token, done) => {
  // Token validation logic
  done(null, token);
}));

OIDC Strategy

This feature allows you to authenticate users using OpenID Connect (OIDC) with Azure AD. The code sample demonstrates how to configure and use the OIDCStrategy with Passport.js.

const passport = require('passport');
const OIDCStrategy = require('passport-azure-ad').OIDCStrategy;

const options = {
  identityMetadata: 'https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration',
  clientID: 'your-client-id',
  responseType: 'code id_token',
  responseMode: 'form_post',
  redirectUrl: 'http://localhost:3000/auth/openid/return',
  allowHttpForRedirectUrl: true,
  clientSecret: 'your-client-secret',
  validateIssuer: true,
  passReqToCallback: false
};

passport.use(new OIDCStrategy(options, (iss, sub, profile, accessToken, refreshToken, done) => {
  // User profile validation logic
  done(null, profile);
}));

SAML Strategy

This feature allows you to authenticate users using SAML with Azure AD. The code sample demonstrates how to configure and use the SamlStrategy with Passport.js.

const passport = require('passport');
const SamlStrategy = require('passport-azure-ad').SamlStrategy;

const options = {
  identityMetadata: 'https://login.microsoftonline.com/{tenant}/federationmetadata/2007-06/federationmetadata.xml',
  loginCallback: 'http://localhost:3000/auth/saml/callback',
  issuer: 'your-issuer',
  audience: 'your-audience',
  cert: 'your-certificate',
  privateCert: 'your-private-certificate'
};

passport.use(new SamlStrategy(options, (profile, done) => {
  // User profile validation logic
  done(null, profile);
}));

Other packages similar to passport-azure-ad

passport-google-oauth20

The passport-google-oauth20 package provides OAuth 2.0 authentication strategy for Google. It allows you to authenticate users using their Google accounts. Compared to passport-azure-ad, it is specific to Google OAuth 2.0 and does not support other authentication flows like SAML or OIDC.

passport-saml

The passport-saml package provides SAML authentication strategy for Passport.js. It allows you to authenticate users using SAML identity providers. Compared to passport-azure-ad, it is more generic and can be used with any SAML identity provider, not just Azure AD.

passport-oauth2

The passport-oauth2 package provides a generic OAuth 2.0 authentication strategy for Passport.js. It allows you to authenticate users using any OAuth 2.0 provider. Compared to passport-azure-ad, it is more flexible but requires more configuration to work with specific providers like Azure AD.

README

Microsoft Azure Active Directory Passport.js Plug-In

=============

passport-azure-ad is a collection of Passport Strategies to help you integrate with Azure Active Directory. It includes OpenID Connect, WS-Federation, and SAML-P authentication and authorization. These providers let you integrate your Node app with Microsoft Azure AD so you can use its many features, including web single sign-on (WebSSO), Endpoint Protection with OAuth, and JWT token issuance and validation.

passport-azure-ad has been tested to work with both Microsoft Azure Active Directory and with Microsoft Active Directory Federation Services.

Security Vulnerability in Versions < 1.4.6 and 2.0.0

passport-azure-ad has a known security vulnerability affecting versions <1.4.6 and 2.0.0. Please update to >=1.4.6 or >=2.0.1 immediately. For more details, see the security notice.

Versions

Current version - 2.0.3
Minimum recommended version - 1.4.6
You can find the changes for each version in the change log.

Contribution History

Installation

$ npm install passport-azure-ad

Usage

Configure strategy

This sample uses the OAuth2Bearer Strategy:

// We pass these options in to the ODICBearerStrategy.

var options = {
    // The URL of the metadata document for your app. We will put the keys for token validation from the URL found in the jwks_uri tag of the in the metadata.
    identityMetadata: config.creds.identityMetadata,
    issuer: config.creds.issuer,
    audience: config.creds.audience

};

var bearerStrategy = new BearerStrategy(options,
    function(token, done) {
        log.info('verifying the user');
        log.info(token, 'was the token retreived');
        findById(token.sub, function(err, user) {
            if (err) {
                return done(err);
            }
            if (!user) {
                // "Auto-registration"
                log.info('User was added automatically as they were new. Their sub is: ', token.sub);
                users.push(token);
                owner = token.sub;
                return done(null, token);
            }
            owner = token.sub;
            return done(null, user, token);
        });
    }
);

This sample uses the OIDCStrategy:

passport.use(new OIDCStrategy({
    callbackURL: config.creds.returnURL,
    realm: config.creds.realm,
    clientID: config.creds.clientID,
    clientSecret: config.creds.clientSecret,
    oidcIssuer: config.creds.issuer,
    identityMetadata: config.creds.identityMetadata,
    skipUserProfile: config.creds.skipUserProfile,
    responseType: config.creds.responseType,
    responseMode: config.creds.responseMode
  },
  function(iss, sub, profile, accessToken, refreshToken, done) {
    if (!profile.email) {
      return done(new Error("No email found"), null);
    }
    // asynchronous verification, for effect...
    process.nextTick(function () {
      findByEmail(profile.email, function(err, user) {
        if (err) {
          return done(err);
        }
        if (!user) {
          // "Auto-registration"
          users.push(profile);
          return done(null, profile);
        }
        return done(null, user);
      });
    });
  }
));

Provide the authentication callback for OIDCStrategy

To complete the sample, provide a route that corresponds to the path configuration parameter that is sent to the strategy:

app.get('/login', 
  passport.authenticate('azuread-openidconnect', { failureRedirect: '/login' }),
  function(req, res) {
    log.info('Login was called in the Sample');
    res.redirect('/');
});

// POST /auth/openid/return
//   Use passport.authenticate() as route middleware to authenticate the
//   request.  If authentication fails, the user will be redirected back to the
//   login page.  Otherwise, the primary route function function will be called,
//   which, in this example, will redirect the user to the home page.
app.post('/auth/openid/return',
  passport.authenticate('azuread-openidconnect', { failureRedirect: '/login' }),
  function(req, res) {
    
    res.redirect('/');
  });

  app.get('/logout', function(req, res){
  req.logout();
  res.redirect('/');
});

Test

In the library root folder, type the following command to install the dependency packages:

    $ npm install

Then type the following command to run tests:

    $ npm test

Tests will run automatically and in the terminal you can see how many tests are passing/failing. More details can be found here.

Samples and Documentation

We provide a full suite of sample applications and documentation on GitHub to help you get started with learning the Azure Identity system. This includes tutorials for native clients such as Windows, Windows Phone, iOS, OSX, Android, and Linux. We also provide full walkthroughs for authentication flows such as OAuth2, OpenID Connect, Graph API, and other awesome features.

Azure Identity samples for this plug-in is here: https://github.com/Azure-Samples/active-directory-node-webapp-openidconnect

Community Help and Support

We leverage Stack Overflow to work with the community on supporting Azure Active Directory and its SDKs, including this one. We highly recommend you ask your questions on Stack Overflow (we're all on there!) Also browser existing issues to see if someone has had your question before.

We recommend you use the "adal" tag so we can see it! Here is the latest Q&A on Stack Overflow for ADAL: http://stackoverflow.com/questions/tagged/adal

Security Reporting

If you find a security issue with our libraries or services please report it to [e-mail] with as much detail as possible. Your submission may be eligible for a bounty through the Microsoft Bounty program. Please do not post security issues to GitHub Issues or any other public site. We will contact you shortly upon receiving the information. We encourage you to get notifications of when security incidents occur by visiting this page and subscribing to Security Advisory Alerts.

Contributing

All code is licensed under the MIT license and we triage actively on GitHub. We enthusiastically welcome contributions and feedback. You can clone the repo and start contributing now.

More details about contribution

Versions

Please check the releases for updates.

Acknowledgements

The code is based on Henri Bergius's passport-saml library and Matias Woloski's passport-wsfed-saml2 library as well as Kiyofumi Kondoh's passport-openid-google.

License

Copyright (c) Microsoft Corp. All rights reserved. Licensed under the MIT License;

We Value and Adhere to the Microsoft Open Source Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [e-mail] with any additional questions or comments.