Merge pull request #233133 from cilwerner/content-health-1

v-regandowner · web-flow · commit 04e8592df1a0 · 2023-04-03T10:41:51.000-04:00
[GTD][freshness] msal-authentication-flows.md is 365+ days stale (ADO-82362)
diff --git a/articles/active-directory/develop/TOC.yml b/articles/active-directory/develop/TOC.yml
@@ -25,6 +25,8 @@
           href: security-tokens.md
         - name: Microsoft Authentication Library (MSAL)
           href: msal-overview.md
+        - name: Auth flows supported by MSAL
+          href: msal-authentication-flows.md
         - name: Microsoft Graph
           href: /graph/overview?toc=/azure/active-directory/develop/toc.json&bc=/azure/active-directory/develop/breadcrumb/toc.json
         - name: Glossary of terms
@@ -573,8 +575,6 @@
     - name: Microsoft Authentication Library (MSAL) reference
       displayName: SDK, library, msal, auth
       items:
-        - name: Auth flows supported by MSAL
-          href: msal-authentication-flows.md
         - name: Request and cache tokens
           href: msal-acquire-cache-tokens.md
         - name: Public and confidential client apps
diff --git a/articles/active-directory/develop/msal-authentication-flows.md b/articles/active-directory/develop/msal-authentication-flows.md
@@ -9,9 +9,10 @@ ms.service: active-directory
 ms.subservice: develop
 ms.topic: conceptual
 ms.workload: identity
-ms.date: 03/22/2022
+ms.date: 04/03/2023
 ms.author: cwerner
 ms.reviewer: saeeda
+ms.custom: engagement-fy23
 # Customer intent: As an application developer, I want to learn about the authentication flows supported by MSAL.
 ---
 
