Web app that signs in users: Code configuration

Learn how to configure the code for your web app that signs in users.

Libraries for protecting web apps

The libraries that are used to protect a web app (and a web API) are:

Platform Library Description
.NET Identity Model Extensions for .NET Used directly by ASP.NET and ASP.NET Core, Microsoft Identity Model Extensions for .NET proposes a set of DLLs running on both .NET Framework and .NET Core. From an ASP.NET or ASP.NET Core web app, you can control token validation by using the TokenValidationParameters class (in particular, in some partner scenarios). In practice the complexity is encapsulated in the Microsoft.Identity.Web library
Java MSAL Java Support for Java web applications
Python MSAL Python Support for Python web applications

Select the tab that corresponds to the platform you're interested in:

Code snippets in this article and the following are extracted from the ASP.NET Core web app incremental tutorial, chapter 1.

You might want to refer to this tutorial for full implementation details.

Configuration files

Web applications that sign in users by using the Microsoft identity platform are configured through configuration files. The settings that you need to fill in are:

  • The cloud instance (Instance) if you want your app to run in national clouds, for example
  • The audience in the tenant ID (TenantId)
  • The client ID (ClientId) for your application, as copied from the Azure portal

Sometimes, applications can be parametrized by Authority, which is a concatenation of Instance and TenantId.

In ASP.NET Core, these settings are located in the appsettings.json file, in the "AzureAd" section.

{
  "AzureAd": {
    // Azure cloud instance among:
    // - "https://login.microsoftonline.com/" for Azure public cloud
    // - "https://login.microsoftonline.us/" for Azure US government
    // - "https://login.microsoftonline.de/" for Azure AD Germany
    // - "https://login.chinacloudapi.cn/" for Azure AD China operated by 21Vianet
    "Instance": "https://login.microsoftonline.com/",

    // Azure AD audience among:
    // - "TenantId" as a GUID obtained from the Azure portal to sign in users in your organization
    // - "organizations" to sign in users in any work or school account
    // - "common" to sign in users with any work or school account or Microsoft personal account
    // - "consumers" to sign in users with a Microsoft personal account only
    "TenantId": "[Enter the tenantId here]",

    // Client ID (application ID) obtained from the Azure portal
    "ClientId": "[Enter the Client Id]",
    "CallbackPath": "/signin-oidc",
    "SignedOutCallbackPath ": "/signout-oidc"
  }
}

In ASP.NET Core, another file (properties\launchSettings.json) contains the URL (applicationUrl) and the TLS/SSL port (sslPort) for your application and various profiles.

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:3110/",
      "sslPort": 44321
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "webApp": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "applicationUrl": "http://localhost:3110/"
    }
  }
}

In the Azure portal, the reply URIs that you need to register on the Authentication page for your application need to match these URLs. For the two preceding configuration files, they would be https://localhost:44321/signin-oidc. The reason is that applicationUrl is http://localhost:3110, but sslPort is specified (44321). CallbackPath is /signin-oidc, as defined in appsettings.json.

In the same way, the sign-out URI would be set to https://localhost:44321/signout-oidc.

Initialization code

The initialization code is different depending on the platform. For ASP.NET Core and ASP.NET, signing in users is delegated to the OpenID Connect middleware. The ASP.NET or ASP.NET Core template generates web applications for the Azure Active Directory (Azure AD) v1.0 endpoint. Some configuration is required to adapt them to the Microsoft identity platform (v2.0) endpoint. In the case of Java, it's handled by Spring with the cooperation of the application.

In ASP.NET Core web apps (and web APIs), the application is protected because you have a [Authorize] attribute on the controllers or the controller actions. This attribute checks that the user is authenticated. The code that's initializing the application is in the Startup.cs file.

To add authentication with the Microsoft identity platform (formerly Azure AD v2.0), you'll need to add the following code. The comments in the code should be self-explanatory.

Note

If you want to start directly with the new ASP.NET Core templates for Microsoft identity platform, that leverage Microsoft.Identity.Web, you can download a preview NuGet package containing project templates for .NET Core 3.1 and .NET 5.0. Then, once installed, you can directly instantiate ASP.NET Core web applications (MVC or Blazor). See Microsoft.Identity.Web web app project templates for details. This is the simplest approach as it will do all the steps below for you.

If you prefer to start your project with the current default ASP.NET Core web project within Visual Studio or by using dotnet new mvc --auth SingleAuth or dotnet new webapp --auth SingleAuth, you'll see code like the following:

 services.AddAuthentication(AzureADDefaults.AuthenticationScheme)
         .AddAzureAD(options => Configuration.Bind("AzureAd", options));

This code uses the legacy Microsoft.AspNetCore.Authentication.AzureAD.UI NuGet package which is used to create an Azure AD v1.0 application. This article explains how to create a Microsoft identity platform (Azure AD v2.0) application which replaces that code.

  1. Add the Microsoft.Identity.Web and Microsoft.Identity.Web.UI NuGet packages to your project. Remove the Microsoft.AspNetCore.Authentication.AzureAD.UI NuGet package if it is present.

  2. Update the code in ConfigureServices so that it uses the AddMicrosoftWebAppAuthentication and AddMicrosoftIdentityUI methods.

    public class Startup
    {
     ...
     // This method gets called by the runtime. Use this method to add services to the container.
     public void ConfigureServices(IServiceCollection services)
     {
      services.AddMicrosoftWebAppAuthentication(Configuration, "AzureAd");
    
      services.AddRazorPages().AddMvcOptions(options =>
      {
       var policy = new AuthorizationPolicyBuilder()
                     .RequireAuthenticatedUser()
                     .Build();
       options.Filters.Add(new AuthorizeFilter(policy));
      }).AddMicrosoftIdentityUI();
    
  3. In the Configure method in Startup.cs, enable authentication with a call to app.UseAuthentication();

    // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
     // more code here
     app.UseAuthentication();
     app.UseAuthorization();
     // more code here
    }
    

In the code above:

  • The AddMicrosoftWebAppAuthentication extension method is defined in Microsoft.Identity.Web. It:

    • Adds the authentication service.
    • Configures options to read the configuration file (here from the "AzureAD" section)
    • Configures the OpenID Connect options so that the authority is the Microsoft identity platform endpoint.
    • Validates the issuer of the token.
    • Ensures that the claims corresponding to name are mapped from the preferred_username claim in the ID token.
  • In addition to the configuration object, you can specify the name of the configuration section when calling AddMicrosoftWebAppAuthentication. By default, it's AzureAd.

  • AddMicrosoftWebAppAuthentication has other parameters for advanced scenarios. For example, tracing OpenID Connect middleware events can help you troubleshoot your web application if authentication doesn't work. Setting the optional parameter subscribeToOpenIdConnectMiddlewareDiagnosticsEvents to true will show you how information is processed by the set of ASP.NET Core middleware as it progresses from the HTTP response to the identity of the user in HttpContext.User.

  • The AddMicrosoftIdentityUI extension method is defined in Microsoft.Identity.Web.UI. It provides a default controller to handle sign-in and sign-out.

You can find more details about how Microsoft.Identity.Web enables you to create web apps in https://aka.ms/ms-id-web/webapp

Warning

Currently, Microsoft.Identity.Web does not support the scenario of Individual User Accounts (storing user accounts in-app) when using Azure AD as and external login provider. For details, see: AzureAD/microsoft-identity-web#133

Next steps

In the next article, you'll learn how to trigger sign-in and sign-out.