@kollorg/rerum-quaerat-et NPM

Passport-microsoft

Passport strategy for authenticating with Microsoft Graph using the OAuth 2.0 API.

This module lets you authenticate using Microsoft, in your Node.js applications.
By plugging into Passport, Microsoft authentication can be easily and unobtrusively integrated into any application or framework that supports Connect-style middleware, including Express.

Install

Install via npm

$ npm install @kollorg/rerum-quaerat-et

Usage

Configure Strategy

The Microsoft authentication strategy authenticates users using a Microsoft account and OAuth 2.0 tokens. The strategy requires a verify callback, which accepts these credentials and calls done providing a user, as well as options specifying a client ID, client secret, and callback URL.

The consumer key and secret are obtained by creating an application at Microsoft's developer site.

    var MicrosoftStrategy = require('@kollorg/rerum-quaerat-et').Strategy;
    passport.use(new MicrosoftStrategy({
        // Standard OAuth2 options
        clientID: 'applicationidfrommicrosoft',
        clientSecret: 'applicationsecretfrommicrosoft',
        callbackURL: "http://localhost:3000/auth/microsoft/callback",
        scope: ['user.read'],

        // Microsoft specific options

        // [Optional] The tenant ID for the application. Defaults to 'common'. 
        // Used to construct the authorizationURL and tokenURL
        tenant: 'common',

        // [Optional] The authorization URL. Defaults to `https://login.microsoftonline.com/${tenant}/oauth2/v2.0/authorize`
        authorizationURL: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',

        // [Optional] The token URL. Defaults to `https://login.microsoftonline.com/${tenant}/oauth2/v2.0/token`
        tokenURL: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',

        // [Optional] The Microsoft Graph API version (e.g., 'v1.0', 'beta'). Defaults to 'v1.0'.
        graphApiVersion: 'v1.0',

        // [Optional] If true, will push the User Principal Name into the `emails` array in the Passport.js profile. Defaults to false.
        addUPNAsEmail: false,
        
        // [Optional] The Microsoft Graph API Entry Point, defaults to https://graph.microsoft.com. Configure this if you are using Azure China or other regional version.
        apiEntryPoint: 'https://graph.microsoft.com',
      },
      function(accessToken, refreshToken, profile, done) {
        User.findOrCreate({ userId: profile.id }, function (err, user) {
          return done(err, user);
        });
      }
    ));

Authenticate Requests

Use passport.authenticate(), specifying the 'microsoft' strategy, to authenticate requests.

For example, as route middleware in an Express application:

    app.get('/auth/microsoft',
      passport.authenticate('microsoft', {
        // Optionally define any authentication parameters here
        // For example, the ones in https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow
        
        prompt: 'select_account',
      }));

    app.get('/auth/microsoft/callback', 
      passport.authenticate('microsoft', { failureRedirect: '/login' }),
      function(req, res) {
        // Successful authentication, redirect home.
        res.redirect('/');
      });