Merge pull request #215173 from derisen/update-node-desktop-articles

update msal node electron articles

Author: v-ccolin

articles/active-directory/develop/includes/desktop-app/quickstart-nodejs-electron.md

@@ -38,7 +38,7 @@ To register your application and add the app's registration information to your
 1. Select **Register** to create the application.
 1. Under **Manage**, select **Authentication**.
 1. Select **Add a platform** > **Mobile and desktop applications**.
-1. In the **Redirect URIs** section, enter the redirect URI suggested by the app registration portal, e.g. `msalfa29b4c9-7675-4b61-8a0a-bf7b2b4fda91://auth`.
+1. In the **Redirect URIs** section, enter `http://localhost`.
 1. Select **Configure**.
 
 #### Step 2: Download the Electron sample project
@@ -62,7 +62,7 @@ Your file should look similar to below:
 
    ```javascript   
    const AAD_ENDPOINT_HOST = "https://login.microsoftonline.com/"; // include the trailing slash
-   const REDIRECT_URI = "msalfa29b4c9-7675-4b61-8a0a-bf7b2b4fda91://auth";
+
    const msalConfig = {
        auth: {
            clientId: "fa29b4c9-7675-4b61-8a0a-bf7b2b4fda91",
@@ -80,14 +80,11 @@ Your file should look similar to below:
    }
 
    const GRAPH_ENDPOINT_HOST = "https://graph.microsoft.com/"; // include the trailing slash
+
    const protectedResources = {
         graphMe: {
             endpoint: `${GRAPH_ENDPOINT_HOST}v1.0/me`,
             scopes: ["User.Read"],
-        },
-        graphMessages: {
-            endpoint: `${GRAPH_ENDPOINT_HOST}v1.0/me/messages`,
-            scopes: ["Mail.Read"],
         }
    };
 
@@ -121,7 +118,7 @@ Your file should look similar to below:
 
 ### How the sample works
 
-When a user selects the **Sign In** button for the first time, get `getTokenInteractive` method of *AuthProvider.js* is called. This method redirects the user to sign-in with the *Microsoft identity platform endpoint* and validate the user's credentials, and then obtains an **authorization code**. This code is then exchanged for an access token using the `acquireTokenByCode` method of MSAL Node.
+When a user selects the **Sign In** button for the first time, `acquireTokenInteractive` method of MSAL Node is called. This method redirects the user to sign-in with the *Microsoft identity platform endpoint*, obtains an **authorization code**, and then exchanges it for an access token.
 
 ### MSAL Node
 

articles/active-directory/develop/quickstart-v2-nodejs-desktop.md

@@ -108,94 +108,29 @@ ms.custom: mode-api
 > 
 > ### Requesting tokens
 > 
-> In the first leg of authorization code flow with PKCE, prepare and send an authorization code request with the appropriate parameters. Then, in the second leg of the flow, listen for the authorization code response. Once the code is obtained, exchange it to obtain a token.
+> You can use MSAL Node's acquireTokenInteractive public API to acquire tokens via an external user-agent such as the default system browser.
 > 
 > ```javascript
