Merge pull request #92102 from TylerMSFT/twhitney-addtable

add table

Author: PRMerger19

articles/active-directory/develop/msal-authentication-flows.md

@@ -13,7 +13,7 @@ ms.devlang: na
 ms.topic: conceptual
 ms.tgt_pltfrm: na
 ms.workload: identity
-ms.date: 04/25/2019
+ms.date: 10/16/2019
 ms.author: twhitney
 ms.reviewer: saeeda
 ms.custom: aaddev
@@ -34,9 +34,26 @@ This article describes the different authentication flows provided by Microsoft
 | [Client credentials](#client-credentials) | Allows you to access web-hosted resources by using the identity of an application. Commonly used for server-to-server interactions that must run in the background, without immediate interaction with a user. | [Daemon apps](scenario-daemon-overview.md) |
 | [Device code](#device-code) | Allows users to sign in to input-constrained devices such as a smart TV, IoT device, or printer. | [Desktop/mobile apps](scenario-desktop-acquire-token.md#command-line-tool-without-web-browser) |
 | [Integrated Windows Authentication](scenario-desktop-acquire-token.md#integrated-windows-authentication) | Allows applications on domain or Azure Active Directory (Azure AD) joined computers to acquire a token silently (without any UI interaction from the user).| [Desktop/mobile apps](scenario-desktop-acquire-token.md#integrated-windows-authentication) |
-| [Username/password](scenario-desktop-acquire-token.md#username--password) | Allows an application to sign in the user by directly handling their password. This flow isn't recommended. | [Desktop/mobile apps](scenario-desktop-acquire-token.md#username--password) | 
+| [Username/password](scenario-desktop-acquire-token.md#username--password) | Allows an application to sign in the user by directly handling their password. This flow isn't recommended. | [Desktop/mobile apps](scenario-desktop-acquire-token.md#username--password) |
+
+## How each flow emits tokens and codes
+ 
+Depending on how your client is built, it can use one (or several) of the authentication flows supported by the Microsoft identity platform.  These flows can produce a variety of tokens (id_tokens, refresh tokens, access tokens) as well as authorization codes, and require different tokens to make them work. This chart proides an overview:
+ 
+|Flow | Requires | id_token | access token | refresh token | authorization code | 
+|-----|----------|----------|--------------|---------------|--------------------|
+|[Authorization code flow](v2-oauth2-auth-code-flow.md) | | x | x | x | x|  
+|[Implicit flow](v2-oauth2-implicit-grant-flow.md) | | x        | x    |      |                    |
+|[Hybrid OIDC flow](v2-protocols-oidc.md#get-access-tokens)| | x  | |          |            x   |
+|[Refresh token redemption](v2-oauth2-auth-code-flow.md#refresh-the-access-token) | refresh token | x | x | x| |
+|[On-behalf-of flow](v2-oauth2-on-behalf-of-flow.md) | access token| x| x| x| |
+|[Device code flow](v2-oauth2-device-code.md) | | x| x| x| |
+|[Client credentials](v2-oauth2-client-creds-grant-flow.md) | | | x (app-only)| | |
+ 
+Tokens issued via the implicit mode have a length limitation due to being passed back to the browser via the URL (where `response_mode` is `query` or `fragment`).  Some browsers have a limit on the size of the URL that can be put in the browser bar and fail when it is too long.  Thus, these tokens do not have `groups` or `wids` claims.
 
 ## Interactive
+
 MSAL supports the ability to interactively prompt the user for their credentials to sign in, and obtain a token by using those credentials.
 
 ![Diagram of interactive flow](media/msal-authentication-flows/interactive.png)
@@ -59,6 +76,7 @@ Many modern web applications are built as client-side, single page applications,
 This authentication flow doesn't include application scenarios that use cross-platform JavaScript frameworks such as Electron and React-Native, because they require further capabilities for interaction with the native platforms.
 
 ## Authorization code
+
 MSAL supports the [OAuth 2 authorization code grant](v2-oauth2-auth-code-flow.md). This grant can be used in apps that are installed on a device to gain access to protected resources, such as web APIs. This allows you to add sign-in and API access to your mobile and desktop apps. 
 
 When users sign in to web applications (websites), the web application receives an authorization code.  The authorization code is redeemed to acquire a token to call web APIs. In ASP.NET and ASP.NET Core web apps, the only goal of `AcquireTokenByAuthorizationCode` is to add a token to the token cache. The token can then be used by the application (usually in the controllers, which just get a token for an API by using `AcquireTokenSilent`).
@@ -71,6 +89,7 @@ In the preceding diagram, the application:
 2. Uses the access token to call a web API.
 
 ### Considerations
+
 - You can use the authorization code only once to redeem a token. Don't try to acquire a token multiple times with the same authorization code (it's explicitly prohibited by the protocol standard specification). If you redeem the code several times intentionally, or because you are not aware that a framework also does it for you, you'll get the following 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.`
 
 - If you're writing an ASP.NET or ASP.NET Core application, this might happen if you don't tell the framework that you've already redeemed the authorization code. For this, you need to call the `context.HandleCodeRedemption()` method of the `AuthorizationCodeReceived` event handler.
@@ -101,7 +120,7 @@ The client credentials grant flow permits a web service (a confidential client)
 
 MSAL.NET supports two types of client credentials. These client credentials need to be registered with Azure AD. The credentials are passed in to the constructors of the confidential client application in your code.
 
-### Application secrets 
+### Application secrets
 
 ![Diagram of confidential client with password](media/msal-authentication-flows/confidential-client-password.png)
 
@@ -110,7 +129,7 @@ In the preceding 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 
+### Certificates
 
 ![Diagram of confidential client with cert](media/msal-authentication-flows/confidential-client-certificate.png)
 
@@ -123,8 +142,8 @@ These client credentials need to be:
 - Registered with Azure AD.
 - Passed in at the construction of the confidential client application in your code.
 
-
 ## Device code
+
 MSAL supports the [OAuth 2 device code flow](v2-oauth2-device-code.md), which allows users to sign in to input-constrained devices, such as a smart TV, IoT device, or printer. Interactive authentication with Azure AD requires a web browser. The device code flow lets the user use another device (for example, another computer or a mobile phone) to sign in interactively, where the device or operating system doesn't provide a web browser.
 
 By using the device code flow, the application obtains tokens through a two-step process especially designed for these devices or operating systems. Examples of such applications include those running on IoT devices or command-line tools (CLI). 
@@ -146,6 +165,7 @@ In the preceding diagram:
 - Microsoft personal accounts aren't yet supported by the Azure AD v2.0 endpoint (you can't use the `/common` or `/consumers` tenants).
 
 ## Integrated Windows Authentication
+
 MSAL supports Integrated Windows Authentication (IWA) for desktop or mobile applications that run on a domain joined or Azure AD joined Windows computer. Using IWA, these applications can acquire a token silently (without any UI interaction from the user). 
 
 ![Diagram of Integrated Windows Authentication](media/msal-authentication-flows/integrated-windows-authentication.png)
@@ -183,7 +203,8 @@ The IWA flow is enabled for .NET desktop, .NET Core, and Windows Universal Platf
 
 For more information on consent, see [v2.0 permissions and consent](v2-permissions-and-consent.md).
 
-## Username/password 
+## Username/password
+
 MSAL supports the [OAuth 2 resource owner password credentials grant](v2-oauth-ropc.md), which allows an application to sign in the user by directly handling their password. In your desktop application, you can use the username/password flow to acquire a token silently. No UI is required when using the application.
 
 ![Diagram of the username/password flow](media/msal-authentication-flows/username-password.png)