Authentication flows and application scenarios

The Microsoft identity platform (v2.0) endpoint supports authentication for a variety of modern app architectures, all of them based on industry-standard protocols OAuth 2.0 or OpenID Connect. Using the authentication libraries, applications authenticate identities and acquire tokens to access protected APIs. This article describes the different authentication flows and the application scenarios that they're used in. This article also provides lists of application scenarios and supported authentication flows and application scenarios and supported platforms and languages.

Application categories

Tokens can be acquired from a number of application types: Web applications, Mobile or Desktop applications, Web APIs, and application running on devices that don't have a browser (or iOT). Applications can be categorized by the following:

  • Protected resources vs client applications. Some scenarios are about protecting resources (Web Apps or Web APIs) and others are about acquiring a security token to call a protected Web API.
  • With users or without users. Some scenarios involve a signed-in user, whereas other don't involve a user (daemon scenarios).
  • Single page applications, Public client applications, and confidential client applications. These are three large categories of application types. The libraries and objects used to manipulate them will be different.
  • Sign-in audience. Some authentication flows are unavailable for certain sign in audiences. Some flows are only available for Work or School accounts and some are available for both Work or School accounts and Personal Microsoft accounts. The allowed audience depends on the authentication flows.
  • Supported OAuth 2.0 flows. Authentication flows are used to implement the application scenarios requesting tokens. There is not a one-to-one mapping between application scenarios and authentication flows.
  • Supported platforms. Not all application scenarios are available for every platform.

Protected resources vs client applications

Authentication scenarios involve two activities:

  • Acquiring security tokens for a protected Web API. Microsoft recommends that you use authentication libraries to acquire tokens, in particular the Microsoft Authentication Libraries family (MSAL)
  • Protecting a Web API (or a Web App). One of the challenges of protecting a resource (Web app or Web API) is to validate the security token. Microsoft offers, on some platforms, middleware libraries.

With users or without users

Most authentication scenarios acquire tokens on behalf of a (signed-in) user.

scenarios with users

However there are also scenarios (daemon apps), where applications will acquire tokens on behalf of themselves (with no user).

daemon apps

Single page applications, Public client applications, and confidential client applications

The security tokens can be acquired from a number of application types. Applications tend to be separated into three categories:

  • Single page applications (SPA) are a form of Web applications where tokens are acquired from the app running in the browser (written in JavaScript or Typescript). Many modern apps have a single-page app front end that primarily is written in JavaScript. Often, the app is written by using a framework like Angular, React, or Vue. MSAL.js is the only Microsoft authentication library supporting Single Page applications.

  • Public client applications always sign in users. These apps are:

    • Desktop applications calling Web APIs on behalf of the signed-in user.
    • Mobile applications.
    • A third category of applications, running on devices that don't have a browser (Browserless apps, running on iOT for instance).

    They're represented by the MSAL class named PublicClientApplication.

  • Confidential client applications

    • Web applications calling a Web API
    • Web APIs calling a Web API
    • Daemon applications (even when implemented as a console service like a daemon on linux, or a Windows service)

    These types of apps use the ConfidentialClientApplication

Application scenarios

The Microsoft identity platform endpoint supports authentication for a variety of app architectures: single-page apps, web apps, web APIs, mobile and native apps, and daemons and server-side apps. Applications use the various authentication flows to sign in users and get tokens to call protected APIs.

Single-page application

Many modern web applications are built as client-side single-page applications written using JavaScript or a SPA framework such as Angular, Vue.js, and React.js. These applications run in a web browser and have different authentication characteristics than traditional server-side web applications. The Microsoft identity platform enables single-page applications to sign in users and get tokens to access backend services or web APIs.

Single-page application

For more information, read Single-page applications.

Web Application signing-in a user

Web app signs in users

To protect a Web App (signing in the user), you'll use:

  • In the .NET world, ASP.NET or ASP.NET Core with the ASP.NET Open ID Connect middleware. Under the hood, protecting a resource involves validating the security token, which is done by the IdentityModel extensions for .NET library, not MSAL libraries

  • If you develop in Node.js, you'll use Passport.js.