-> // The redirect URI you setup during app registration with a custom file protocol "msal"
-> const redirectUri = "msal://redirect";
-> 
-> const cryptoProvider = new CryptoProvider();
-> 
-> const pkceCodes = {
->     challengeMethod: "S256", // Use SHA256 Algorithm
->     verifier: "", // Generate a code verifier for the Auth Code Request first
->     challenge: "" // Generate a code challenge from the previously generated code verifier
-> };
-> 
-> /**
->  * Starts an interactive token request
->  * @param {object} authWindow: Electron window object
->  * @param {object} tokenRequest: token request object with scopes
->  */
-> async function getTokenInteractive(authWindow, tokenRequest) {
-> 
->     /**
->      * Proof Key for Code Exchange (PKCE) Setup
->      *
->      * MSAL enables PKCE in the Authorization Code Grant Flow by including the codeChallenge and codeChallengeMethod
->      * parameters in the request passed into getAuthCodeUrl() API, as well as the codeVerifier parameter in the
->      * second leg (acquireTokenByCode() API).
->      */
-> 
->     const {verifier, challenge} = await cryptoProvider.generatePkceCodes();
-> 
->     pkceCodes.verifier = verifier;
->     pkceCodes.challenge = challenge;
-> 
->     const authCodeUrlParams = {
->         redirectUri: redirectUri
->         scopes: tokenRequest.scopes,
->         codeChallenge: pkceCodes.challenge, // PKCE Code Challenge
->         codeChallengeMethod: pkceCodes.challengeMethod // PKCE Code Challenge Method
->     };
-> 
->     const authCodeUrl = await pca.getAuthCodeUrl(authCodeUrlParams);
-> 
->     // register the custom file protocol in redirect URI
->     protocol.registerFileProtocol(redirectUri.split(":")[0], (req, callback) => {
->         const requestUrl = url.parse(req.url, true);
->         callback(path.normalize(`${__dirname}/${requestUrl.path}`));
->     });
-> 
->     const authCode = await listenForAuthCode(authCodeUrl, authWindow); // see below
-> 
->     const authResponse = await pca.acquireTokenByCode({
->         redirectUri: redirectUri,
->         scopes: tokenRequest.scopes,
->         code: authCode,
->         codeVerifier: pkceCodes.verifier // PKCE Code Verifier
->     });
-> 
->     return authResponse;
-> }
-> 
-> /**
->  * Listens for auth code response from Azure AD
->  * @param {string} navigateUrl: URL where auth code response is parsed
->  * @param {object} authWindow: Electron window object
->  */
-> async function listenForAuthCode(navigateUrl, authWindow) {
-> 
->     authWindow.loadURL(navigateUrl);
-> 
->     return new Promise((resolve, reject) => {
->         authWindow.webContents.on('will-redirect', (event, responseUrl) => {
->             try {
->                 const parsedUrl = new URL(responseUrl);
->                 const authCode = parsedUrl.searchParams.get('code');
->                 resolve(authCode);
->             } catch (err) {
->                 reject(err);
->             }
->         });
->     });
+> const { shell } = require('electron');
+>
+> try {
+>    const openBrowser = async (url) => {
+>        await shell.openExternal(url);
+>    };
+>
+>    const authResponse = await pca.acquireTokenInteractive({
+>        scopes: ["User.Read"],
+>        openBrowser,
+>        successTemplate: '<h1>Successfully signed in!</h1> <p>You can close this window now.</p>',
+>        failureTemplate: '<h1>Oops! Something went wrong</h1> <p>Check the console for more information.</p>',
+>    });
+>
+>    return authResponse;
+> } catch (error) {
+>    throw error;
 > }
 > ```
-> 
-> > |Where:| Description |
-> > |---------|---------|
-> > | `authWindow` | Current Electron window in process. |
-> > | `tokenRequest` | Contains the scopes being requested, such as `"User.Read"` for Microsoft Graph or `"api://<Application ID>/access_as_user"` for custom web APIs. |
+>
 > 
 > ## Next steps
 > 

articles/active-directory/develop/tutorial-v2-nodejs-desktop.md

@@ -40,9 +40,9 @@ First, complete the steps in [Register an application with the Microsoft identit
 Use the following settings for your app registration:
 
 - Name: `ElectronDesktopApp` (suggested)
-- Supported account types: **Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)**
+- Supported account types: **Accounts in my organizational directory only (single tenant)**
 - Platform type: **Mobile and desktop applications**
-- Redirect URI: `msal{Your_Application/Client_Id}://auth`
+- Redirect URI: `http://localhost`
 
 ## Create the project
 
@@ -52,8 +52,8 @@ Create a folder to host your application, for example *ElectronDesktopApp*.
 
     ```console
     npm init -y
-    npm install --save @azure/msal-node axios bootstrap dotenv jquery popper.js
-    npm install --save-dev babel electron@18.2.3 webpack
+    npm install --save @azure/msal-node @microsoft/microsoft-graph-sdk isomorphic-fetch bootstrap jquery popper.js
+    npm install --save-dev electron@20.0.0
     ```
 
 2. Then, create a folder named *App*. Inside this folder, create a file named *index.html* that will serve as UI. Add the following code there:
@@ -76,9 +76,7 @@ The renderer methods are exposed by the preload script found in the *preload.js*
 
     :::code language="js" source="~/ms-identity-JavaScript-nodejs-desktop/App/preload.js":::
 
-This preload script exposes a renderer methods to give the renderer process controlled access to some `Node APIs` by applying IPC channels that have been configured for communication between the main and renderer processes.
-
-*CustomProtocolListener* class can be instantiated in order to register and unregister a custom typed protocol on which MSAL Node can listen for Auth Code responses.
+This preload script exposes a renderer API to give the renderer process controlled access to some `Node APIs` by applying IPC channels that have been configured for communication between the main and renderer processes.
 
 6. Finally, create a file named *constants.js* that will store the strings constants for describing the application **events**:
 
@@ -91,13 +89,11 @@ ElectronDesktopApp/
 ├── App
 │   ├── AuthProvider.js
 │   ├── constants.js
-│   ├── CustomProtocolListener.js
-│   ├── fetch.js
+│   ├── graph.js
 │   ├── index.html
 |   ├── main.js
 |   ├── preload.js
 |   ├── renderer.js
-│   ├── UIManager.js
 │   ├── authConfig.js
 ├── package.json
 ```
@@ -108,11 +104,17 @@ In *App* folder, create a file named *AuthProvider.js*. The *AuthProvider.js* fi
 
 :::code language="js" source="~/ms-identity-JavaScript-nodejs-desktop/App/AuthProvider.js":::
 
-In the code snippet above, we first initialized MSAL Node `PublicClientApplication` by passing a configuration object (`msalConfig`). We then exposed `login`, `logout` and `getToken` methods to be called by main module (*main.js*). In `login` and `getToken`, we acquire ID and access tokens, respectively, by first requesting an authorization code and then exchanging this with a token using MSAL Node `acquireTokenByCode` public API.
+In the code snippet above, we first initialized MSAL Node `PublicClientApplication` by passing a configuration object (`msalConfig`). We then exposed `login`, `logout` and `getToken` methods to be called by main module (*main.js*). In `login` and `getToken`, we acquire ID and access tokens using MSAL Node `acquireTokenInteractive` public API.
+
+## Add Microsoft Graph SDK
+
+Create a file named *graph.js*. The *graph.js* file will contain an instance of the Microsoft Graph SDK Client to facilitate accessing data on the Microsoft Graph API, using the access token obtained by MSAL Node:
+
+:::code language="js" source="~/ms-identity-JavaScript-nodejs-desktop/App/graph.js":::
 
 ## Add app registration details
 
-Finally, create an environment file to store the app registration details that will be used when acquiring tokens. To do so, create a file named *authConfig.js* inside the root folder of the sample (*ElectronDesktopApp*), and add the following code:
+Create an environment file to store the app registration details that will be used when acquiring tokens. To do so, create a file named *authConfig.js* inside the root folder of the sample (*ElectronDesktopApp*), and add the following code:
 
 :::code language="js" source="~/ms-identity-JavaScript-nodejs-desktop/App/authConfig.js":::
 
@@ -127,7 +129,6 @@ Fill in these details with the values you obtain from Azure app registration por
 - `Enter_the_Cloud_Instance_Id_Here`: The Azure cloud instance in which your application is registered.
   - For the main (or *global*) Azure cloud, enter `https://login.microsoftonline.com/`.
   - For **national** clouds (for example, China), you can find appropriate values in [National clouds](authentication-national-cloud.md).
-- `Enter_the_Redirect_Uri_Here`: The Redirect Uri of the application you registered `msal{Your_Application/Client_Id}:///auth`.
 - `Enter_the_Graph_Endpoint_Here` is the instance of the Microsoft Graph API the application should communicate with.
   - For the **global** Microsoft Graph API endpoint, replace both instances of this string with `https://graph.microsoft.com/`.
   - For endpoints in **national** cloud deployments, see [National cloud deployments](/graph/deployments) in the Microsoft Graph documentation.
@@ -156,23 +157,13 @@ If you consent to the requested permissions, the web applications displays your
 
 ## Test web API call
 
-After you sign in, select **See Profile** to view the user profile information returned in the response from the call to the Microsoft Graph API:
+After you sign in, select **See Profile** to view the user profile information returned in the response from the call to the Microsoft Graph API. After consent, you'll view the profile information returned in the response:
 
 :::image type="content" source="media/tutorial-v2-nodejs-desktop/desktop-04-profile.png" alt-text="profile information from Microsoft Graph":::
 
-Select **Read Mails** to view the messages in user's account. You'll be presented with a consent screen:
-
-:::image type="content" source="media/tutorial-v2-nodejs-desktop/desktop-05-consent-mail.png" alt-text="consent screen for read.mail permission":::
-
-After consent, you'll view the messages returned in the response from the call to the Microsoft Graph API:
-
-:::image type="content" source="media/tutorial-v2-nodejs-desktop/desktop-06-mails.png" alt-text="mail information from Microsoft Graph":::
-
 ## How the application works
 
-When a user selects the **Sign In** button for the first time, get `getTokenInteractive` method of *AuthProvider.js* is called. This method redirects the user to sign-in with the Microsoft identity platform endpoint and validates the user's credentials, and then obtains an **authorization code**. This code is then exchanged for an access token using `acquireTokenByCode` public API of MSAL Node.
-
-At this point, a PKCE-protected authorization code is sent to the CORS-protected token endpoint and is exchanged for tokens. An ID token, access token, and refresh token are received by your application and processed by MSAL Node, and the information contained in the tokens is cached.
+When a user selects the **Sign In** button for the first time, the `acquireTokenInteractive` method of MSAL Node. This method redirects the user to sign-in with the Microsoft identity platform endpoint and validates the user's credentials, obtains an **authorization code** and then exchanges that code for an ID token, access token, and refresh token. MSAL Node also caches these tokens for future use.
 
 The ID token contains basic information about the user, like their display name. The access token has a limited lifetime and expires after 24 hours. If you plan to use these tokens for accessing protected resource, your back-end server *must* validate it to guarantee the token was issued to a valid user for your application.