title | description | author | manager | ms.author | ms.custom | ms.date | ms.service | ms.topic |
---|---|---|---|---|---|---|---|---|
Quickstart: Sign in users in JavaScript single-page apps |
In this quickstart, you learn how a JavaScript app can call an API that requires access tokens issued by the Microsoft identity platform. |
OwenRichards1 |
CelesteDG |
owenrichards |
scenarios:getting-started, languages:JavaScript, devx-track-js, mode-api |
04/09/2024 |
identity-platform |
quickstart |
In this quickstart, you download and run a code sample that demonstrates how a JavaScript single-page application (SPA) can sign in users and call Microsoft Graph. The code sample also demonstrates how to get an access token to call the Microsoft Graph API or any web API.
See How the sample works for an illustration.
[!INCLUDE portal updates]
- An Azure account with an active subscription. Create an account for free.
- Node.js
- Visual Studio Code (to edit project files)
[!div renderon="docs"]
To start your quickstart application, use either of the following options.
- Sign in to the Azure portal - App registrations quickstart experience.
- Enter a name for your application.
- Under Supported account types, select Accounts in any organizational directory and personal Microsoft accounts.
- Select Register.
- Follow the instructions to download and automatically configure your new application.
- Sign in to the Azure portal.
- If you have access to multiple tenants,use the Settings icon :::image type="icon" source="./media/common/admin-center-settings-icon.png" border="false"::: in the top menu to select the tenant in which you want to register an application.
- Search for and select Identity.
- 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.
- Select Register. On the app Overview page, note the Application (client) ID value for later use.
- This quickstart requires the Implicit grant flow to be enabled. Under Manage, select Authentication.
- Under Platform Configurations > Add a platform. Select Web.
- Set the Redirect URI value to
http://localhost:3000/
.- Select Access Tokens and ID Tokens under the Implicit grant and hybrid flows .
- Select Configure.
[!div class="sxs-lookup" renderon="portal"]
For the code sample in this quickstart to work, add a Redirect URI of
http://localhost:3000/
and enable Implicit grant.[!div renderon="portal" id="makechanges" class="nextstepaction"] Make these changes for me
[!div id="appconfigured" class="alert alert-info"] Your application is configured with these attributes.
[!div renderon="docs"] To run the project with a web server by using Node.js, download the core project files.
[!div renderon="portal" class="sxs-lookup"] Run the project with a web server by using Node.js
[!div renderon="portal" id="autoupdate" class="sxs-lookup nextstepaction"] Download the code sample
[!div renderon="docs"]
In the JavaScriptSPA folder, edit authConfig.js, and set the
clientID
,authority
andredirectUri
values undermsalConfig
.// Config object to be passed to Msal on creation const msalConfig = { auth: { clientId: "Enter_the_Application_Id_Here", authority: "Enter_the_Cloud_Instance_Id_Here/Enter_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 } };
[!div class="sxs-lookup" renderon="portal"]
[!NOTE]
Enter_the_Supported_Account_Info_Here
[!div renderon="docs"]
Where:
Enter_the_Application_Id_Here
is the Application (client) ID for the application you registered.To find the value of Application (client) ID, go to the app's Overview page in the Azure portal.
Enter_the_Cloud_Instance_Id_Here
is the instance of the Azure cloud. For the main or global Azure cloud, simply enterhttps://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
).To find the value of the Directory (tenant) ID, go to the app registration's Overview page in the Azure portal.
- 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 withconsumers
.To find the value of Supported account types, go to the app registration's Overview page in the Azure portal.
Enter_the_Redirect_Uri_Here
ishttp://localhost:3000/
.[!div class="sxs-lookup" renderon="portal"]
We have configured your project with values of your app's properties.
[!div renderon="docs"]
Then, still in the same folder, edit graphConfig.js file to set the
graphMeEndpoint
andgraphMeEndpoint
for theapiConfig
object.// Add here the endpoints for MS Graph API services you would like to use. const graphConfig = { graphMeEndpoint: "Enter_the_Graph_Endpoint_Here/v1.0/me", graphMailEndpoint: "Enter_the_Graph_Endpoint_Here/v1.0/me/messages" }; // Add here scopes for access token to be used at MS Graph API endpoints. const tokenRequest = { scopes: ["Mail.Read"] };
[!div renderon="docs"]
Where:
- <Enter_the_Graph_Endpoint_Here> is the endpoint that API calls will be made against. For the main or global Microsoft Graph API service, simply enter
https://graph.microsoft.com/
. For more information, see National cloud deployment
Run the project with a web server by using Node.js:
-
To start the server, run the following command from the project directory:
npm install npm start
-
Open a web browser and go to
http://localhost:3000/
. -
Select Sign In to start the sign-in, and then call Microsoft Graph API.
After the browser loads the application, select Sign In. The first time that you sign in, you're prompted to provide your consent to allow the application to access your profile and to sign you in. After you're signed in successfully, your user profile information should be displayed on the page.
The MSAL library signs in users and requests the tokens that are used to access an API that's protected by Microsoft identity platform. The quickstart index.html file contains a reference to the library:
<script type="text/javascript" src="https://alcdn.msftauth.net/lib/1.2.1/js/msal.js" integrity="sha384-9TV1245fz+BaI+VvCjMYL0YDMElLBwNS84v3mY57pXNOt6xcUYch2QLImaTahcOP" crossorigin="anonymous"></script>
You can replace the preceding version with the latest released version under MSAL.js releases.
Alternatively, if you have Node.js installed, you can download the latest version through Node.js Package Manager (npm):
npm install msal
The quickstart code also shows how to initialize the MSAL library:
// Config object to be passed to Msal on creation
const msalConfig = {
auth: {
clientId: "00001111-aaaa-2222-bbbb-3333cccc4444", // this is a fake id
authority: "https://login.microsoftonline.com/common",
redirectUri: "http://localhost:3000/",
},
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
}
};
const myMSALObj = new Msal.UserAgentApplication(msalConfig);
Where | Description |
---|---|
clientId |
The application ID of the application that's registered in the Azure portal. |
authority |
(Optional) The authority URL that supports account types, as described previously in the configuration section. The default authority is https://login.microsoftonline.com/common . |
redirectUri |
The application registration's configured reply/redirectUri. In this case, http://localhost:3000/ . |
cacheLocation |
(Optional) Sets the browser storage for the auth state. The default is sessionStorage. |
storeAuthStateInCookie |
(Optional) The library that stores the authentication request state that's required for validation of the authentication flows in the browser cookies. This cookie is set for IE and Edge browsers to mitigate certain known issues. |
For more information about available configurable options, see Initialize client applications.
The following code snippet shows how to sign in users:
// Add scopes for the id token to be used at Microsoft identity platform endpoints.
const loginRequest = {
scopes: ["openid", "profile", "User.Read"],
};
myMSALObj.loginPopup(loginRequest)
.then((loginResponse) => {
//Login Success callback code here
}).catch(function (error) {
console.log(error);
});
Where | Description |
---|---|
scopes |
(Optional) Contains scopes that are being requested for user consent at sign-in time. For example, [ "user.read" ] for Microsoft Graph or [ "<Application ID URL>/scope" ] for custom web APIs (that is, api://<Application ID>/access_as_user ). |
Alternatively, you might want to use the loginRedirect
method to redirect the current page to the sign-in page instead of a pop-up window.
MSAL uses three methods to acquire tokens: acquireTokenRedirect
, acquireTokenPopup
, and acquireTokenSilent
The acquireTokenSilent
method handles token acquisitions and renewal without any user interaction. After the loginRedirect
or loginPopup
method is executed for the first time, acquireTokenSilent
is the method commonly used to obtain tokens that are used to access protected resources for subsequent calls. Calls to request or renew tokens are made silently.
const tokenRequest = {
scopes: ["Mail.Read"]
};
myMSALObj.acquireTokenSilent(tokenRequest)
.then((tokenResponse) => {
// Callback code here
console.log(tokenResponse.accessToken);
}).catch((error) => {
console.log(error);
});
Where | Description |
---|---|
scopes |
Contains scopes being requested to be returned in the access token for API. For example, [ "mail.read" ] for Microsoft Graph or [ "<Application ID URL>/scope" ] for custom web APIs (that is, api://<Application ID>/access_as_user ). |
There are situations where you force users to interact with the Microsoft identity platform. For example:
- Users might need to reenter their credentials because their password has expired.
- Your application is requesting access to additional resource scopes that the user needs to consent to.
- Two-factor authentication is required.
The usual recommended pattern for most applications is to call acquireTokenSilent
first, then catch the exception, and then call acquireTokenPopup
(or acquireTokenRedirect
) to start an interactive request.
Calling the acquireTokenPopup
results in a pop-up window for signing in. (Or acquireTokenRedirect
results in redirecting users to the Microsoft identity platform). In that window, users need to interact by confirming their credentials, giving the consent to the required resource, or completing the two-factor authentication.
// Add here scopes for access token to be used at MS Graph API endpoints.
const tokenRequest = {
scopes: ["Mail.Read"]
};
myMSALObj.acquireTokenPopup(requestObj)
.then((tokenResponse) => {
// Callback code here
console.log(tokenResponse.accessToken);
}).catch((error) => {
console.log(error);
});
Note
This quickstart uses the loginRedirect
and acquireTokenRedirect
methods with Microsoft Internet Explorer, because of a known issue related to the handling of pop-up windows by Internet Explorer.
For a more detailed step-by-step guide on building the application for this quickstart, see:
[!div class="nextstepaction"] Tutorial: Sign in users and call Microsoft Graph