For more information, read Web App that signs-in users.

Web Application signing-in a user and calling a Web API on behalf of the user

Web app calls Web APIs

From the Web App, to call the Web API on behalf of the user, use MSAL ConfidentialClientApplication. You'll use the Authorization code flow, storing the acquired token in the token cache. Then the controller will acquire tokens silently from the cache when needed. MSAL refreshes the token if needed.

For more information, read Web App calls Web APIs.

Desktop application calling a Web API on behalf of the signed-in user

To call a Web API from a desktop application that signs in users, use MSAL's PublicClientApplication's interactive token acquisition methods. These interactive methods enable you to control the sign in UI experience. To enable this interaction, MSAL leverages a web browser.

Desktop

For Windows hosted applications running on computers joined to a Windows domain or AAD joined, there's another possibility. These applications can acquire a token silently by using Integrated Windows Authentication.

Applications running on a device without a browser will still be able to call an API on behalf of a user. To authenticate, the user will have to sign in on another device that has a Web browser. To enable this scenario, you'll need to use the Device Code flow

Device code flow

Finally, though it's not recommended, you can use Username/Password in public client applications. This flow is still needed in some scenarios (like DevOps), but beware that using it will impose constraints on your application. For instance, apps using this flow won't be able to sign in a user who needs to perform multi-factor authentication (conditional access). It won't enable your application to benefit from single sign-on either. Authentication with username/password goes against the principles of modern authentication and is only provided for legacy reasons.

In desktop applications, if you want the token cache to be persistent, you should customize the token cache serialization. You can even enable backward and forward compatible token caches with previous generations of authentication libraries (ADAL.NET 3.x and 4.x) by implementing dual token cache serialization.

For more information, read Desktop app that calls web APIs.

Mobile application calling a Web API on behalf of the user who's signed-in interactively

Similar to desktop applications, a mobile application will use MSAL's PublicClientApplication's interactive token acquisition methods to acquire a token to call a Web API.

Mobile

MSAL iOS and MSAL Android, by default, use the system web browser. However, you can also direct it to use the embedded Web View. There are specificities depending on the mobile platform: (UWP, iOS, Android).

Some scenarios, involving conditional access related to the device ID, or a device being enrolled require a broker to be installed on a device. Examples of brokers are Microsoft Company portal (on Android), Microsoft Authenticator (Android and iOS). MSAL is now capable of interacting with brokers.

Note

Your mobile app (using MSAL.iOS, MSAL.Android, or MSAL.NET/Xamarin) can have app protection policies applied to it (for instance prevent the user to copy some protected text). This is managed by Intune and recognized by Intune as a managed app. The Intune SDK is separate from MSAL libraries, and it talks to AAD on its own.

For more information, read Mobile app that calls web APIs.

Protected Web API

You can use the Microsoft identity platform endpoint to secure web services, such as your app's RESTful Web API. A protected Web API is called with an access token to secure its data and to authenticate incoming requests. The caller of a Web API appends an access token in the authorization header of an HTTP request. If you want to protect your ASP.NET or ASP.NET Core Web API, you will need to validate the access token. For this, you'll use the ASP.NET JWT middleware. Under the hood, the validation is done by the IdentityModel extensions for .NET library, not MSAL.NET

For more information, read Protected Web API.

Web API calling another downstream Web API on behalf of the user for whom it was called

If, moreover, you want your ASP.NET or ASP.NET Core protected Web API to call another Web API on behalf of the user, the app will need to acquire a token for the downstream Web API by using the ConfidentialClientApplication's method Acquiring a token on behalf of a user. This is also named service to services calls. The Web APIs calling other web API will also need to provide a custom cache serialization

Web API

For more information, read Web API that calls web APIs.

Desktop/service or Web daemon application calling Web API without a user (in its own name)

Apps that have long-running processes or that operate without user interaction also need a way to access secured Web APIs. These apps can authenticate and get tokens by using the app's identity, rather than a user's delegated identity. They prove their identity using a client secret or certificate. You can write such apps (daemon app) acquiring a token for the app on top using MSAL's ConfidentialClientApplication's client credentials acquisition methods. These suppose that the app has previously registered a secret (application password or certificate or client assertion) with Azure AD, which it then shares with this call.

