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

Applies to:
  • Azure AD v2.0 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.

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 (Preview).
  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. In the left-hand navigation pane, select the Azure Active Directory service, and then select App registrations (Preview) > New registration.
  4. 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 Reply URL, add https://localhost:44321/, and select Register.
  5. Select the Authentication menu, and then add the following information:
    • In Reply URL, add https://localhost:44321/signin-oidc, and select Register.
    • 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 2017, open the solution in Visual Studio (optional).
  3. Edit the appsettings.json file. Find ClientId and replace Enter_the_Application_Id_here with the Application (client) ID value of the application you just registered.

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


  • 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


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 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;

          .AddAzureAD(options => Configuration.Bind("AzureAd", options));

  services.Configure<OpenIdConnectOptions>(AzureADDefaults.OpenIdScheme, options =>
    options.Authority = options.Authority + "/v2.0/";         // Azure AD v2.0

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

  services.AddMvc(options =>
     var policy = new AuthorizationPolicyBuilder()
     options.Filters.Add(new AuthorizeFilter(policy));

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

The line containing .AddAzureAd adds the Azure AD authentication to your application. It's then configured to sign-in using the Azure AD v2.0 endpoint.

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.

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 is not 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 quickstart for more information including instructions on how to add authentication to a brand new ASP.NET Core Web application: