Authentication flows and application scenarios

The Microsoft identity platform (v2.0) endpoint supports authentication for different kinds of modern application architectures. All of the architectures are based on the industry-standard protocols OAuth 2.0 and 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 they're used in. This article also provides lists of:

Application categories

Tokens can be acquired from several types of applications including:

  • Web apps
  • Mobile apps
  • Desktop apps
  • Web APIs

They can also be acquired from apps running on devices that don't have a browser or are running on IoT.

Applications can be categorized as in the following list:

  • Protected resources vs. client applications: Some scenarios are about protecting resources like web apps or web APIs. Other scenarios are about acquiring a security token to call a protected web API.
  • With users or without users: Some scenarios involve a signed-in user, but others like daemon scenarios don't involve a user.
  • Single-page, public client, and confidential client applications: These are three large categories of application types. Each is used with different libraries and objects.
  • Sign-in audience: The available authentication flows differ depending on the sign-in audience. Some flows are available only for work or school accounts. And some are available both for work or school accounts and for 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 that are requesting tokens. There isn't 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 Library (MSAL) family.
  • Protecting a web API or a web app: One challenge of protecting a web API or web app resource is validating the security token. On some platforms, Microsoft offers middleware libraries.

With users or without users

Most authentication scenarios acquire tokens on behalf of signed-in users.

Scenarios with users

However, there are also daemon-app scenarios, in which applications acquire tokens on behalf of themselves with no user.

Scenarios with daemon apps

Single-page, public client, and confidential client applications

The security tokens can be acquired from multiple types of applications. These applications tend to be separated into three categories:

  • Single-page applications: Also known as SPAs, these are web apps in which tokens are acquired from a JavaScript or TypeScript app running in the browser. Many modern apps have a single-page application front end that is primarily written in JavaScript. The application often uses a framework like Angular, React, or Vue. MSAL.js is the only Microsoft authentication library that supports single-page applications.

  • Public client applications: These applications always sign in users:

    • Desktop apps calling web APIs on behalf of the signed-in user
    • Mobile apps
    • Apps running on devices that don't have a browser, like those running on iOT

    These apps are represented by the MSAL PublicClientApplication class.

  • Confidential client applications:

    • Web apps calling a web API
    • Web APIs calling a web API
    • Daemon apps, even when implemented as a console service like a Linux daemon or a Windows service

    These types of apps use the ConfidentialClientApplication class.

Application scenarios

The Microsoft identity platform endpoint supports authentication for different kinds of app architectures:

  • Single-page apps
  • Web apps
  • Web APIs
  • Mobile apps
  • Native apps
  • Daemon apps
  • Server-side apps

Applications use the different authentication flows to sign in users and get tokens to call protected APIs.

A single-page application

Many modern web apps are built as client-side single-page applications written using JavaScript or an SPA framework like Angular, Vue.js, and React.js. These applications run in a web browser. Their authentication characteristics differ from those of traditional server-side web apps. By using the Microsoft identity platform, single-page applications can sign in users and get tokens to access back-end services or web APIs.

A single-page application

For more information, see Single-page applications.

A web app that is signing in a user

A web app that signs in a user

To protect a web app that is signing in a user:

  • If you develop in .NET, you use ASP.NET or ASP.NET Core with the ASP.NET Open ID Connect middleware. Protecting a resource involves validating the security token, which is done by the IdentityModel extensions for .NET library and not MSAL libraries.

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

For more information, see Web app that signs in users.

A web app that signs in a user and calling a web API on behalf of the user

A web app calling web APIs

To call a web API from a web app on behalf of a user, use the MSAL ConfidentialClientApplication class. You use the Authorization code flow and store the acquired tokens in the token cache. When needed, MSAL refreshes tokens and the controller silently acquires tokens from the cache.

For more information, see A web app calling web APIs.

A desktop app calling a web API on behalf of a signed-in user

For a desktop app to call a web API that signs in users, use the interactive token-acquisition methods of the MSAL PublicClientApplication class. With these interactive methods, you can control the sign-in UI experience. MSAL uses a web browser for this interaction.

A desktop app calling a web API

There's another possibility for Windows-hosted applications on computers joined either to a Windows domain or by Azure Active Directory (Azure AD). These applications can silently acquire a token by using Integrated Windows Authentication.

Applications running on a device without a browser can still call an API on behalf of a user. To authenticate, the user must sign in on another device that has a web browser. This scenario requires that you use the Device Code flow.

Device Code flow

Though we don't recommend you use it, the Username/Password flow is available in public client applications. This flow is still needed in some scenarios like DevOps.

But using this flow imposes constraints on your applications. For instance, applications using this flow can't sign in a user who needs to perform multi-factor authentication or Conditional Access. Your applications also don't benefit from single sign-on.

Authentication with the Username/Password flow goes against the principles of modern authentication and is provided only for legacy reasons.

In desktop apps, if you want the token cache to be persistent, you should customize the token cache serialization. By implementing dual token cache serialization, you can use backward-compatible and forward-compatible token caches with previous generations of authentication libraries. Specific libraries include Azure AD Authentication Library for .NET (ADAL.NET) version 3 and version 4.

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

A mobile app calling a web API on behalf of an interactive user

Similar to a desktop app, a mobile app calls the interactive token-acquisition methods of the MSAL PublicClientApplication class to acquire a token for calling a web API.

A mobile app calling a web API

MSAL iOS and MSAL Android use the system web browser by default. However, you can direct them to use the embedded Web View instead. There are specificities that depend on the mobile platform: Universal Windows Platform (UWP), iOS, or Android.

Some scenarios, like those that involve Conditional Access related to a device ID or a device enrollment, require a broker to be installed on the device. Examples of brokers are Microsoft Company Portal on Android and Microsoft Authenticator on Android and iOS. Also, MSAL can now interact with brokers.