Daemon app

For more information, read Daemon application that calls web APIs.

Scenarios and supported authentication flows

Scenarios that involve acquiring tokens also map to OAuth 2.0 authentication flows described in details in Microsoft identity platform protocols

Scenario Detailed Scenario walk-through OAuth 2.0 Flow/Grant Audience
Single Page App Single-page app Implicit Work or School accounts and Personal accounts, B2C
Web App that signs-in users Web App that signs in users Authorization Code Work or School accounts and Personal accounts, B2C
Web App that calls Web APIs Web App that calls web APIs Authorization Code Work or School accounts and Personal accounts, B2C
Desktop app that calls web APIs Desktop app that calls web APIs Interactive (Authorization Code with PKCE) Work or School accounts and Personal accounts, B2C
Integrated Windows Work or School accounts
Resource Owner Password Work or School accounts, B2C
Device code flow Desktop app that calls web APIs Device Code Work or School accounts*
Mobile app that calls web APIs Mobile app that calls web APIs Interactive (Authorization Code with PKCE) Work or School accounts and Personal accounts, B2C
Resource Owner Password Work or School accounts, B2C
Daemon app Daemon app Client credentials App only permissions (no user) only on AAD Organizations
Web API that calls web APIs Web API that calls web APIs On Behalf Of Work or School accounts and Personal accounts

Scenarios and supported platforms and languages

Not every application type is available on every platform. You can also use various languages to build your applications. Microsoft Authentication libraries support a number of platforms (JavaScript, .NET Framework, .NET Core, Windows 10/UWP, Xamarin.iOS, Xamarin.Android, native iOS, native Android, Java, Python)

Scenario Windows Linux Mac iOS Android
Single-page app
Single Page App
MSAL.js MSAL.js MSAL.js MSAL.js MSAL.js MSAL.js MSAL.js MSAL.js MSAL.js MSAL.js
Web App that signs in users
Web App that signs-in users
ASP.NET
ASP.NET ASP.NET CoreASP.NET Core
ASP.NET CoreASP.NET Core ASP.NET CoreASP.NET Core
Web App that calls web APIs
Web App that calls Web APIs
ASP.NET
ASP.NET + MSAL.NET
ASP.NET CoreASP.NET Core + MSAL.NET MSAL Java msal4j MSAL Python Flask + MSAL Python
ASP.NET CoreASP.NET Core + MSAL.NET MSAL Java msal4j MSAL Python Flask + MSAL Python ASP.NET CoreASP.NET Core + MSAL.NET MSAL Java msal4j MSAL Python Flask + MSAL Python
Desktop app that calls web APIs
Desktop app that calls web APIs Device code flow
MSAL.NET MSAL.NET .NET Core MSAL.NET MSAL Java msal4j MSAL Python MSAL Python .NET CoreMSAL.NET MSAL Java msal4j MSAL Python MSAL Python .NET Core MSAL.NET MSAL Java msal4j MSAL Python MSAL Python
Mobile app that calls web APIs
Mobile app that calls web APIs
UWP MSAL.NET Xamarin MSAL.NET iOS / Objective C or swift MSAL.iOS Android MSAL.Android
Daemon app
Daemon app
.NET MSAL.NET .NET CoreMSAL.NET MSAL Java msal4j MSAL Python MSAL Python .NET Core MSAL.NET MSAL Java msal4j MSAL Python MSAL Python .NET CoreMSAL.NET MSAL Java msal4j MSAL Python MSAL Python
Web API that calls web APIs
Web API that calls web APIs
.NET MSAL.NET .NET CoreMSAL.NET MSAL Java msal4j MSAL Python MSAL Python .NET Core MSAL.NET MSAL Java msal4j MSAL Python MSAL Python .NET CoreMSAL.NET MSAL Java msal4j MSAL Python MSAL Python

See also Microsoft-supported libraries by OS / language

Next steps

Learn more about authentication basics and access tokens.