| Getting Started | AAD Docs | Library Reference | Support | Samples |
|---|
MSAL for JavaScript enables client-side JavaScript web applications, running in a web browser, 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.
Installation
Via NPM:
npm install msal Via CDN:
<script type="text/javascript" src="https://alcdn.msauth.net/lib/1.4.17/js/msal.min.js"></script>
Complete details and best practices for CDN usage are available in our documentation.
What To Expect From This Library
Msal support on JavaScript is a collection of libraries. msal-core or just simply msal, is the framework agnostic core library. Once our core 1.x+ is stabilized, we are going to bring our msal-angular library with the latest 1.x improvements. We are planning to deprecate support for msal-angularjs based on usage trends of the framework and the library indicating increased adoption of Angular 2+ instead of Angular 1x. After our current libraries are up to standards, we will begin balancing new feature requests, with new platforms such as react and node.js.
Our goal is to communicate extremely well with the community and to take their opinions into account. We would like to get to a monthly minor release schedule, with patches coming as often as needed. The level of communication, planning, and granularity we want to get to will be a work in progress.
Please check our roadmap to see what we are working on and what we are tracking next.
OAuth 2.0 and the Implicit Flow
Msal implements the Implicit Grant Flow, as defined by the OAuth 2.0 protocol and is OpenID compliant.
Our goal is that the library abstracts enough of the protocol away so that you can get plug and play authentication, but it is important to know and understand the implicit flow from a security perspective. The implicit flow runs in the context of a web browser which cannot manage client secrets securely. It is optimized for single page apps and has one less hop between client and server so tokens are returned directly to the browser. These aspects make it naturally less secure. These security concerns are mitigated per standard practices such as- use of short lived tokens (and so no refresh tokens are returned), the library requiring a registered redirect URI for the app, library matching the request and response with a unique nonce and state parameter.
Cache Storage
We offer two methods of storage for Msal, localStorage and sessionStorage. Our recommendation is to use sessionStorage because it is more secure in storing tokens that are acquired by your users, but localStorage will give you Single Sign On accross tabs and user sessions. We encourge you to explore the options and make the best decision for your application.
forceRefresh to skip cache
If you would like to skip a cached token and go to the server, please pass in the boolean forceRefresh into the AuthenticationParameters object used to make a login / token request. WARNING: This should not be used by default, because of the performance impact on your application. Relying on the cache will give your users a better experience, and skipping it should only be used in scenarios where you know the current cached data does not have up to date information. Example: Admin tool to add roles to a user that needs to get a new token with updates roles.
Usage
The example below walks you through how to login a user and acquire a token to be used for Microsoft's Graph Api.
Prerequisites
Before using MSAL.js you will need to register an application in Azure AD to get a valid clientId for configuration, and to register the routes that your app will accept redirect traffic on.
1. Instantiate the UserAgentApplication
UserAgentApplication can be configured with a variety of different options, detailed in our Wiki, but the only required parameter is auth.clientId.
After instantiating your instance, if you plan on using a redirect flow in MSAL 1.2.x or earlier (loginRedirect and acquireTokenRedirect), you must register a callback handler using handleRedirectCallback(authCallback) where authCallback = function(AuthError, AuthResponse). As of MSAL 1.3.0 this is optional. The callback function is called after the authentication request is completed either successfully or with a failure. This is not required for the popup flows since they return promises.
import * as Msal from "msal"; // if using cdn version, 'Msal' will be available in the global scope const msalConfig = { auth: { clientId: 'your_client_id' } }; const msalInstance = new Msal.UserAgentApplication(msalConfig); msalInstance.handleRedirectCallback((error, response) => { // handle redirect response or error });
For details on the configuration options, read Initializing client applications with MSAL.js.
2. Login the user
Your app must login the user with either the loginPopup or the loginRedirect method to establish user context.
When the login methods are called and the authentication of the user is completed by the Azure AD service, an id token is returned which is used to identify the user with some basic information.
When you login a user, you can pass in scopes that the user can pre consent to on login, however this is not required. Please note that consenting to scopes on login, does not return an access_token for these scopes, but gives you the opportunity to obtain a token silently with these scopes passed in, with no further interaction from the user.
It is best practice to only request scopes you need when you need them, a concept called dynamic consent. While this can create more interactive consent for users in your application, it also reduces drop-off from users that may be uneasy granting a large list of permissions for features they are not yet using.
AAD will only allow you to get consent for 3 resources at a time, although you can request many scopes within a resource. When the user makes a login request, you can pass in multiple resources and their corresponding scopes because AAD issues an idToken pre consenting those scopes. However acquireToken calls are valid only for one resource / multiple scopes. If you need to access multiple resources, please make separate acquireToken calls per resource.
var loginRequest = { scopes: ["user.read", "mail.send"] // optional Array<string> }; msalInstance.loginPopup(loginRequest) .then(response => { // handle response }) .catch(err => { // handle error });
ssoSilent
If you are confident that the user has an existing session and would like to establish user context without prompting for interaction, you can invoke ssoSilent with a loginHint or sid (available as an optional claim) and MSAL will attempt to silently SSO to the existing session and establish user context.
Note, if there is no active session for the given loginHint or sid, an error will be thrown, which should be handled by invoking an interactive login method (loginPopup or loginRedirect).
Example:
const ssoRequest = { loginHint: "user@example.com" }; msalInstance.ssoSilent(ssoRequest) .then(response => { // session silently established }) .catch(error => { // handle error by invoking an interactive login method msalInstance.loginPopup(ssoRequest); });
3. Get an access token to call an API
In MSAL, you can get access tokens for the APIs your app needs to call using the acquireTokenSilent method which makes a silent request (without prompting the user with UI) to Azure AD to obtain an access token. The Azure AD service then returns an access token containing the user consented scopes to allow your app to securely call the API.
You can use acquireTokenRedirect or acquireTokenPopup to initiate interactive requests, although, it is best practice to only show interactive experiences if you are unable to obtain a token silently due to interaction required errors. If you are using an interactive token call, it must match the login method used in your application. (loginPopup=> acquireTokenPopup, loginRedirect => acquireTokenRedirect).
If the acquireTokenSilent call fails with an error of type InteractionRequiredAuthError you will need to initiate an interactive request. This could happen for many reasons including scopes that have been revoked, expired tokens, or password changes.
acquireTokenSilent will look for a valid token in the cache, and if it is close to expiring or does not exist, will automatically try to refresh it for you.
See Request and Response Data Types for reference.
// if the user is already logged in you can acquire a token if (msalInstance.getAccount()) { var tokenRequest = { scopes: ["user.read", "mail.send"] }; msalInstance.acquireTokenSilent(tokenRequest) .then(response => { // get access token from response // response.accessToken }) .catch(err => { // could also check if err instance of InteractionRequiredAuthError if you can import the class. if (err.name === "InteractionRequiredAuthError") { return msalInstance.acquireTokenPopup(tokenRequest) .then(response => { // get access token from response // response.accessToken }) .catch(err => { // handle error }); } }); } else { // user is not logged in, you will need to log them in to acquire a token }
4. Use the token as a bearer in an HTTP request to call the Microsoft Graph or a Web API
var headers = new Headers(); var bearer = "Bearer " + token; headers.append("Authorization", bearer); var options = { method: "GET", headers: headers }; var graphEndpoint = "https://graph.microsoft.com/v1.0/me"; fetch(graphEndpoint, options) .then(resp => { //do something with response });
You can learn further details about MSAL.js functionality documented in the MSAL Wiki and find complete code samples for all MSAL libraries and code samples for MSAL v1 specifically.
Security Reporting
If you find a security issue with our libraries or services please report it to secure@microsoft.com 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 (the "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 opencode@microsoft.com with any additional questions or comments.
FAQs
What is Microsoft authentication library? ›
The Microsoft Authentication Library (MSAL) enables application developers to acquire tokens in order to call secured web APIs. These web APIs can be the Microsoft Graph, other Microsoft APIs, third-party web APIs, or your own web API. MSAL supports multiple application architectures and platforms.
What is Microsoft authentication library MSAL for JavaScript? ›The Microsoft Authentication Library for JavaScript enables both client-side and server-side JavaScript applications to authenticate users using Azure Active Directory (Azure AD) for work and school accounts, Microsoft personal accounts (MSA), and social identity providers like Facebook, Google, LinkedIn, Microsoft ...
How to get access token from Azure Active Directory in JavaScript? ›- Request an authorization code, which launches a browser window and asks for Azure user login. The authorization code is returned after the user successfully logs in.
- Use the authorization code to acquire the Azure AD access token.
Microsoft Azure Active Directory Authentication Library (ADAL) is a tool in the . NET framework that lets client applications developers authenticate users to an on-premises Active Directory deployment or to the cloud. ADAL will then secure API calls by locating tokens for access.
What is the difference between Windows authentication and server authentication? ›Connecting Through Windows Authentication
SQL Server does not ask for the password, and does not perform the identity validation. Windows Authentication is the default authentication mode, and is much more secure than SQL Server Authentication.
If you have a smartphone (iPhone, Android or Windows Phone) you can use the Microsoft Authenticator App to verify your login.
How to implement authentication in JavaScript? ›To setup Authentication, the user needs to configure OAuth 2.0 ID in JavaScript and the backend code. 5. JavaScript application uses client ID to obtain the Google ID token from OAuth 2.0 server and send ID in the request.
Why do we use Msal? ›The Microsoft Authentication Library (MSAL) enables developers to acquire security tokens from the Microsoft identity platform to authenticate users and access secured web APIs. It can be used to provide secure access to Microsoft Graph, other Microsoft APIs, third-party web APIs, or your own web API.
What is the default authentication method for Windows domains? ›In Active Directory domains, the Kerberos protocol is the default authentication protocol.
How do I generate a JWT token for Azure AD? ›- Select the "Body" tab, select the "x-www-form-urlencoded" radio button, and enter the following Key-Value pairs: ...
- Click the [Send] button to send the HTTP POST request. ...
- The resulting JSON includes a node named "access_token".
How to access JWT token in JavaScript? ›
Send JWT access token as a bearer in HTTP header with each server request that requires authorization. Verify the JWT on your server using the public key (public to your services). Load user data from your database based on the user ID stored in the JWT subject.
How do I validate my Azure AD security token? ›The validate-azure-ad-token policy enforces the existence and validity of a JSON web token (JWT) that was provided by the Azure Active Directory service. The JWT can be extracted from a specified HTTP header, query parameter, or value provided using a policy expression or context variable.
How do I authenticate using Azure Active Directory? ›- Sign in to the Azure portal and navigate to your app.
- Select Authentication in the menu on the left. ...
- Select Microsoft in the identity provider dropdown.
- The client requests an authentication ticket from the AD server.
- The AD server returns the ticket to the client.
- The client sends this ticket to the Endpoint Server.
- The Server then returns an acknowledgment of authentication to the client.
User authentication happens when the user presents credentials to Azure AD or to some identity provider that federates with Azure AD, such as Active Directory Federation Services (AD FS). The user gets back a security token. That token can be presented to the Azure Data Explorer service.
What is the difference between client authentication and server authentication? ›Client certificates tend to be used within private organizations to authenticate requests to remote servers. Whereas server certificates are more commonly known as TLS/SSL certificates and are used to protect servers and web domains.
What is the difference between authenticator and authentication? ›An authenticator app provides an additional layer of security that is more than just a username and password. Authentication is the process a user goes through to validate who they are by way of logging basic identification details such as an email address or username followed by a password.
What is the difference between authentication server and authorization server? ›Authentication confirms that users are who they say they are. Authorization gives those users permission to access a resource. While authentication and authorization might sound similar, they are distinct security processes in the world of identity and access management (IAM).
Why would I need Microsoft Authenticator app? ›The Microsoft Authenticator app helps you sign in to your accounts when you're using two-step verification. Two-step verification helps you to use your accounts more securely because passwords can be forgotten, stolen, or compromised.
Why should I use Microsoft Authenticator app? ›The authenticator app is a secure and convenient way to prove who you are. You can use the Authenticator app as a way to sign in if you forget your password. You can use the app to back up and restore all your other account credentials.
What can my employer see through Microsoft Authenticator? ›
- Device owner.
- Device name.
- Device serial number.
- Device model, such as Google Pixel.
- Device manufacturer, such as Microsoft.
- Operating system and version, such as iOS 12.0.1.
- Device IMEI.
- App inventory and app names, such as Microsoft Word.
- Step 0 — Setup Express JS app. ...
- Step 1 — Register a new User. ...
- Step 2 — Authenticate Users and return JWT tokens. ...
- Step 3 — Understanding the accessToken and refreshToken model. ...
- Step 4 — Retire Refresh Tokens.
- Step 1: Generate the OTP. Use the Time-Based OTP algorithm to generate a random six-digit one-time password (OTP). ...
- Step 2: Send an SMS message with the OTP. Send an SMS message with the OTP to the user's registered mobile number using Plivo's Send Message API. ...
- Step 3: Verify the OTP.
- Go to the resource page of your function app on Azure portal.
- Select Settings -> Authentication.
- Select Add identity provider.
- Select Microsoft from the Identity provider list. ...
- Select Add to complete the settings.
Authorization common endpoint is https://login.microsoftonline.com/common/oauth2/v2.0/authorize . Token common endpoint is https://login.microsoftonline.com/common/oauth2/v2.0/token . For single-tenant applications, replace "common" in the previous URLs with your tenant ID or name.
What is authorization code in Azure? ›The authorization code flow begins with the client directing the user to the /authorize endpoint. In this request, the client indicates the permissions it needs to acquire from the user. You can get the OAuth 2.0 authorization endpoint for your tenant by selecting App registrations > Endpoints in the Azure portal.
What is the purpose of Azure Synapse? ›Azure Synapse Analytics is an enterprise analytics service that accelerates time to insight across data warehouses and big data systems. It brings together the best of SQL technologies used in enterprise data warehousing, Apache Spark technologies for big data, and Azure Data Explorer for log and time series analytics.
What are the three authentication domains? ›Three-factor authentication (3FA) is the use of identity-confirming credentials from three separate categories of authentication factors -- typically, the knowledge, possession and inherence categories.
What is the default authentication method in Azure? ›Authentication methods
Security defaults users are required to register for and use Azure AD Multifactor Authentication using the Microsoft Authenticator app using notifications. Users may use verification codes from the Microsoft Authenticator app but can only register using the notification option.
There are three basic types of authentication. The first is knowledge-based — something like a password or PIN code that only the identified user would know. The second is property-based, meaning the user possesses an access card, key, key fob or authorized device unique to them. The third is biologically based.
Does Azure AD use JWT? ›
All tokens used in Azure AD B2C are JSON web tokens (JWTs) that contain assertions of information about the bearer and the subject of the token. The following tokens are used in communication with Azure AD B2C: ID token - A JWT that contains claims that you can use to identify users in your application.
What is the difference between access token and ID token in Azure AD? ›Access tokens are what the OAuth client uses to make requests to an API. The access token is meant to be read and validated by the API. An ID token contains information about what happened when a user authenticated, and is intended to be read by the OAuth client.
How do I authorize a Web API using JWT token? ›- Create a Web API Project.
- Test the API.
- Configure Authentication and JWT.
- Enable HTTPS and Authentication.
- Add a Service.
- Add a Controller.
- Enable Authentication for the Sample Controller.
- Testing the Sample API.
To validate a JWT using JWKS in node js:
Create/have a token endpoint and sign the token. Retrieve the JWKS from the JWKs endpoint. Extract the JWT from the request's authorization header. Decode the JWT and grab the unique kid (Key ID) property of the token from the header.
- Select the algorithm RS256 from the Algorithm drop-down menu.
- Enter the header and the payload. ...
- Download the private key from the /home/vol/privatekey. ...
- Enter the downloaded private key in the Private Key field of the Verify Signature section.
Click Security > Global security. In the User account repository section, click Configure. In the Related Items section, click Trusted authentication realms - inbound > Add External Realm. In the External realm name field, enter the issuer name that is used by the JWT.
How do I verify my JWT token in Azure? ›The way you validate the authenticity of the JWT token's data is by using Azure AD's public key to verify the signature. If it works, you know the contents were signed with the private key. If not, you can't be sure of it so you should treat the JWT token as an invalid token.
How do I validate JWT token in Azure API management? ›To validate a JWT that was provided by the Azure Active Directory service, API Management also provides the validate-azure-ad-token policy. Set the policy's elements and child elements in the order provided in the policy statement. To help you configure this policy, the portal provides a guided, form-based editor.
How do I authenticate my access token? ›- Request: The person asks for access to a server or protected resource. ...
- Verification: The server determines that the person should have access. ...
- Tokens: The server communicates with the authentication device, like a ring, key, phone, or similar device.
- In the Azure portal, click Azure Active Directory > Security > Authentication methods > Microsoft Authenticator. ...
- On the Enable and Target tab, click Yes and All users to enable the policy for everyone or add selected users and groups.
How do I enable strong authentication in Azure AD? ›
Sign in to the Azure portal and select User management. Select Multifactor authentication. Select the user you want to enable and then select Enable. "Enabled" in this procedure means that the user is asked to set up MFA verification when they sign in for the first time.
How do I enable basic authentication in Azure AD? ›You can enable Basic Auth support for a tenant from the Azure portal (Azure Active Directory -> Properties -> Manage Security defaults -> Enable Security defaults = No). Note a number of options under Allow access to basic authentication protocols.
What is the difference between authentication and authorization in Active Directory? ›Authentication verifies who the user is. Authorization determines what resources a user can access. Authentication works through passwords, one-time pins, biometric information, and other information provided or entered by the user.
Is Azure AD used for authentication and authorization? ›Azure Active Directory (Azure AD) is a centralized identity provider in the cloud. Delegating authentication and authorization to it enables scenarios such as: Conditional Access policies that require a user to be in a specific location. Multi-Factor Authentication which requires a user to have a specific device.
How do I allow authenticate permissions in Active Directory? ›You can apply the "Allowed to authenticate" permission to a OU, by configuring the permission to apply to all descendant computer objects; this will assign the permission to all computers in the OU. Right-click on the OU, select Properties, then Security, then click on "Advanced".
Which three authentication methods can be used by Azure MFA? ›- Microsoft Authenticator.
- Authenticator Lite (in Outlook)
- Windows Hello for Business.
- FIDO2 security key.
- OATH hardware token (preview)
- OATH software token.
- SMS.
- Voice call.
Authentication methods in Azure AD include password and phone (for example, SMS and voice calls), which are manageable in Microsoft Graph beta endpoint today, among many others such as FIDO2 security keys and the Microsoft Authenticator app.
What is library authentication? ›“Authenticate" means to verify the identity of authorized patrons logging into Library computers.
How do I stop Microsoft from asking for authentication? ›- Login your account here.
- Under Security & Privacy Click on "Manage Advanced Security"
- You will see the "protect your account" page. Select any option to get a code, and request for it.
- You will see a checkbox that says : "I sign in frequently on this device. Don't ask me for a code".
If you don't want to use email, a phone call, or text, you can use the Microsoft Authenticator app to help strengthen your account security and to sign-in without passwords.
Why is my Microsoft Authenticator app asking for authentication? ›
When App Lock is enabled, you'll be asked to authenticate using your device PIN or biometric every time you open Authenticator. App Lock also helps ensure that you're the only one who can approve notifications by prompting for your PIN or biometric any time you approve a sign-in notification.
What is the most popular auth library? ›1. Passport JS. Passport is not only a 15k stars user-auth library, it is probably the most common way for JS developers to use an external library for user authentication.
What is the best authentication library for node JS? ›Passport is an authentication middleware and one of the best libraries for Node developers. It is adaptable, modular, and it turns out to be an Express-based web application. It provides a simple and flexible way to authenticate users in your web application.
How do I turn off Azure authentication? ›- Open the Microsoft 365 Admin Center.
- In the left side navigation, click Azure Active Directory admin center.
- In the left side navigation, click Azure Active Directory.
- Click Properties.
- Click Manage Security Defaults.
- Select No to Disable Security defaults.
- Restart the device and try again.
- Try change the network to see if the result is different? For example, if we use WIFI. ...
- Try to remove the account in Authenticator and try again to see if there's any different.
Under "Signing in to Google," tap 2-Step Verification. You might need to sign in. Tap Turn off. Confirm by tapping Turn off.
What can my employer see through Microsoft authenticator? ›- Device owner.
- Device name.
- Device serial number.
- Device model, such as Google Pixel.
- Device manufacturer, such as Microsoft.
- Operating system and version, such as iOS 12.0.1.
- Device IMEI.
- App inventory and app names, such as Microsoft Word.
After the authenticator app is deleted, it's removed from your security info and it disappears from the Security info page. If the authenticator app is your default method, the default changes to another available method.
Is Authenticator the same as Microsoft authenticator? ›Microsoft Authenticator can support one account on multiple devices simultaneously while Google Authenticator is limited to one device per account. Only Microsoft Authenticator supports backup and restore features. Google Authenticator doesn't require a password to access the app, decreasing its security.
Is it safe to use the Microsoft Authenticator app? ›Microsoft describes their Authenticator as “More secure. Passwords can be forgotten, stolen, or compromised. With Authenticator, your phone provides an extra layer of security on top of your PIN or fingerprint.”
How do I reset Microsoft authentication app? ›
Go to the security settings of your Microsoft account, either on a web browser or on a different device. Click on the "Security info" option and sign in to your account. Under the "Security info" section, locate the "Authenticator app" and click on "Manage". Click on the "Remove" option next to the lost device.
How to get 6 digit authentication code Microsoft Authenticator app? ›- Open the Microsoft Authenticator app on your phone.
- Tap the + > Work or school account.
- Use your phone to scan the QR square that is on your computer screen. Notes: ...
- Your account will be added automatically to the app and will display a six-digit code.