Note

Your mobile app that uses MSAL.iOS, MSAL.Android, or MSAL.NET on Xamarin can have app protection policies applied to it. For instance, the policies might prevent a user from copying protected text. The mobile app is managed by Intune and recognized by Intune as a managed app. The Intune App SDK is separate from MSAL libraries and interacts with Azure AD on its own.

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

A protected web API

You can use the Microsoft Identity Platform endpoint to secure web services like your app's RESTful web API. A protected web API is called with an access token to secure the API's 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 need to validate the access token. For this validation, you use the ASP.NET JWT middleware. The validation is done by the IdentityModel extensions for .NET library and not by MSAL.NET.

For more information, see Protected web API.

A web API calling another web API on behalf of a user

For your ASP.NET or ASP.NET Core protected Web API to call another web API on behalf of a user, your app needs to acquire a token for the downstream web API. It does so by calling the ConfidentialClientApplication class's AcquireTokenOnBehalfOf method. Such calls are also named service-to-services calls. The web APIs that call other web APIs need to provide custom cache serialization.

A web API calling another web API

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

A daemon app calling a web API in the daemon's name

Apps that have long-running processes or that operate without user interaction also need a way to access secure web APIs. Such an app can authenticate and get tokens by using the app's identity rather than a user's delegated identity. The app proves its identity by using a client secret or certificate.

You can write such daemon apps that acquire a token for the calling app by using the MSAL ConfidentialClientApplication class's client credentials acquisition methods. These methods require that the calling app has registered a secret with Azure AD. The app then shares the secret with the called daemon. Examples of such secrets include application passwords, certificate assertion, or client assertion.

A daemon app called by other apps and APIs

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

Scenarios and supported authentication flows

Scenarios that involve acquiring tokens also map to OAuth 2.0 authentication flows, as detailed in Microsoft identity platform protocols.

Scenario Detailed scenario walk-through OAuth 2.0 flow and grant Audience
Single-Page App Single-page app Implicit Work or school accounts, personal accounts, and Microsoft Azure Active Directory B2C (Azure AD B2C)
Web App that signs in users A web app that signs in users Authorization Code Work or school accounts, personal accounts, and Azure AD B2C
Web App that signs in users A web app that calls web APIs Authorization Code Work or school accounts, personal accounts, and Azure AD B2C
Desktop A desktop app that calls web APIs Interactive by using Authorization Code with PKCE Work or school accounts, personal accounts, and Azure AD B2C
Integrated Windows Auth Work or school accounts
Resource Owner Password Work or school accounts and Azure AD B2C
Browserless application Device code Work or school accounts
Mobile app that calls web APIs A mobile app that calls web APIs Interactive by using Authorization Code with PKCE Work or school accounts, personal accounts, and Azure AD B2C
Resource Owner Password Work or school accounts and Azure AD B2C
Daemon app that calls web APIs A daemon app that calls web APIs Client credentials App-only permissions with no user and used only in Azure AD organizations
Web API that calls web APIs A web API that calls web APIs On Behalf Of Work or school accounts and personal accounts

Scenarios and supported platforms and languages

Microsoft Authentication libraries support multiple platforms:

  • JavaScript
  • .NET Framework
  • .NET Core
  • Windows 10/UWP
  • Xamarin.iOS
  • Xamarin.Android
  • Native iOS
  • macOS
  • Native Android
  • Java
  • Python

You can also use various languages to build your applications. Note that some application types aren't available on every platform.

In the Windows column of the following table, each time .NET Core is mentioned, .NET Framework is also possible. The latter is omitted to avoid cluttering the table.

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 Core
ASP.NET Core
ASP.NET Core
ASP.NET Core
ASP.NET Core
ASP.NET Core
Web App that calls web APIs

Web App that calls web APIs
ASP.NET Core
ASP.NET Core + MSAL.NET MSAL Java
MSAL Java
MSAL Python
Flask + MSAL Python
ASP.NET Core
ASP.NET Core + MSAL.NET MSAL Java
MSAL Java
MSAL Python
Flask + MSAL Python
ASP.NET Core
ASP.NET Core + MSAL.NET MSAL Java
MSAL Java
MSAL Python
Flask + MSAL Python
Desktop app that calls web APIs

Desktop app that calls web APIs Device code flow
.NET CoreMSAL.NET MSAL Java
MSAL Java
MSAL Python
MSAL Python
.NET CoreMSAL.NET MSAL Java
MSAL Java
MSAL Python
MSAL Python
.NET CoreMSAL.NET MSAL Java
MSAL Java
MSAL Python
MSAL Python
iOS / Objective C or swift MSAL.objc
Mobile app that calls web APIs
Mobile app that calls web APIs
UWP MSAL.NET Xamarin MSAL.NET iOS / Objective C or swift MSAL.objc Android MSAL.Android
Daemon app
Daemon app
.NET CoreMSAL.NET MSAL Java
MSAL Java
MSAL Python
MSAL Python
.NET Core MSAL.NET MSAL Java
MSAL Java
MSAL Python
MSAL Python
.NET CoreMSAL.NET MSAL Java
MSAL Java
MSAL Python
MSAL Python
Web API that calls web APIs

Web API that calls web APIs
ASP.NET Core
ASP.NET Core + MSAL.NET MSAL Java
MSAL Java
MSAL Python
MSAL Python
.NET Core
ASP.NET Core + MSAL.NET MSAL Java
MSAL Java
MSAL Python
MSAL Python
.NET Core
ASP.NET Core + MSAL.NET MSAL Java
MSAL Java
MSAL Python
MSAL Python

See also Microsoft-supported libraries by OS / language.

Next steps

Learn more about authentication basics and access tokens.