@@ -21,7 +22,7 @@ The Microsoft Authentication Library (MSAL) supports several authorization grant
 
 | Authentication flow                                                               | Enables                                                                                                                                                                                          | Supported application types                                                                                                                                                                             |
 |-----------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [Authorization code](#authorization-code)                                         | User sign-in and access to web APIs on behalf of the user.                                                                                                                                       | * [Desktop](scenario-desktop-overview.md) <br /> * [Mobile](scenario-mobile-overview.md) <br /> * [Single-page app (SPA)](scenario-spa-overview.md) (requires PKCE) <br /> * [Web](scenario-web-app-call-api-overview.md) |
+| [Authorization code](#authorization-code)                                         | User sign-in and access to web APIs on behalf of the user.                                                                                                                                       | [Desktop](scenario-desktop-overview.md) <br /> [Mobile](scenario-mobile-overview.md) <br /> [Single-page app (SPA)](scenario-spa-overview.md) (requires PKCE) <br /> [Web](scenario-web-app-call-api-overview.md) |
 | [Client credentials](#client-credentials)                                         | Access to web APIs by using the identity of the application itself. Typically used for server-to-server communication and automated scripts requiring no user interaction.                       | [Daemon](scenario-daemon-overview.md)                                                                                                                                                                   |
 | [Device code](#device-code)                                                       | User sign-in and access to web APIs on behalf of the user on input-constrained devices like smart TVs and IoT devices. Also used by command line interface (CLI) applications.                   | [Desktop, Mobile](scenario-desktop-acquire-token-device-code-flow.md)                                                                                                                                   |
 | [Implicit grant](#implicit-grant)                                                 | User sign-in and access to web APIs on behalf of the user. _The implicit grant flow is no longer recommended - use authorization code with PKCE instead._                                        | * [Single-page app (SPA)](scenario-spa-overview.md) <br /> * [Web](scenario-web-app-call-api-overview.md)                                                                                                 |
@@ -57,22 +58,22 @@ Your MSAL-based application should first try to acquire a token silently and fal
 
 The [OAuth 2.0 authorization code grant](v2-oauth2-auth-code-flow.md) can be used by web apps, single-page apps (SPA), and native (mobile and desktop) apps to gain access to protected resources like web APIs.
 
-When users sign in to web applications, the application receives an authorization code that it can redeem for an access token to call web APIs.
+When users sign in to web applications, the application receives an authorization code that it can redeem for an access token to call web APIs. 
 
-![Diagram of authorization code flow](media/msal-authentication-flows/authorization-code.png)
+In the following diagram, the application:
 
-In the preceding diagram, the application:
-
-1. Requests an authorization code which redeemed for an access token.
+1. Requests an authorization code which was redeemed for an access token.
 2. Uses the access token to call a web API, Microsoft Graph.
 
+![Diagram of authorization code flow.](media/msal-authentication-flows/authorization-code.png)
+
 ### Constraints for authorization code
 
-- Single-page applications require Proof Key for Code Exchange (PKCE) when using the authorization code grant flow. PKCE is supported by MSAL.
+- Single-page applications require *Proof Key for Code Exchange* (PKCE) when using the authorization code grant flow. PKCE is supported by MSAL.
 
-- The OAuth 2.0 specification requires you use an authorization code to redeem an access token only _once_.
+- The OAuth 2.0 specification requires you to use an authorization code to redeem an access token only _once_.
 
-    If you attempt to acquire access token multiple times with the same authorization code, an error similar to the following is returned by the Microsoft identity platform. Keep in mind that some libraries and frameworks request the authorization code for you automatically, and requesting a code manually in such cases will also result in this error.
+    If you attempt to acquire access token multiple times with the same authorization code, an error similar to the following is returned by the Microsoft identity platform. Some libraries and frameworks request the authorization code for you automatically, and requesting a code manually in such cases will also result in this error.
 
     `AADSTS70002: Error validating credentials. AADSTS54005: OAuth2 Authorization code was already redeemed, please retry with a new valid code or use an existing refresh token.`
 
@@ -84,22 +85,22 @@ The client credentials grant flow permits a web service (a confidential client)
 
 ### Application secrets
 
-![Diagram of confidential client with password](media/msal-authentication-flows/confidential-client-password.png)
-
-In the preceding diagram, the application:
+In the following diagram, the application:
 
 1. Acquires a token by using application secret or password credentials.
 2. Uses the token to make requests of the resource.
 
-### Certificates
+![Diagram of confidential client with password.](media/msal-authentication-flows/confidential-client-password.png)
 
-![Diagram of confidential client with cert](media/msal-authentication-flows/confidential-client-certificate.png)
+### Certificates
 
-In the preceding diagram, the application:
+In the following diagram, the application:
 
 1. Acquires a token by using certificate credentials.
 2. Uses the token to make requests of the resource.
 
+![Diagram of confidential client with cert.](media/msal-authentication-flows/confidential-client-certificate.png)
+
 These client credentials need to be:
 
 - Registered with Azure AD.
@@ -115,18 +116,18 @@ The [OAuth 2 device code flow](v2-oauth2-device-code.md) allows users to sign in
 
 By using the device code flow, the application obtains tokens through a two-step process designed for these devices and operating systems. Examples of such applications include those running on IoT devices and command-line interface (CLI) tools.
 
-![Diagram of device code flow](media/msal-authentication-flows/device-code.png)
-
-In the preceding diagram:
+In the following diagram:
 
 1. Whenever user authentication is required, the app provides a code and asks the user to use another device like an internet-connected smartphone to visit a URL (for example, `https://microsoft.com/devicelogin`). The user is then prompted to enter the code, and proceeding through a normal authentication experience including consent prompts and [multi-factor authentication](../authentication/concept-mfa-howitworks.md), if necessary.
 1. Upon successful authentication, the command-line app receives the required tokens through a back channel, and uses them to perform the web API calls it needs.
 
+![Diagram of device code flow.](media/msal-authentication-flows/device-code.png)
+
 ### Constraints for device code
 
 - The device code flow is available only for public client applications.
 - When you initialize a public client application in MSAL, use one of these authority formats:
-  - Tenanted: `https://login.microsoftonline.com/{tenant}/,` where `{tenant}` is either the GUID representing the tenant ID or a domain name associated with the tenant.
+  - Tenant: `https://login.microsoftonline.com/{tenant}/,` where `{tenant}` is either the GUID representing the tenant ID or a domain name associated with the tenant.
   - Work and school accounts: `https://login.microsoftonline.com/organizations/`.
 
 ## Implicit grant
@@ -149,15 +150,15 @@ Tokens issued via the implicit flow mode have a **length limitation** because th
 
 The [OAuth 2 on-behalf-of authentication flow](v2-oauth2-on-behalf-of-flow.md) flow is used when an application invokes a service or web API that in turn needs to call another service or web API. The idea is to propagate the delegated user identity and permissions through the request chain. For the middle-tier service to make authenticated requests to the downstream service, it needs to secure an access token from the Microsoft identity platform *on behalf of* the user.
 
-![Diagram of on-behalf-of flow](media/msal-authentication-flows/on-behalf-of.png)
-
-In the preceding diagram:
+In the following diagram:
 
 1. The application acquires an access token for the web API.
 2. A client (web, desktop, mobile, or single-page application) calls a protected web API, adding the access token as a bearer token in the authentication header of the HTTP request. The web API authenticates the user.
 3. When the client calls the web API, the web API requests another token on-behalf-of the user.
 4. The protected web API uses this token to call a downstream web API on-behalf-of the user. The web API can also later request tokens for other downstream APIs (but still on behalf of the same user).
 
+![Diagram of on-behalf-of flow.](media/msal-authentication-flows/on-behalf-of.png)
+
 ## Username/password (ROPC)
 
 > [!WARNING]
@@ -167,13 +168,13 @@ The [OAuth 2 resource owner password credentials](v2-oauth-ropc.md) (ROPC) grant
 
 Some application scenarios like DevOps might find ROPC useful, but you should avoid it in any application in which you provide an interactive UI for user sign-in.
 
-![Diagram of the username/password flow](media/msal-authentication-flows/username-password.png)
-
-In the preceding diagram, the application:
+In the following diagram, the application:
 
 1. Acquires a token by sending the username and password to the identity provider.
 2. Calls a web API by using the token.
 
+![Diagram of the username/password flow.](media/msal-authentication-flows/username-password.png)
+
 To acquire a token silently on Windows domain-joined machines, we recommend [integrated Windows authentication (IWA)](#integrated-windows-authentication-iwa) instead of ROPC. For other scenarios, use the [device code flow](#device-code).
 
 ### Constraints for ROPC
@@ -195,13 +196,13 @@ The following constraints apply to the applications using the ROPC flow:
 
 MSAL supports integrated Windows authentication (IWA) for desktop and mobile applications that run on domain-joined or Azure AD-joined Windows computers. By using IWA, these applications acquire a token silently without requiring UI interaction by user.
 
-![Diagram of integrated Windows authentication](media/msal-authentication-flows/integrated-windows-authentication.png)
-
-In the preceding diagram, the application:
+In the following diagram, the application:
 
 1. Acquires a token by using integrated Windows authentication.
 2. Uses the token to make requests of the resource.
 
+![Diagram of integrated Windows authentication.](media/msal-authentication-flows/integrated-windows-authentication.png)
+
 ### Constraints for IWA
 
 **Compatibility**
@@ -239,10 +240,10 @@ To satisfy either requirement, one of these operations must have been completed:
 
 - You as the application developer have selected **Grant** in the Azure portal for yourself.
 - A tenant admin has selected **Grant/revoke admin consent for {tenant domain}** in the **API permissions** tab of the app registration in the Azure portal; see [Add permissions to access your web API](quickstart-configure-app-access-web-apis.md#add-permissions-to-access-your-web-api).
-- You've provided a way for users to consent to the application; see [Requesting individual user consent](v2-permissions-and-consent.md#requesting-individual-user-consent).
-- You've provided a way for the tenant admin to consent for the application; see [admin consent](v2-permissions-and-consent.md#requesting-consent-for-an-entire-tenant).
+- You've provided a way for users to consent to the application; see [User consent](../manage-apps/user-admin-consent-overview.md#user-consent).
+- You've provided a way for the tenant admin to consent for the application; see [Administrator consent]../manage-apps/user-admin-consent-overview.md#administrator-consent).
 
-For more information on consent, see [Permissions and consent](v2-permissions-and-consent.md).
+For more information on consent, see [Permissions and consent](v2-permissions-and-consent.md#consent).
 
 ## Next steps
 
