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

In this quickstart, you download and run a code sample that demonstrates how an ASP.NET Core web app can sign in users from any Azure Active Directory (Azure AD) organization.

See How the sample works for an illustration.


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 quickstart experience.
  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 add the app's registration information to your solution manually, follow these steps:

  1. Sign in to the Azure portal.
  2. If you have access to multiple tenants, use the Directory + subscription filter in the top menu to select the tenant in which you want to register an application.
  3. Search for and select Azure Active Directory.
  4. Under Manage, select App registrations > New registration.
  5. Enter a Name for your application, for example AspNetCore-Quickstart. Users of your app might see this name, and you can change it later.
  6. Enter a Redirect URI of https://localhost:44321/.
  7. Select Register.
  8. Under Manage, select Authentication.
  9. Under Redirect URIs, select Add URI, and then enter https://localhost:44321/signin-oidc.
  10. Enter a Logout URL of https://localhost:44321/signout-oidc.
  11. Under Implicit grant, select ID tokens.
  12. 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

Run the project.

Step 3: Your app is configured and ready to run

We have configured your project with values of your app's properties and it's ready to run.



Step 3: Configure your ASP.NET Core project

  1. Extract the .zip archive into a local folder near the root of your drive. For example, into C:\Azure-Samples.

  2. Open the solution in Visual Studio 2019.

  3. Open the appsettings.json file and modify the following:

    "ClientId": "Enter_the_Application_Id_here",
    "TenantId": "common",
    • Replace Enter_the_Application_Id_here with the Application (client) ID of the application you registered in the Azure portal. You can find Application (client) ID in the app's Overview page.
    • Replace common with one of the following:
      • If your application supports Accounts in this organizational directory only, replace this value with the Directory (tenant) ID (a GUID) or tenant name (for example, contoso.onmicrosoft.com). You can find the Directory (tenant) ID on the app's Overview page.
      • If your application supports Accounts in any organizational directory, replace this value with organizations
      • If your application supports All Microsoft account users, leave this value as common

For this quickstart, don't change any other values in the appsettings.json file.

Step 4: Build and run the application

Build and run the app in Visual Studio by selecting the Debug menu > Start Debugging, or by pressing the F5 key.

You're prompted for your credentials, and then asked to consent to the permissions your app requires. Select Accept on the consent prompt.

Consent dialog showing the permissions the app is requesting from the > user

After consenting to the requested permissions, the app displays that you've successfully logged in using your Azure Active Directory credentials.

Web browser displaying the running web app and the user signed in

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.

How the sample works

Shows how the sample app generated by this quickstart works

Startup class

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

  public void ConfigureServices(IServiceCollection services)

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

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

The line containing .AddMicrosoftIdentityWebApp adds Microsoft identity platform authentication to your application. It's then configured to sign in using the Microsoft identity platform endpoint based on the information in the AzureAD section of the appsettings.json configuration file:

appsettings.json key Description
ClientId Application (client) ID of the application registered in the Azure portal.
Instance Security token service (STS) endpoint for the user to authenticate. This value is typically https://login.microsoftonline.com/, indicating the Azure public cloud.
TenantId Name of your tenant or its tenant ID (a GUID), or common to sign in users with work or school accounts or Microsoft personal accounts.

The Configure() method contains two important methods, app.UseAuthentication() and app.UseAuthorization(), that enable their named functionality. Also in the Configure() method, you must register Microsoft Identity Web's routes with at least one call to endpoints.MapControllerRoute() or a call to endpoints.MapControllers().


app.UseEndpoints(endpoints =>

        name: "default",
        pattern: "{controller=Home}/{action=Index}/{id?}");

// endpoints.MapControllers(); // REQUIRED if MapControllerRoute() isn't called.

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 about your support options, see Help and support for developers.

Next steps

The GitHub repo that contains this ASP.NET Core tutorial includes instructions and more code samples that show you how to:

  • Add authentication to a new ASP.NET Core Web application
  • Call Microsoft Graph, other Microsoft APIs, or your own web APIs
  • Add authorization
  • Sign in users in national clouds or with social identities