edits from Cephas' feedback

v-geberr · v-geberr · commit d36f90581198 · 2023-03-21T16:32:01.000-07:00
diff --git a/articles/app-service/tutorial-connect-app-app-graph-javascript.md b/articles/app-service/tutorial-connect-app-app-graph-javascript.md
@@ -10,29 +10,30 @@ zone_pivot_groups: app-service-platform-windows-linux
 # Requires non-internal subscription - internal subscriptons doesn't provide permission to correctly configure AAD apps
 ---
 
-# Tutorial: Authenticate and authorize users end-to-end in Azure App Service to a downstream Azure service
+# Tutorial: Flow authentication from App Service through back-end API to Microsoft Graph
 
 Learn how to create and configure a backend App service to accept a frontend app's user credential, then exchange that credential for a downstream Azure service. This allows a user to sign in to a frontend App service, pass their credential to a backend App service, then access an Azure service with the same identity. 
 
 In this tutorial, you learn how to:
 
 > [!div class="checklist"]
 >
-> * Extend the previous tutorial's backend app
 > * Configure the backend authentication app to provide a token scoped for the downstream Azure service
-> * Use JavaScript code to exchange the user's token for a new token for downstream service.
+> * Use JavaScript code to exchange the [signed-in user's access token](configure-authentication-oauth-tokens.md#retrieve-tokens-in-app-code) for a new token for downstream service.
 > * Use JavaScript code to access downstream service.
 
 ## Prerequisites
 
-Complete the [previous tutorial](tutorial-auth-aad.md) before starting this tutorial but don't remove the resources at the end of the tutorial. This tutorial assumes you have the two App services and their corresponding authentication apps. 
+Complete the previous tutorial, [Access Microsoft Graph from a secured JavaScript app as the user](tutorial-auth-aad.md), before starting this tutorial but don't remove the resources at the end of the tutorial. This tutorial assumes you have the two App services and their corresponding authentication apps. 
 
 The previous tutorial used the Azure Cloud Shell as the shell for the Azure CLI. This tutorial continues that usage. In order to add the code to the backend app service to exchange the token, this tutorial uses a version of the _code_ editor. Other editors are available such as nano, vim, and emacs.
 
 ## Architecture
 
 The tutorial shows how to pass the user credential provided by the frontend app to the backend app then on to an Azure service. In this tutorial, the downstream service is Microsoft Graph. The user's credential is used to get their profile from Microsoft Graph. 
 
+:::image type="content" source="{source}" alt-text="{alt-text}":::
+
 **Authentication flow** for a user to get Microsoft Graph information in this architecture:
 
 [Previous tutorial](tutorial-auth-aad.md) covered:
@@ -51,19 +52,11 @@ This tutorial doesn't:
 * Change the frontend app from the previous tutorial. 
 * Change the backend authentication app's scope permission because `User.Read` is added by default to all authentication apps. 
 
-## Understand user consent
+## 1. Configure admin consent for the backend app
 
 In the previous tutorial, when the user signed in to the frontend app, a pop-up displayed asking for user consent. 
 
-:::image type="content" source="./media/tutorial-auth-aad/browser-screenshot-authentication-permission-requested-pop-up.png" alt-text="Screenshot of browser authentication pop-up requesting permissions.":::
-
-In this tutorial, the backend needs to exchange the user's token for a new token with an audience for **Microsoft Graph** with a scope of **User.Read** in order to get the user's profile. Because the user isn't directly connected to the backend app, you need to configure the backend authentication app to _not require_ user consent for Microsoft Graph. 
-
-This is a setting change typically done by an Active Directory administrator. For this tutorial, you change that setting as though you've been assigned that task in your organization. If you don't change this setting, the backend app logs an error such as `AADSTS65001: The user or administrator has not consented to use the application with ID \<backend-authentication-id>. Send an interactive authorization request for this user and resource`. Because the error shows up in the log for the backend app, the frontend application can't tell the user why they didn't see their profile in the frontend app.
-
-## 1. Configure backend authentication app with admin consent
-
-Configure the [user consent](#understand-user-consent) for the backend app. 
+In this tutorial, in order to read user profile from Microsoft Graph, the back-end app needs to exchange the signed-in user's [access token](../active-directory/develop/access-tokens.md) for a new access token with the required permissions for Microsoft Graph. Because the user isn't directly connected to the backend app, they can't access the consent screen interactively. You must work around this by configuring the back-end app's app registration in Azure AD to [grant admin consent](../active-directory/manage-apps/grant-admin-consent.md?pivots=portal). This is a setting change typically done by an Active Directory administrator. 
 
 1. Open the Azure portal and search for your research for the backend App Service.
 1. Find the **Settings -> Authentication** section.
@@ -74,13 +67,15 @@ Configure the [user consent](#understand-user-consent) for the backend app.
     :::image type="content" source="./media/tutorial-connect-app-app-graph-javascript/azure-portal-authentication-app-api-permission-admin-consent-area.png" alt-text="Screenshot of Azure portal authentication app with admin consent button highlighted.":::
 
 1. In the pop-up window, select **Yes** to confirm the consent. 
-1. Verify the **Status** column says **Granted for Default Directory**.
+1. Verify the **Status** column says **Granted for Default Directory**. With this setting, the back-end app is no longer required to show a consent screen to the signed-in user and can directly request an access token. The signed-in user will have access to the `User.Read` scope setting because that is the default scope with which the app registration is created. 
 
     :::image type="content" source="./media/tutorial-connect-app-app-graph-javascript/azure-portal-authentication-app-api-permission-admin-consent-granted.png" alt-text="Screenshot of Azure portal authentication app with admin consent granted in status column.":::
 
+
+
 ## 2. Install npm packages
 
-In the previous tutorial, the backend app didn't need any npm packages for authentication because the only authentication was provided by configuring the identity provider in the Azure portal. In this tutorial, the user's token for the backend API with `user_impersonation` needs to be exchanged for a Microsoft Graph token. This exchange is completed with two libraries.
+In the previous tutorial, the backend app didn't need any npm packages for authentication because the only authentication was provided by configuring the identity provider in the Azure portal. In this tutorial, the signed-in user's access token for the back-end API must be exchanged for an access token with Microsoft Graph in its scope. This exchange is completed with two libraries because this exchange doesn't use App Service authentication anymore, but Azure Active Directory and MSAL.js directly.
 
 * [@azure/msal-node](https://www.npmjs.com/package/@azure/msal-node) - exchange token
 * [@microsoft/microsoft-graph-client](https://www.npmjs.com/package/@microsoft/microsoft-graph-client) - connect to Microsoft Graph
@@ -107,12 +102,6 @@ In the previous tutorial, the backend app didn't need any npm packages for authe
 
 The source code to complete this step is provided for you. Use the following steps to include it.
 
-1. Use the Cloud Shell to open the backend app with _code_:
-
-    ```azurecli-interactive
-    code .
-    ```
-
 1. Open the `./src/server.js` file.
 1. Uncomment the following dependency at the top of the file:
 
@@ -156,9 +145,6 @@ The following code is already provided for you in the sample app. You need to un
 Get the current tenant ID from the `WEBSITE_AUTH_OPENID_ISSUER` environment variable. The ID just needs to be parsed out of the variable with a regular expression.
 
 ```javascript
-// Programmatically get tenant id from env var
-// Env var was set by Easy Auth in App Service
-// env value should look something like: https://sts.windows.net/YOUR-TENANT-ID-AS-GUID/v2.0
 export function getTenantId() {
 
     const openIdIssuer = process.env.WEBSITE_AUTH_OPENID_ISSUER;
@@ -175,7 +161,7 @@ Build the MSAL.js configuration object.
 ```javascript
 // ./backend/src/auth.js
 // Exchange current bearerToken for Graph API token
-// Env vars were set by Easy Auth in App Service
+// Env vars were set by App Service
 export async function getGraphToken(backEndAccessToken) {
 
     const config = {
@@ -210,10 +196,10 @@ export async function getGraphToken(backEndAccessToken) {
         scopes: ["https://graph.microsoft.com/.default"]
     }
 
-    // This example has Easy auth validate token in App service runtime
+    // This example has App service validate token in runtime
     // from headers that can't be set externally
 
-    // If you aren't using App service/Easy Auth, 
+    // If you aren't using App service's authentication, 
     // you must validate your access token yourself
     // before calling this code
     try {
@@ -227,6 +213,11 @@ export async function getGraphToken(backEndAccessToken) {
 
 ## 5. Get the user's profile from Microsoft Graph
 
+Before the token exchange, remember that the steps included:
+* Configuration of the Active Directory app registration with an API permission to Microsoft Graph with the scope `User.Read`.
+* Grant admin consent to bypass the user consent screen for the back-end app.
+* Change the application code to convert the access token sent from the front-end app to an access token with the required permission for Microsoft Graph.
+
 Now that the code has the correct token for Microsoft Graph, use it to create a client to Microsoft Graph then get the user's profile. 
 
 The following code is already provided for you in the sample app. You need to understand why it's there and how it works so that you can apply this work to other apps you build that need this same functionality.
@@ -263,7 +254,7 @@ export async function getGraphProfile(accessToken) {
 }
 ```
 
-## 6. Use frontend app to get your profile from Microsoft Graph
+## 6. Test your changes
 
 1. Use the frontend web site in a browser. The URL is in the format of `https://<front-end-app-name>.azurewebsites.net/`. You may need to refresh your token if it's expired.
 1. Select `Get user's profile`. This passes your authentication in the bearer token to the backend. 
@@ -278,12 +269,15 @@ export async function getGraphProfile(accessToken) {
 
 ## Frequently asked questions
 
-### I got an error, what does it mean?
+#### I got an error `80049217`, what does it mean?
+
+This error, `CompactToken parsing failed with error code: 80049217`, means the backend App service isn't authorized to return the Microsoft Graph token.
+
+#### I got an error `AADSTS65001`, what does it mean?
 
-* `CompactToken parsing failed with error code: 80049217` means the backend App service isn't authorized to return the Microsoft Graph token. 
-*  `AADSTS65001: The user or administrator has not consented to use the application with ID \<backend-authentication-id>. Send an interactive authorization request for this user and resource` means the backend authentication app hasn't been configured for Admin consent. 
+This error, `AADSTS65001: The user or administrator has not consented to use the application with ID \<backend-authentication-id>. Send an interactive authorization request for this user and resource`, means the backend authentication app hasn't been configured for Admin consent. Because the error shows up in the log for the backend app, the frontend application can't tell the user why they didn't see their profile in the frontend app.
 
-## Connect to downstream Azure service as user
+#### How do I connect to a different downstream Azure service as user?
 
 This tutorial demonstrates an API app authenticated to **Microsoft Graph**, however, the same general steps can be applied to access any Azure service on behalf of the user. 
 
@@ -294,4 +288,5 @@ This tutorial demonstrates an API app authenticated to **Microsoft Graph**, howe
 
 ## Next steps
 
+* [Tutorial: Create a secure n-tier app in Azure App Service](tutorial-secure-ntier-app.md)
 * [Deploy a Node.js + MongoDB web app to Azure](tutorial-nodejs-mongodb-app.md)
