Skip to content

Commit 7fea84d

Browse files
v-albemiv-albemi
authored
Merge pull request #112361 from hamiltonha/patch-13
create msal js v2 quickstart
2 parents 5c75af9 + be67cd4 commit 7fea84d

File tree

2 files changed

+796
-0
lines changed

2 files changed

+796
-0
lines changed

‎articles/active-directory/develop/quickstart-v2-javascipt-auth-code.md

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
---
2+
title: Sign in users in JavaScript single-page apps with auth code | Azure
3+
titleSuffix: Microsoft identity platform
4+
description: Learn how a JavaScript app can call an API that requires access tokens using the Microsoft identity platform.
5+
services: active-directory
6+
author: hahamil
7+
manager: CelesteDG
8+
9+
ms.service: active-directory
10+
ms.subservice: develop
11+
ms.topic: quickstart
12+
ms.workload: identity
13+
ms.date: 04/22/2020
14+
ms.author: hahamil
15+
ms.custom: aaddev, identityplatformtop40, scenarios:getting-started, languages:JavaScript
16+
ROBOTS: NOINDEX
17+
#Customer intent: As an app developer, I want to learn how to get access tokens and refresh tokens by using the Microsoft identity platform endpoint so that my JavaScript app can sign in users of personal accounts, work accounts, and school accounts.
18+
---
19+
20+
# Quickstart: Sign in users and get an access token in a JavaScript SPA using the Auth Code Flow
21+
22+
> [!IMPORTANT]
23+
> This feature is currently in preview. Previews are made available to you on the condition that you agree to the [supplemental terms of use](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). Some aspects of this feature might change before general availability (GA).
24+
25+
26+
This quickstart uses MSAL.js 2.0 with the Authorization Code flow. To use MSAL.js 1.0 with the implicit flow, view [this quickstart](https://docs.microsoft.com/azure/active-directory/develop/quickstart-v2-javascript)
27+
28+
In this quickstart, you use a code sample to learn how a JavaScript single-page application (SPA) can sign in users of personal accounts, work accounts, and school accounts. A JavaScript SPA can also get an access token to call the Microsoft Graph API or any web API. See [How the sample works](#how-the-sample-works) for an illustration.
29+
30+
## Prerequisites
31+
32+
* Azure subscription - [Create an Azure subscription for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F)
33+
* [Node.js](https://nodejs.org/en/download/)
34+
* [Visual Studio Code](https://code.visualstudio.com/download) (to edit project files)
35+
36+
37+
> [!div renderon="docs"]
38+
> ## Register and download your quickstart application
39+
> To start your quickstart application, use either of the following options.
40+
>
41+
> ### Option 1 (Express): Register and auto configure your app and then download your code sample
42+
>
43+
> 1. Sign in to the [Azure portal](https://portal.azure.com).
44+
> 1. If your account gives you access to more than one tenant, select the account at the top right, and then set your portal session to the Azure Active Directory (Azure AD) tenant you want to use.
45+
> 1. Select [App registrations](https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade/quickStartType/JavascriptSpaQuickstartPage/sourceType/docs).
46+
> 1. Enter a name for your application.
47+
> 1. Under **Supported account types**, select **Accounts in any organizational directory and personal Microsoft accounts**.
48+
> 1. Select **Register**.
49+
> 1. Go to the quickstart pane and follow the instructions to download and automatically configure your new application.
50+
>
51+
> ### Option 2 (Manual): Register and manually configure your application and code sample
52+
>
53+
> #### Step 1: Register your application
54+
>
55+
> 1. Sign in to the [Azure portal](https://portal.azure.com).
56+
>
57+
> 1. If your account gives you access to more than one tenant, select your account at the top right, and then set your portal session to the Azure AD tenant you want to use.
58+
> 1. Select [App registrations](https://go.microsoft.com/fwlink/?linkid=2083908).
59+
> 1. Select **New registration**.
60+
> 1. When the **Register an application** page appears, enter a name for your application.
61+
> 1. Under **Supported account types**, select **Accounts in any organizational directory and personal Microsoft accounts**.
62+
> 1. Select **Register**. On the app **Overview** page, note the **Application (client) ID** value for later use.
63+
> 1. In the left pane of the registered application, select **Authentication**.
64+
> 1. Under **Platform Configurations**, select **Add a platform**. A panel opens on the left. There, select the **Single-Page Applications** region.
65+
> 1. Still on the left, set the **Redirect URI** value to `http://localhost:3000/`.
66+
> 1. Select **Configure**.
67+
68+
> [!div class="sxs-lookup" renderon="portal"]
69+
> #### Step 1: Configure your application in the Azure portal
70+
> To make the code sample in this quickstart work, you need to add a `redirectUri` as `http://localhost:3000/`.
71+
> > [!div renderon="portal" id="makechanges" class="nextstepaction"]
72+
> > [Make these changes for me]()
73+
>
74+
> > [!div id="appconfigured" class="alert alert-info"]
75+
> > ![Already configured](media/quickstart-v2-javascript/green-check.png) Your application is configured with these attributes.
76+
77+
#### Step 2: Download the project
78+
79+
> [!div renderon="docs"]
80+
> To run the project with a web server by using Node.js, [download the core project files](https://github.com/Azure-Samples/ms-identity-javascript-v2/archive/quickstart.zip).
81+
82+
> [!div renderon="portal" class="sxs-lookup"]
83+
> Run the project with a web server by using Node.js
84+
85+
> [!div renderon="portal" id="autoupdate" class="nextstepaction" class="sxs-lookup"]
86+
> [Download the code sample](https://github.com/Azure-Samples/ms-identity-javascript-v2/archive/quickstart.zip)
87+
88+
> [!div renderon="docs"]
89+
> #### Step 3: Configure your JavaScript app
90+
>
91+
> In the *app* folder, edit *authConfig.js*, and set the `clientID`, `authority` and `redirectUri` values under `msalConfig`.
92+
>
93+
> ```javascript
94+
>
95+
> // Config object to be passed to Msal on creation
96+
> const msalConfig = {
97+
> auth: {
98+
> clientId: "Enter_the_Application_Id_Here",
99+
> authority: "Enter_the_Cloud_Instance_Id_HereEnter_the_Tenant_Info_Here",
100+
> redirectUri: "Enter_the_Redirect_Uri_Here",
101+
> },
102+
> cache: {
103+
> cacheLocation: "sessionStorage", // This configures where your cache will be stored
104+
> storeAuthStateInCookie: false, // Set this to "true" if you are having issues on IE11 or Edge
105+
> }
106+
> };
107+
>
108+
>```
109+
110+
> [!div renderon="portal" class="sxs-lookup"]
111+
> > [!NOTE]
112+
> > `Enter_the_Supported_Account_Info_Here`
113+
114+
> [!div renderon="docs"]
115+
>
116+
> Where:
117+
> - *\<Enter_the_Application_Id_Here>* is the **Application (client) ID** for the application you registered.
118+
> - *\<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](https://docs.microsoft.com/azure/active-directory/develop/authentication-national-cloud).
119+
> - *\<Enter_the_Tenant_info_here>* is set to one of the following options:
120+
> - If your application supports *accounts in this organizational directory*, replace this value with the **Tenant ID** or **Tenant name** (for example, *contoso.microsoft.com*).
121+
> - If your application supports *accounts in any organizational directory*, replace this value with **organizations**.
122+
> - 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**.
123+
> - *\<Enter_the_Redirect_Uri_Here>* is `http://localhost:3000`
124+
> > [!TIP]
125+
> > To find the values of **Application (client) ID**, **Directory (tenant) ID**, and **Supported account types**, go to the app registration's **Overview** page in the Azure portal.
126+
>
127+
> [!div class="sxs-lookup" renderon="portal"]
128+
> #### Step 3: Your app is configured and ready to run
129+
> We have configured your project with values of your app's properties.
130+
131+
> [!div renderon="docs"]
132+
>
133+
> Then, still in the same folder, edit *graphConfig.js* file to set the `graphMeEndpoint` and `graphMailEndpoint` for the `apiConfig` object.
134+
> ```javascript
135+
> // Add here the endpoints for MS Graph API services you would like to use.
136+
> const graphConfig = {
137+
> graphMeEndpoint: "Enter_the_Graph_Endpoint_Herev1.0/me",
138+
> graphMailEndpoint: "Enter_the_Graph_Endpoint_Herev1.0/me/messages"
139+
> };
140+
>
141+
> // Add here scopes for access token to be used at MS Graph API endpoints.
142+
> const tokenRequest = {
143+
> scopes: ["Mail.Read"]
144+
> };
145+
> ```
146+
>
147+
148+
> [!div renderon="docs"]
149+
>
150+
> *\<Enter_the_Graph_Endpoint_Here>* is the endpoint that API calls will be made against. For the main or global Microsoft Graph API service, enter `https://graph.microsoft.com`. For more information, see [National cloud deployment](https://docs.microsoft.com/graph/deployments).
151+
>
152+
> #### Step 4: Run the project
153+
154+
Run the project with a web server by using [Node.js](https://nodejs.org/en/download/):
155+
156+
1. To start the server, run the following commands from within the project directory:
157+
```bash
158+
npm install
159+
npm start
160+
```
161+
1. Browse to `http://localhost:3000/`.
162+
163+
1. Select **Sign In** to start the sign-in process and then call Microsoft Graph API.
164+
165+
The first time you sign in, you're prompted to provide your consent to allow the application to access your profile and sign you in. After you're signed in successfully, your user profile information should be displayed on the page.
166+
167+
## More information
168+
169+
### How the sample works
170+
171+
![How the sample JavaScript SPA works: 1. The SPA initiates sign in. 2. The SPA acquires an ID token from the Microsoft identity platform. 3. The SPA calls acquire token. 4. The Microsoft identity platform returns an Access token to the SPA. 5. The SPA makes and HTTP GET request with the Access Token to the Microsoft Graph API. 6. The Graph API returns an HTTP response to the SPA.](media/quickstart-v2-javascript/javascriptspa-intro.svg)
172+
173+
### msal.js
174+
175+
The MSAL.js library signs in users and requests the tokens that are used to access an API that's protected by Microsoft identity platform. The sample's *index.html* file contains a reference to the library:
176+
177+
```html
178+
<script type="text/javascript" src="https://alcdn.msftauth.net/lib/1.2.1/js/msal.js" integrity="sha384-9TV1245fz+BaI+VvCjMYL0YDMElLBwNS84v3mY57pXNOt6xcUYch2QLImaTahcOP" crossorigin="anonymous"></script>
179+
```
180+
> [!TIP]
181+
> You can replace the preceding version with the latest released version under [MSAL.js releases](https://github.com/AzureAD/microsoft-authentication-library-for-js/releases).
182+
183+
Alternatively, if you have Node.js installed, you can download the latest version by using the Node.js Package Manager (npm):
184+
185+
```batch
186+
npm install msal
187+
```
188+
189+
## Next steps
190+
191+
The [MSAL.js GitHub repo](https://github.com/AzureAD/microsoft-authentication-library-for-js) contains additional library documentation, a FAQ, and provides issue support.
192+
193+
For a more detailed step-by-step guide on building the application for this quickstart, see:
194+
195+
> [!div class="nextstepaction"]
196+
> [Tutorial to sign in and call MS Graph](https://docs.microsoft.com/azure/active-directory/develop/tutorial-v2-javascript-auth-code)

0 commit comments

Comments
 (0)