Tutorial: Sign in users and call the Microsoft Graph API from a JavaScript single-page application (SPA)
In this tutorial, you build a JavaScript single-page application (SPA) that signs in users and calls Microsoft Graph by using the implicit flow. The SPA you build uses the Microsoft Authentication Library (MSAL) for JavaScript v1.0.
In this tutorial:
- Create a JavaScript project with
npm
- Register the application in the Azure portal
- Add code to support user sign-in and sign-out
- Add code to call Microsoft Graph API
- Test the app
Tip
This tutorial uses MSAL.js v1.x which is limited to using the implicit grant flow for single-page applications. We recommend all new applications instead use MSAL.js 2.x and the authorization code flow with PKCE and CORS support.
Prerequisites
- Node.js for running a local web server.
- Visual Studio Code or other editor for modifying project files.
- A modern web browser. Internet Explorer is not supported by the app you build in this tutorial due to the app's use of ES6 conventions.
How the sample app generated by this guide works
The sample application created by this guide enables a JavaScript SPA to query the Microsoft Graph API or a web API that accepts tokens from the Microsoft identity platform endpoint. In this scenario, after a user signs in, an access token is requested and added to HTTP requests through the authorization header. This token will be used to acquire the user's profile and mails via MS Graph API.
Token acquisition and renewal are handled by the Microsoft Authentication Library (MSAL) for JavaScript.
Set up your web server or project
Prefer to download this sample's project instead? Download the project files.
To configure the code sample before you execute it, skip to the configuration step.
Create your project
Make sure you have Node.js installed, and then create a folder to host your application. There, we will implement a simple Express web server to serve your index.html
file.
Using a terminal (such as Visual Studio Code integrated terminal), locate your project folder, then type:
npm init
Next, install the required dependencies:
npm install express --save npm install morgan --save
Now, create a .js file named
server.js
, and then add the following code:const express = require('express'); const morgan = require('morgan'); const path = require('path'); //initialize express. const app = express(); // Initialize variables. const port = 3000; // process.env.PORT || 3000; // Configure morgan module to log all requests. app.use(morgan('dev')); // Set the front-end folder to serve public assets. app.use(express.static('JavaScriptSPA')) // Set up a route for index.html. app.get('*', function (req, res) { res.sendFile(path.join(__dirname + '/index.html')); }); // Start the server. app.listen(port); console.log('Listening on port ' + port + '...');
You now have a simple server to serve your SPA. The intended folder structure at the end of this tutorial is as follows:
Create the SPA UI
Create an
index.html
file for your JavaScript SPA. This file implements a UI built with Bootstrap 4 Framework and imports script files for configuration, authentication and API call.In the
index.html
file, add the following code:<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0, shrink-to-fit=no"> <title>Quickstart | MSAL.JS Vanilla JavaScript SPA</title> <!-- msal.js with a fallback to backup CDN --> <script type="text/javascript" src="https://alcdn.msauth.net/lib/1.2.1/js/msal.js" integrity="sha384-9TV1245fz+BaI+VvCjMYL0YDMElLBwNS84v3mY57pXNOt6xcUYch2QLImaTahcOP" crossorigin="anonymous"></script> <script type="text/javascript"> if(typeof Msal === 'undefined')document.write(unescape("%3Cscript src='https://alcdn.msftauth.net/lib/1.2.1/js/msal.js' type='text/javascript' integrity='sha384-m/3NDUcz4krpIIiHgpeO0O8uxSghb+lfBTngquAo2Zuy2fEF+YgFeP08PWFo5FiJ' crossorigin='anonymous'%3E%3C/script%3E")); </script> <!-- adding Bootstrap 4 for UI components --> <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.4.1/css/bootstrap.min.css" integrity="sha384-Vkoo8x4CGsO3+Hhxv8T/Q5PaXtkKtu6ug5TOeNV6gBiFeWPGFN9MuhOf23Q9Ifjh" crossorigin="anonymous"> </head> <body> <nav class="navbar navbar-expand-lg navbar-dark bg-primary"> <a class="navbar-brand" href="/">MS Identity Platform</a> <div class="btn-group ml-auto dropleft"> <button type="button" id="signIn" class="btn btn-secondary" onclick="signIn()">Sign In</button> <button type="button" id="signOut" class="btn btn-success d-none" onclick="signOut()">Sign Out</button> </div> </nav> <br> <h5 class="card-header text-center">Vanilla JavaScript SPA calling MS Graph API with MSAL.JS</h5> <br> <div class="row" style="margin:auto" > <div id="card-div" class="col-md-3 d-none"> <div class="card text-center"> <div class="card-body"> <h5 class="card-title" id="welcomeMessage">Please sign-in to see your profile and read your mails</h5> <div id="profile-div"></div> <br> <br> <button class="btn btn-primary" id="seeProfile" onclick="seeProfile()">See Profile</button> <br> <br> <button class="btn btn-primary d-none" id="readMail" onclick="readMail()">Read Mails</button> </div> </div> </div> <br> <br> <div class="col-md-4"> <div class="list-group" id="list-tab" role="tablist"> </div> </div> <div class="col-md-5"> <div class="tab-content" id="nav-tabContent"> </div> </div> </div> <br> <br> <!-- importing bootstrap.js and supporting js libraries --> <script src="https://code.jquery.com/jquery-3.4.1.slim.min.js" integrity="sha384-J6qa4849blE2+poT4WnyKhv5vZF5SrPo0iEjwBvKU7imGFAV0wwj1yYfoRSJoZ+n" crossorigin="anonymous"></script> <script src="https://cdn.jsdelivr.net/npm/popper.js@1.16.0/dist/umd/popper.min.js" integrity="sha384-Q6E9RHvbIyZFJoft+2mJbHaEWldlvI9IOYy5n3zV9zzTtmI3UksdQRVvoxMfooAo" crossorigin="anonymous"></script> <script src="https://stackpath.bootstrapcdn.com/bootstrap/4.4.1/js/bootstrap.min.js" integrity="sha384-wfSDF2E50Y2D1uUdj0O3uMBJnjuUD4Ih7YwaYd1iqfktj0Uod8GCExl3Og8ifwB6" crossorigin="anonymous"></script> <!-- importing app scripts (load order is important) --> <script type="text/javascript" src="./authConfig.js"></script> <script type="text/javascript" src="./graphConfig.js"></script> <script type="text/javascript" src="./ui.js"></script> <!-- replace next line with authRedirect.js if you would like to use the redirect flow --> <!-- <script type="text/javascript" src="./authRedirect.js"></script> --> <script type="text/javascript" src="./authPopup.js"></script> <script type="text/javascript" src="./graph.js"></script> </body> </html>
Tip
You can replace the version of MSAL.js in the preceding script with the latest released version under MSAL.js releases.
Now, create a .js file named
ui.js
, which will access and update DOM elements, and add the following code:// Select DOM elements to work with const welcomeDiv = document.getElementById("welcomeMessage"); const signInButton = document.getElementById("signIn"); const signOutButton = document.getElementById('signOut'); const cardDiv = document.getElementById("card-div"); const mailButton = document.getElementById("readMail"); const profileButton = document.getElementById("seeProfile"); const profileDiv = document.getElementById("profile-div"); function showWelcomeMessage(account) { // Reconfiguring DOM elements cardDiv.classList.remove('d-none'); welcomeDiv.innerHTML = `Welcome ${account.name}`; signInButton.classList.add('d-none'); signOutButton.classList.remove('d-none'); } function updateUI(data, endpoint) { console.log('Graph API responded at: ' + new Date().toString()); if (endpoint === graphConfig.graphMeEndpoint) { const title = document.createElement('p'); title.innerHTML = "<strong>Title: </strong>" + data.jobTitle; const email = document.createElement('p'); email.innerHTML = "<strong>Mail: </strong>" + data.mail; const phone = document.createElement('p'); phone.innerHTML = "<strong>Phone: </strong>" + data.businessPhones[0]; const address = document.createElement('p'); address.innerHTML = "<strong>Location: </strong>" + data.officeLocation; profileDiv.appendChild(title); profileDiv.appendChild(email); profileDiv.appendChild(phone); profileDiv.appendChild(address); } else if (endpoint === graphConfig.graphMailEndpoint) { if (data.value.length < 1) { alert("Your mailbox is empty!") } else { const tabList = document.getElementById("list-tab"); tabList.innerHTML = ''; // clear tabList at each readMail call const tabContent = document.getElementById("nav-tabContent"); data.value.map((d, i) => { // Keeping it simple if (i < 10) { const listItem = document.createElement("a"); listItem.setAttribute("class", "list-group-item list-group-item-action") listItem.setAttribute("id", "list" + i + "list") listItem.setAttribute("data-toggle", "list") listItem.setAttribute("href", "#list" + i) listItem.setAttribute("role", "tab") listItem.setAttribute("aria-controls", i) listItem.innerHTML = d.subject; tabList.appendChild(listItem) const contentItem = document.createElement("div"); contentItem.setAttribute("class", "tab-pane fade") contentItem.setAttribute("id", "list" + i) contentItem.setAttribute("role", "tabpanel") contentItem.setAttribute("aria-labelledby", "list" + i + "list") contentItem.innerHTML = "<strong> from: " + d.from.emailAddress.address + "</strong><br><br>" + d.bodyPreview + "..."; tabContent.appendChild(contentItem); } }); } } }
Register your application
Before proceeding further with authentication, register your application on Azure Active Directory.
- Sign in to the Azure portal.
- If you have access to multiple tenants, use the Directory + subscription filter
in the top menu to select the tenant in which you want to register an application.
- Search for and select Azure Active Directory.
- Under Manage, select App registrations > New registration.
- Enter a Name for your application. Users of your app might see this name, and you can change it later.
- Under Supported account types, select Accounts in any organizational directory and personal Microsoft accounts.
- In the Redirect URI section, select the Web platform from the drop-down list, and then set the value to the application URL that's based on your web server.
- Select Register.
- On the app Overview page, note the Application (client) ID value for later use.
- Under Manage, select Authentication.
- In the Implicit grant section, select ID tokens and Access tokens. ID tokens and access tokens are required because this app must sign in users and call an API.
- Select Save.
Set a redirect URL for Node.js
For Node.js, you can set the web server port in the server.js file. This tutorial uses port 3000, but you can use any other available port.
To set up a redirect URL in the application registration information, switch back to the Application Registration pane, and do either of the following:
- Set
http://localhost:3000/
as the Redirect URL.- If you're using a custom TCP port, use
http://localhost:<port>/
(where <port> is the custom TCP port number).
- Copy the URL value.
- Switch back to the Application Registration pane, and paste the copied value as the Redirect URL.
Configure your JavaScript SPA
Create a new .js file named authConfig.js
, which will contain your configuration parameters for authentication, and add the following code:
const msalConfig = {
auth: {
clientId: "Enter_the_Application_Id_Here",
authority: "Enter_the_Cloud_Instance_Id_HereEnter_the_Tenant_Info_Here",
redirectUri: "Enter_the_Redirect_Uri_Here",
},
cache: {
cacheLocation: "sessionStorage", // This configures where your cache will be stored
storeAuthStateInCookie: false, // Set this to "true" if you are having issues on IE11 or Edge
}
};
// Add here scopes for id token to be used at MS Identity Platform endpoints.
const loginRequest = {
scopes: ["openid", "profile", "User.Read"]
};
// Add here scopes for access token to be used at MS Graph API endpoints.
const tokenRequest = {
scopes: ["Mail.Read"]
};
Where:
- <Enter_the_Application_Id_Here> is the Application (client) ID for the application you registered.
- <Enter_the_Cloud_Instance_Id_Here> is the instance of the Azure cloud. For the main or global Azure cloud, simply enter https://login.microsoftonline.com. For national clouds (for example, China), see National clouds.
- <Enter_the_Tenant_info_here> is set to one of the following options:
- If your application supports accounts in this organizational directory, replace this value with the Tenant ID or Tenant name (for example, contoso.microsoft.com).
- If your application supports accounts in any organizational directory, replace this value with organizations.
- If your application supports accounts in any organizational directory and personal Microsoft accounts, replace this value with common. To restrict support to personal Microsoft accounts only, replace this value with consumers.
Use the Microsoft Authentication Library (MSAL) to sign in the user
Create a new .js file named authPopup.js
, which will contain your authentication and token acquisition logic, and add the following code:
const myMSALObj = new Msal.UserAgentApplication(msalConfig);
function signIn() {
myMSALObj.loginPopup(loginRequest)
.then(loginResponse => {
console.log('id_token acquired at: ' + new Date().toString());
console.log(loginResponse);
if (myMSALObj.getAccount()) {
showWelcomeMessage(myMSALObj.getAccount());
}
}).catch(error => {
console.log(error);
});
}
function signOut() {
myMSALObj.logout();
}
function callMSGraph(theUrl, accessToken, callback) {
var xmlHttp = new XMLHttpRequest();
xmlHttp.onreadystatechange = function () {
if (this.readyState == 4 && this.status == 200) {
callback(JSON.parse(this.responseText));
}
}
xmlHttp.open("GET", theUrl, true); // true for asynchronous
xmlHttp.setRequestHeader('Authorization', 'Bearer ' + accessToken);
xmlHttp.send();
}
function getTokenPopup(request) {
return myMSALObj.acquireTokenSilent(request)
.catch(error => {
console.log(error);
console.log("silent token acquisition fails. acquiring token using popup");
// fallback to interaction when silent call fails
return myMSALObj.acquireTokenPopup(request)
.then(tokenResponse => {
return tokenResponse;
}).catch(error => {
console.log(error);
});
});
}
function seeProfile() {
if (myMSALObj.getAccount()) {
getTokenPopup(loginRequest)
.then(response => {
callMSGraph(graphConfig.graphMeEndpoint, response.accessToken, updateUI);
profileButton.classList.add('d-none');
mailButton.classList.remove('d-none');
}).catch(error => {
console.log(error);
});
}
}
function readMail() {
if (myMSALObj.getAccount()) {
getTokenPopup(tokenRequest)
.then(response => {
callMSGraph(graphConfig.graphMailEndpoint, response.accessToken, updateUI);
}).catch(error => {
console.log(error);
});
}
}
More information
After a user selects the Sign In button for the first time, the signIn
method calls loginPopup
to sign in the user. This method opens a pop-up window with the Microsoft identity platform endpoint to prompt and validate the user's credentials. After a successful sign-in, the user is redirected back to the original index.html page. A token is received, processed by msal.js
, and the information contained in the token is cached. This token is known as the ID token and contains basic information about the user, such as the user display name. If you plan to use any data provided by this token for any purposes, you need to make sure this token is validated by your backend server to guarantee that the token was issued to a valid user for your application.
The SPA generated by this guide calls acquireTokenSilent
and/or acquireTokenPopup
to acquire an access token used to query the Microsoft Graph API for user profile info. If you need a sample that validates the ID token, take a look at this sample application in GitHub. The sample uses an ASP.NET web API for token validation.
Get a user token interactively
After the initial sign-in, you do not want to ask users to reauthenticate every time they need to request a token to access a resource. So acquireTokenSilent should be used most of the time to acquire tokens. There are situations, however, where you need to force users to interact with Microsoft identity platform endpoint. Examples include:
- Users need to reenter their credentials because the password has expired.
- Your application is requesting access to a resource, and you need the user's consent.
- Two-factor authentication is required.
Calling acquireTokenPopup opens a pop-up window (or acquireTokenRedirect redirects users to the Microsoft identity platform endpoint). In that window, users need to interact by confirming their credentials, giving consent to the required resource, or completing the two-factor authentication.
Get a user token silently
The acquireTokenSilent
method handles token acquisition and renewal without any user interaction. After loginPopup
(or loginRedirect
) is executed for the first time, acquireTokenSilent
is the method commonly used to obtain tokens used to access protected resources for subsequent calls. (Calls to request or renew tokens are made silently.)
acquireTokenSilent
may fail in some cases. For example, the user's password may have expired. Your application can handle this exception in two ways:
Make a call to
acquireTokenPopup
immediately, which triggers a user sign-in prompt. This pattern is commonly used in online applications where there is no unauthenticated content in the application available to the user. The sample generated by this guided setup uses this pattern.Applications can also make a visual indication to the user that an interactive sign-in is required, so the user can select the right time to sign in, or the application can retry
acquireTokenSilent
at a later time. This is commonly used when the user can use other functionality of the application without being disrupted. For example, there might be unauthenticated content available in the application. In this situation, the user can decide when they want to sign in to access the protected resource, or to refresh the outdated information.
Note
This quickstart uses the loginPopup
and acquireTokenPopup
methods by default. If you are using Internet Explorer as your browser, it is recommended to use loginRedirect
and acquireTokenRedirect
methods, due to a known issue related to the way Internet Explorer handles pop-up windows. If you would like to see how to achieve the same result using Redirect methods
, please see.
Call the Microsoft Graph API by using the token you just acquired
First, create a .js file named
graphConfig.js
, which will store your REST endpoints. Add the following code:const graphConfig = { graphMeEndpoint: "Enter_the_Graph_Endpoint_Herev1.0/me", graphMailEndpoint: "Enter_the_Graph_Endpoint_Herev1.0/me/messages" };
Where:
- <Enter_the_Graph_Endpoint_Here> is the instance of MS Graph API. For the global MS Graph API endpoint, simply replace this string with
https://graph.microsoft.com
. For national cloud deployments, please refer to Graph API Documentation.
- <Enter_the_Graph_Endpoint_Here> is the instance of MS Graph API. For the global MS Graph API endpoint, simply replace this string with
Next, create a .js file named
graph.js
, which will make a REST call to Microsoft Graph API, and add the following code:function callMSGraph(endpoint, token, callback) { const headers = new Headers(); const bearer = `Bearer ${token}`; headers.append("Authorization", bearer); const options = { method: "GET", headers: headers }; console.log('request made to Graph API at: ' + new Date().toString()); fetch(endpoint, options) .then(response => response.json()) .then(response => callback(response, endpoint)) .catch(error => console.log(error)) }
More information about making a REST call against a protected API
In the sample application created by this guide, the callMSGraph()
method is used to make an HTTP GET
request against a protected resource that requires a token. The request then returns the content to the caller. This method adds the acquired token in the HTTP Authorization header. For the sample application created by this guide, the resource is the Microsoft Graph API me endpoint, which displays the user's profile information.
Test your code
Configure the server to listen to a TCP port that's based on the location of your index.html file. For Node.js, start the web server to listen to the port by running the following commands at a command-line prompt from the application folder:
npm install npm start
In your browser, enter http://localhost:3000 or http://localhost:{port}, where port is the port that your web server is listening to. You should see the contents of your index.html file and the Sign In button.
After the browser loads your index.html file, select Sign In. You're prompted to sign in with the Microsoft identity platform endpoint:
Provide consent for application access
The first time that you sign in to your application, you're prompted to grant it access to your profile and sign you in:
View application results
After you sign in, your user profile information is returned in the Microsoft Graph API response that's displayed:
More information about scopes and delegated permissions
The Microsoft Graph API requires the user.read scope to read a user's profile. By default, this scope is automatically added in every application that's registered on the registration portal. Other APIs for Microsoft Graph, as well as custom APIs for your back-end server, might require additional scopes. For example, the Microsoft Graph API requires the Mail.Read scope in order to list the user’s mails.
Note
The user might be prompted for additional consents as you increase the number of scopes.
Help and support
If you need help, want to report an issue, or want to learn about your support options, see Help and support for developers.
Next steps
Delve deeper into single-page application (SPA) development on the Microsoft identity platform in our the multi-part scenario series.