Quickstart: Add sign-in with Microsoft to an ASP.NET Core web app

Applies to:
  • Microsoft identity platform endpoint

In this quickstart, you'll learn how an ASP.NET Core web app can sign in personal accounts (hotmail.com, outlook.com, others) and work and school accounts from any Azure Active Directory (Azure AD) instance.

Shows how the sample app generated by this quickstart works

Register and download your quickstart app

You have two options to start your quickstart application:

Option 1: Register and auto configure your app and then download your code sample

  1. Go to the Azure portal - App registrations.
  2. Enter a name for your application and select Register.
  3. Follow the instructions to download and automatically configure your new application for you in one click.

Option 2: Register and manually configure your application and code sample

Step 1: Register your application

To register your application and manually add the app's registration information to your solution, follow these steps:

  1. Sign in to the Azure portal using either a work or school account, or a personal Microsoft account.
  2. If your account gives you access to more than one tenant, select your account in the top right corner, and set your portal session to the desired Azure AD tenant.
  3. Navigate to the Microsoft identity platform for developers App registrations page.
  4. Select New registration.
  5. When the Register an application page appears, enter your application's registration information:
    • In the Name section, enter a meaningful application name that will be displayed to users of the app, for example AspNetCore-Quickstart.
    • In Redirect URI, add https://localhost:44321/, and select Register.
  6. Select the Authentication menu, and then add the following information:
    • In Redirect URIs, add https://localhost:44321/signin-oidc, and select Save.
    • In the Advanced settings section, set Logout URL to https://localhost:44321/signout-oidc.
    • Under Implicit grant, check ID tokens.
    • Select Save.

Step 1: Configure your application in the Azure portal

For the code sample for this quickstart to work, you need to add reply URLs as https://localhost:44321/ and https://localhost:44321/signin-oidc, add the Logout URL as https://localhost:44321/signout-oidc, and request ID tokens to be issued by the authorization endpoint.

Already configured Your application is configured with these attributes.

Step 2: Download your ASP.NET Core project

Step 3: Configure your Visual Studio project

  1. Extract the zip file to a local folder within the root folder - for example, C:\Azure-Samples

  2. If you use Visual Studio 2019, open the solution in Visual Studio (optional).

  3. Edit the appsettings.json file. Find ClientId and update the value of ClientId with the Application (client) ID value of the application you registered.

    "ClientId": "Enter_the_Application_Id_here"
    "TenantId": "Enter_the_Tenant_Info_Here"
    

Note

This quickstart supports Enter_the_Supported_Account_Info_Here.

Where:

  • Enter_the_Application_Id_here - is the Application (client) ID for the application you registered in the Azure portal. You can find Application (client) ID in the app's Overview page.
  • Enter_the_Tenant_Info_Here - is one of the following options:
    • If your application supports Accounts in this organizational directory only, replace this value with the Tenant ID or Tenant name (for example, contoso.microsoft.com)
    • If your application supports Accounts in any organizational directory, replace this value with organizations
    • If your application supports All Microsoft account users, replace this value with common

Tip

To find the values of Application (client) ID, Directory (tenant) ID, and Supported account types, go to the app's Overview page in the Azure portal.

More information

This section gives an overview of the code required to sign in users. This overview can be useful to understand how the code works, main arguments, and also if you want to add sign-in to an existing ASP.NET Core application.

Startup class

Microsoft.AspNetCore.Authentication middleware uses a Startup class that is executed when the hosting process initializes:

public void ConfigureServices(IServiceCollection services)
{
  services.Configure<CookiePolicyOptions>(options =>
  {
    // This lambda determines whether user consent for non-essential cookies is needed for a given request.
    options.CheckConsentNeeded = context => true;
    options.MinimumSameSitePolicy = SameSiteMode.None;
  });

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

  services.Configure<OpenIdConnectOptions>(AzureADDefaults.OpenIdScheme, options =>
  {
    options.Authority = options.Authority + "/v2.0/";         // Microsoft identity platform

    options.TokenValidationParameters.ValidateIssuer = false; // accept several tenants (here simplified)
  });

  services.AddMvc(options =>
  {
     var policy = new AuthorizationPolicyBuilder()
                     .RequireAuthenticatedUser()
                     .Build();
     options.Filters.Add(new AuthorizeFilter(policy));
  })
  .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
}

The method AddAuthentication configures the service to add cookie-based authentication, which is used on browser scenarios and to set the challenge to OpenID Connect.

The line containing .AddAzureAd adds the Microsoft identity platform authentication to your application. It's then configured to sign in using the Microsoft identity platform endpoint.

Where
ClientId Application (client) ID from the application registered in the Azure portal.
Authority The STS endpoint for the user to authenticate. Usually, this is https://login.microsoftonline.com/{tenant}/v2.0 for public cloud, where {tenant} is the name of your tenant or your tenant ID, or common for a reference to the common endpoint (used for multi-tenant applications)
TokenValidationParameters A list of parameters for token validation. In this case, ValidateIssuer is set to false to indicate that it can accept sign-ins from any personal, or work or school accounts.

Note

Setting ValidateIssuer = false is a simplification for this quickstart. In real applications you need to validate the issuer. See the samples to understand how to do that.

Protect a controller or a controller's method

You can protect a controller or controller methods using the [Authorize] attribute. This attribute restricts access to the controller or methods by only allowing authenticated users, which means that authentication challenge can be started to access the controller if the user isn't authenticated.

Help and support

If you need help, want to report an issue, or want to learn more about your support options, see the following article:

Next steps

Check out the GitHub repo for this ASP.NET Core tutorial for more information including instructions on how to add authentication to a brand new ASP.NET Core Web application, how to call Microsoft Graph, and other Microsoft APIs, how to call your own APIs, how to add authorization, how to sign in users in national clouds, or with social identities and more:

Help us improve the Microsoft identity platform. Tell us what you think by completing a short two-question survey.