Skip to content

Latest commit

 

History

History
 
 

msal-node

README.md

Microsoft Authentication Library for Node (msal-node)

npm versionnpm versionCoverage Status

Getting Started AAD Docs Library Reference

Currently msal-node is under development, please track the project progress here. This documentation is also in progress and will be changing as we release our alpha patches. We do not recommend using this in a production environment yet.

  1. About
  2. FAQ
  3. Releases
  4. Prerequisites
  5. Installation
  6. Usage
  7. Samples
  8. Build Library
  9. Security Reporting
  10. License
  11. Code of Conduct

About

MSAL Node enables applications to authenticate users using Azure AD work and school accounts (AAD), Microsoft personal accounts (MSA) and social identity providers like Facebook, Google, LinkedIn, Microsoft accounts, etc. through Azure AD B2C service. It also enables your app to get tokens to access Microsoft Cloud services such as Microsoft Graph.

OAuth2.0 grant types supported:

The current alpha version supports the following ways of acquiring tokens:

Public Client:

Confidential Client:

[Coming Soon] In the future we plan to add support for:

More details on different grant types supported by Microsoft authentication libraries in general can be found here.

Scenarios supported:

The scenarios supported with this library are:

  • Desktop app that calls web APIs
  • Web app that calls web APIs
  • Web APIs that call web APIs
  • Daemon apps

More details on scenarios and the authentication flows that map to each of them can be found here.

FAQ

See here.

Prerequisites

Before using @azure/msal-node you will need to register your app in the azure portal:

Installation

Via NPM:

npm install @azure/msal-node

Usage

MSAL basics

Samples

There are multiple samples included in the repository that use MSAL Node to acquire tokens. These samples are currently used for manual testing, and are not meant to be a reference of best practices, therefore use judgement and do not blindly copy this code to any production applications.

  • auth-code: Express app using OAuth2.0 authorization code flow.
  • device-code: Command line app using OAuth 2.0 device code flow.
  • refresh-token: Command line app using OAuth 2.0 refresh flow.
  • silent-flow: Express app using OAuth2.0 authorization code flow to acquire a token and store in the token cache, and silent flow to use tokens in the token cache.
  • client-credentials: Daemon app using Oauth 2.0 client credential grant to acquire a token.
  • on-behalf-of: Web application uses Oauth 2.0 auth code flow to acquire a token for a Web API. The web API validates the token, and calls Microsoft Graph on behalf of the user who authenticated in the web application.
  • msal-node-extensions: Uses authorization code flow to acquire tokens and the msal-extensions library to write the MSAL in-memory token cache to disk.

Build and Test

  • If you don't have lerna installed, run npm install -g lerna
  • Run lerna bootstrap from anywhere within microsoft-authentication-library-for-js.git.
  • Navigate to microsoft-authentication-library-for-js/lib/msal-common and run npm run build
  • Navigate to microsoft-authentication-library-for-js/lib/msal-node and run npm run build
// to link msal-node and msal-common packages
lerna bootstrap

// Change to the msal-node package directory
cd lib/msal-common/

// To run build only for node package
npm run build

// Change to the msal-node package directory
cd lib/msal-node/

// To run build only for node package
npm run build

Local Development

Below is a list of commands you will probably find useful:

npm run build:modules:watch

Runs the project in development/watch mode. Your project will be rebuilt upon changes. TSDX has a special logger for you convenience. Error messages are pretty printed and formatted for compatibility VS Code's Problems tab. The library will be rebuilt if you make edits.

npm run build

Bundles the package to the dist folder. The package is optimized and bundled with Rollup into multiple formats (CommonJS, UMD, and ES Module).

lerna bootstrap

If you are running the project in development/watch mode, or have made changes in msal-common and need them reflecting across the project, please run lerna bootstrap to link all the symbols. Please note that npm install will unlink all the code, hence it is advised to run lerna bootstrap post installation.

npm run lint

Runs eslint with Prettier

npm test, npm run test:coverage, npm run test:watch

Runs the test watcher (Jest) in an interactive mode. By default, runs tests related to files changed since the last commit. Generate code coverage by adding the flag --coverage. No additional setup needed. Jest can collect code coverage information from entire projects, including untested files.

Security Reporting

If you find a security issue with our libraries or services please report it to [email protected] 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.

License

Copyright (c) Microsoft Corporation. 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 [email protected] with any additional questions or comments.