Merge pull request #199391 from derisen/update-msal-node-web-app

update msal-node web app docs

Author: jborsecnik

.openpublishing.publish.config.json

@@ -91,7 +91,7 @@
       "url": "https://github.com/Azure-Samples/msdocs-storage-bind-function-service",
       "branch": "main",
       "branch_mapping": {}
-    },    
+    },
     {
       "path_to_root": "azure_cli_scripts",
       "url": "https://github.com/Azure-Samples/azure-cli-samples",
@@ -901,8 +901,13 @@
       "url": "https://github.com/Azure-Samples/azure-sql-binding-func-dotnet-todo",
       "branch": "docs-snippets",
       "branch_mapping": {}
+    },
+    {
+      "path_to_root": "ms-identity-node",
+      "url": "https://github.com/Azure-Samples/ms-identity-node",
+      "branch": "main",
+      "branch_mapping": {}
     }
-
   ],
   "branch_target_mapping": {
     "live": ["Publish", "PDF"],

articles/active-directory/develop/includes/web-app/quickstart-nodejs-msal.md

@@ -16,7 +16,7 @@ ms.custom: aaddev, scenarios:getting-started, languages:js, devx-track-js
 # Customer intent: As an application developer, I want to know how to set up authentication in a web application built using Node.js and MSAL Node.
 ---
 
-In this quickstart, you download and run a code sample that demonstrates how a Node.js web app can sign in users by using the authorization code flow. The code sample also demonstrates how to get an access token to call Microsoft Graph API.
+In this quickstart, you download and run a code sample that demonstrates how a Node.js web app can sign in users by using the authorization code flow. The code sample also demonstrates how to get an access token to call the Microsoft Graph API.
 
 See [How the sample works](#how-the-sample-works) for an illustration.
 
@@ -37,8 +37,8 @@ This quickstart uses the Microsoft Authentication Library for Node.js (MSAL Node
 1. If you have access to multiple tenants, use the **Directories + subscriptions** filter :::image type="icon" source="../../media/common/portal-directory-subscription-filter.png" border="false"::: in the top menu to switch to the tenant in which you want to register the application.
 1. Under **Manage**, select **App registrations** > **New registration**.
 1. Enter a **Name** for your application. Users of your app might see this name, and you can change it later.
-1. Under **Supported account types**, select **Accounts in any organizational directory and personal Microsoft accounts**.
-1. Set the **Redirect URI** value to `http://localhost:3000/redirect`.
+1. Under **Supported account types**, select **Accounts in this organizational directory only**.
+1. Set the **Redirect URI** value to `http://localhost:3000/auth/redirect`.
 1. Select **Register**.
 1. On the app **Overview** page, note the **Application (client) ID** value for later use.
 1. Under **Manage**, select **Certificates & secrets** > **Client secrets** > **New client secret**.  Leave the description blank and default expiration, and then select **Add**.
@@ -51,67 +51,57 @@ To run the project with a web server by using Node.js, [download the core projec
 
 #### Step 3: Configure your Node app
 
-Extract the project, open the *ms-identity-node-main* folder, and then open the *index.js* file.
-
-Set the `clientID` value with the application (client) ID, and then set the `clientSecret` value with the client secret.
-
-```javascript
-const config = {
-    auth: {
-        clientId: "Enter_the_Application_Id_Here",
-        authority: "https://login.microsoftonline.com/common",
-        clientSecret: "Enter_the_Client_Secret_Here"
-    },
-    system: {
-        loggerOptions: {
-            loggerCallback(loglevel, message, containsPii) {
-                console.log(message);
-            },
-            piiLoggingEnabled: false,
-            logLevel: msal.LogLevel.Verbose,
-        }
-    }
-};
-```
-
+Extract the project, open the *ms-identity-node-main* folder, and then open the *.env* file under the *App* folder. Replace the values above as follows:
 
-Modify the values in the `config` section:
+| Variable  |  Description | Example(s) |
+|-----------|--------------|------------|
+| `Enter_the_Cloud_Instance_Id_Here` | The Azure cloud instance in which your application is registered | `https://login.microsoftonline.com/` (include the trailing forward-slash) |
+| `Enter_the_Tenant_Info_here` | Tenant ID or Primary domain | `contoso.microsoft.com` or `cbe899ec-5f5c-4efe-b7a0-599505d3d54f` |
+| `Enter_the_Application_Id_Here` | Client ID of the application you registered | `cbe899ec-5f5c-4efe-b7a0-599505d3d54f` |
+| `Enter_the_Client_Secret_Here` | Client secret of the application you registered | `WxvhStRfDXoEiZQj1qCy` |
+| `Enter_the_Graph_Endpoint_Here` | The Microsoft Graph API cloud instance that your app will call | `https://graph.microsoft.com/` (include the trailing forward-slash) |
+| `Enter_the_Express_Session_Secret_Here` | A random string of characters used to sign the Express session cookie | `WxvhStRfDXoEiZQj1qCy` |
 
-- `Enter_the_Application_Id_Here` is the application (client) ID for the application you registered.
+Your file should look similar to below:
 
-   To find the application (client) ID, go to the app registration's **Overview** page in the Azure portal.
-- `Enter_the_Client_Secret_Here` is the client secret for the application you registered.
+```text
+CLOUD_INSTANCE=https://login.microsoftonline.com/
+TENANT_ID=cbe899ec-5f5c-4efe-b7a0-599505d3d54f
+CLIENT_ID=fa29b4c9-7675-4b61-8a0a-bf7b2b4fda91
+CLIENT_SECRET=WxvhStRfDXoEiZQj1qCy
 
-   To retrieve or generate a new client secret, under **Manage**, select **Certificates & secrets**.
+REDIRECT_URI=http://localhost:3000/auth/redirect
+POST_LOGOUT_REDIRECT_URI=http://localhost:3000
 
-The default `authority` value represents the main (global) Azure cloud:
+GRAPH_API_ENDPOINT=https://graph.microsoft.com/
 
-```javascript
-authority: "https://login.microsoftonline.com/common",
+EXPRESS_SESSION_SECRET=6DP6v09eLiW7f1E65B8k
 ```
 
+
 #### Step 4: Run the project
 
 Run the project by using Node.js.
 
 1. To start the server, run the following commands from within the project directory:
 
     ```console
+    cd App
     npm install
     npm start
     ```
 
 1. Go to `http://localhost:3000/`.
 
-1. Select **Sign In** to start the sign-in process.
+1. Select **Sign in** to start the sign-in process.
 
-    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, you will see a log message in the command line.
+    The first time you sign in, you're prompted to provide your consent to allow the application to sign you in and access your profile. After you're signed in successfully, you'll be redirected back to the application home page.
 
 ## More information
 
 ### How the sample works
 
-The sample hosts a web server on localhost, port 3000. When a web browser accesses this site, the sample immediately redirects the user to a Microsoft authentication page. Because of this, the sample does not contain any HTML or display elements. Authentication success displays the message "OK".
+The sample hosts a web server on localhost, port 3000. When a web browser accesses this address, the app renders the home page. Once the user selects **Sign in**, the app redirects the browser to Azure AD sign-in screen, via the URL generated by the MSAL Node library. After user consents, the browser redirects the user back to the application home page, along with an ID and access token.  
 
 ### MSAL Node
 
@@ -123,5 +113,6 @@ npm install @azure/msal-node
 
 ## Next steps
 
+Learn more about the web app scenario that the Microsoft identity platform supports:
 > [!div class="nextstepaction"]
-> [Adding Auth to an existing web app - GitHub code sample >](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/samples/msal-node-samples/auth-code)
+> [Web app that signs in users scenario](../../scenario-web-app-sign-user-overview.md)

articles/active-directory/develop/media/tutorial-v2-nodejs-webapp-msal/graph-call-screen.png

@@ -180,31 +180,15 @@ In the Azure portal, the reply URIs that you register on the **Authentication**
 
 # [Node.js](#tab/nodejs)
 
-Here, the configuration parameters reside in `index.js`
+Here, the configuration parameters reside in *.env* as environment variables:
 
-```javascript
+:::code language="text" source="~/ms-identity-node/App/.env":::
 
-const REDIRECT_URI = "http://localhost:3000/redirect";
+These parameters are used to create a configuration object in *authConfig.js* file, which will eventually be used to initialize MSAL Node:
 
-const config = {
-    auth: {
-        clientId: "Enter_the_Application_Id_Here",
-        authority: "https://login.microsoftonline.com/Enter_the_Tenant_Info_Here/",
-        clientSecret: "Enter_the_Client_Secret_Here"
-    },
-    system: {
-        loggerOptions: {
-            loggerCallback(loglevel, message, containsPii) {
-                console.log(message);
-            },
-            piiLoggingEnabled: false,
-            logLevel: msal.LogLevel.Verbose,
-        }
-    }
-};
-```
+:::code language="js" source="~/ms-identity-node/App/authConfig.js":::
 
-In the Azure portal, the reply URIs that you register on the Authentication page for your application need to match the redirectUri instances that the application defines (`http://localhost:3000/redirect`).
+In the Azure portal, the reply URIs that you register on the Authentication page for your application need to match the redirectUri instances that the application defines (`http://localhost:3000/auth/redirect`).
 
 > [!NOTE]
 > This quickstart proposes to store the client secret in the configuration file for simplicity. In your production app, you'd want to use other ways to store your secret, such as a key vault or an environment variable.
@@ -350,12 +334,9 @@ For details about the authorization code flow that this method triggers, see the
 
 # [Node.js](#tab/nodejs)
 
-```javascript
-const msal = require('@azure/msal-node');
+Node sample the Express framework. MSAL is initialized in *auth* route handler:
 
-// Create msal application object
-const cca = new msal.ConfidentialClientApplication(config);
-```
+:::code language="js" source="~/ms-identity-node/App/routes/auth.js" range="6-16":::
 
 # [Python](#tab/python)
 

articles/active-directory/develop/media/tutorial-v2-nodejs-webapp-msal/id-token-screen.png

@@ -96,8 +96,8 @@ By default, the sample uses:
 
 1. When the **Register an application page** appears, enter your application's registration information:
    1. Enter a **Name** for your application, for example `node-webapp`. Users of your app might see this name, and you can change it later.
-   1. Change **Supported account types** to **Accounts in any organizational directory and personal Microsoft accounts (e.g. Skype, Xbox, Outlook.com)**.
-   1. In the **Redirect URI (optional)** section, select **Web** in the combo  box and enter the following redirect URI: `http://localhost:3000/redirect`.
+   1. Change **Supported account types** to **Accounts in this organizational directory only**.
+   1. In the **Redirect URI (optional)** section, select **Web** in the combo  box and enter the following redirect URI: `http://localhost:3000/auth/redirect`.
    1. Select **Register** to create the application.
 1. On the app's **Overview** page, find the **Application (client) ID** value and record it for later. You'll need it to configure the configuration file for this project.
 1. Under **Manage**, select **Certificates & secrets**.

articles/active-directory/develop/media/tutorial-v2-nodejs-webapp-msal/post-sign-in-screen.png

@@ -72,7 +72,7 @@ else
 
 # [Java](#tab/java)
 
-In our Java quickstart, the sign-in button is located in the [main/resources/templates/index.html](https://github.com/Azure-Samples/ms-identity-java-webapp/blob/master/msal-java-webapp-sample/src/main/resources/templates/index.html) file.
+In the Java quickstart, the sign-in button is located in the [main/resources/templates/index.html](https://github.com/Azure-Samples/ms-identity-java-webapp/blob/master/msal-java-webapp-sample/src/main/resources/templates/index.html) file.
 
 ```html
 <!DOCTYPE html>
@@ -94,13 +94,13 @@ In our Java quickstart, the sign-in button is located in the [main/resources/tem
 
 # [Node.js](#tab/nodejs)
 
-In the Node.js quickstart, there's no sign-in button. The code-behind automatically prompts the user for sign-in when it's reaching the root of the web app.
+In the Node.js quickstart, the code for the sign-in button is located in *index.hbs* template file.
 
-```javascript
-app.get('/', (req, res) => {
-    // authentication logic
-});
-```
+:::code language="hbs" source="~/ms-identity-node/App/views/index.hbs" range="10-11":::
+
+This template is served via the main (index) route of the app:
+
+:::code language="js" source="~/ms-identity-node/App/routes/index.js" range="6-15":::
 
 # [Python](#tab/python)
 
@@ -169,40 +169,9 @@ public class AuthPageController {
 
 # [Node.js](#tab/nodejs)
 
-Unlike other platforms, here the MSAL Node takes care of letting the user sign in from the login page.
-
-```javascript
-
-// 1st leg of auth code flow: acquire a code
-app.get('/', (req, res) => {
-    const authCodeUrlParameters = {
-        scopes: ["user.read"],
-        redirectUri: REDIRECT_URI,
-    };
-
-    // get url to sign user in and consent to scopes needed for application
-    pca.getAuthCodeUrl(authCodeUrlParameters).then((response) => {
-        res.redirect(response);
-    }).catch((error) => console.log(JSON.stringify(error)));
-});
-
-// 2nd leg of auth code flow: exchange code for token
-app.get('/redirect', (req, res) => {
-    const tokenRequest = {
-        code: req.query.code,
-        scopes: ["user.read"],
-        redirectUri: REDIRECT_URI,
-    };
-
-    pca.acquireTokenByCode(tokenRequest).then((response) => {
-        console.log("\nResponse: \n:", response);
-        res.sendStatus(200);
-    }).catch((error) => {
-        console.log(error);
-        res.status(500).send(error);
-    });
-});
-```
+When the user selects the **Sign in** link, which triggers the `/auth/signin` route, the sign-in controller takes over to authenticate the user with Microsoft identity platform. 
+
+:::code language="js" source="~/ms-identity-node/App/routes/auth.js" range="27-107, 135-161":::
 
 # [Python](#tab/python)
 
@@ -355,7 +324,7 @@ In our Java quickstart, the sign-out button is located in the main/resources/tem
 
 # [Node.js](#tab/nodejs)
 
-This sample application does not implement sign-out.
+:::code language="hbs" source="~/ms-identity-node/App/views/index.hbs" range="2, 8":::
 
 # [Python](#tab/python)
 
@@ -431,7 +400,9 @@ In Java, sign-out is handled by calling the Microsoft identity platform `logout`
 
 # [Node.js](#tab/nodejs)
 
-This sample application does not implement sign-out.
+When the user selects the **Sign out** button, the app triggers the `/signout` route, which destroys the session and redirects the browser to Microsoft identity platform sign-out endpoint.
+
+:::code language="js" source="~/ms-identity-node/App/routes/auth.js" range="163-174":::
 
 # [Python](#tab/python)
 
@@ -479,7 +450,7 @@ In the Java quickstart, the post-logout redirect URI just displays the index.htm
 
 # [Node.js](#tab/nodejs)
 
-This sample application does not implement sign-out.
+In the Node quickstart, the post-logout redirect URI is used to redirect the browser back to sample home page after the user completes the logout process with the Microsoft identity platform.
 
 # [Python](#tab/python)
 
@@ -494,4 +465,4 @@ If you want to learn more about sign-out, read the protocol documentation that's
 ## Next steps
 
 Move on to the next article in this scenario,
-[Move to production](scenario-web-app-sign-user-production.md).
+[Move to production](scenario-web-app-sign-user-production.md).