Edit

Share via

Tutorial: Set up an ASP.NET Core web app that authenticates users

  • Article

Applies to: Green circle with a white check mark symbol. Workforce tenants Green circle with a white check mark symbol. External tenants (learn more)

In this tutorial, you create an ASP.NET Core web app and configure it for authentication. This is part 1 of a series that demonstrates how to build an ASP.NET Core web application and prepare it for authentication using the Microsoft Entra admin center. This application can be used for employees in a workforce tenant or for customers using an external tenant

In this tutorial:

  • Create an ASP.NET Core web app
  • Create a self-signed certificate
  • Configure the settings for the application
  • Define platform settings and URLs

Prerequisites

  • An Azure account with an active subscription. Create an account for free. This account must have permissions to manage applications. Use any of the following roles needed to register the application:
    • Application Administrator
    • Application Developer
    • Cloud Application Administrator
  • Although any integrated development environment (IDE) that supports ASP.NET Core applications can be used, this tutorial uses Visual Studio Code. You can download it here.
  • A minimum requirement of .NET 8.0 SDK.
  • An ASP.NET Core developer certificate. Install one using dotnet dev-certs
  • A workforce tenant. You can use your Default Directory or set up a new tenant.
  • An application registered in the Microsoft Entra admin center. Use the following setup for the purposes of this tutorial series:
    • Name: identity-client-web-app
    • Supported account types: Accounts in this organizational directory only
    • Redirect URI: https://localhost:5001/signin-oidc
    • Front channel logout URL: https://localhost:5001/signout-oidc
  • For development purposes, create a self signed certificate. Refer to add credentials to upload the certificate and record the certificate Thumbprint. Do not use a self signed certificate for production apps. Use a trusted certificate authority.

Create an ASP.NET Core project

In this section, you'll create an ASP.NET Core project in Visual Studio Code.

  1. Open Visual Studio Code, select File > Open Folder.... Navigate to and select the location in which to create your project.

  2. Open a new terminal by selecting Terminal > New Terminal.

  3. Enter the following command to make a Model View Controller (MVC) ASP.NET Core project.

    dotnet new mvc -n identity-client-web-app

Install identity packages

This application uses Microsoft.Identity.Web and the related NuGet package must be installed.

Use the following snippet to change into the new identity-client-web-app folder and install the relevant NuGet package:

dotnet add package Microsoft.Identity.Web.UI

Configure the application for authentication

The values recorded in your application setup are used to configure the application for authentication. The configuration file, appsettings.json, is used to store application settings used during run-time.

Update the configuration file

In your IDE, open appsettings.json and replace the file contents with the following snippet. Replace the text in quotes with the values that were recorded earlier.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "Enter_the_Tenant_Id_Here",
    "ClientId": "Enter_the_Application_Id_Here",
    "ClientCertificates": [
      {
        "SourceType": "StoreWithThumbprint",
        "CertificateStorePath": "CurrentUser/My",
        "CertificateThumbprint": "Enter the certificate thumbprint obtained the Microsoft Entra admin center"
      }   
    ],
    "CallbackPath": "/signin-oidc"
  },
    "DownstreamApi": {
      "BaseUrl": "https://graph.microsoft.com/v1.0/",
      "RelativePath": "me",
      "Scopes": [ 
        "user.read" 
      ]
    },
    "Logging": {
      "LogLevel": {
        "Default": "Information",
        "Microsoft.AspNetCore": "Warning"
      }
    },
    "AllowedHosts": "*"
  }
  • Instance - The authentication endpoint. Check with the different available endpoints in National clouds.
  • TenantId - The identifier of the tenant where the application is registered. Replace the text in quotes with the Directory (tenant) ID value that was recorded earlier from the overview page of the registered application.
  • ClientId - The identifier of the application, also referred to as the client. Replace the text in quotes with the Application (client) ID value that was recorded earlier from the overview page of the registered application.
  • ClientCertificates - A self-signed certificate is used for authentication in the application. Replace the text of the CertificateThumbprint with the thumbprint of the certificate that was previously recorded. Do not use a self signed certificate for production apps.
  • CallbackPath - Is an identifier to help the server redirect a response to the appropriate application.
  • DownstreamApi - Is an identifier that defines an endpoint for accessing Microsoft Graph. The application URI is combined with the specified scope. To define the configuration for an application owned by the organization, the value of the Scopes attribute is slightly different.

Update the redirect URI

From the prerequisites, the redirect URI is set to https://localhost:5001/signin-oidc. This needs to be updated in the application launch settings. You can use the redirect URI that is created during the local application setup, or any other available port number, provided it matches the redirect URI in the application registration.

  1. In the Properties folder, open the launchSettings.json file.

  2. Find the https object, and update the value of applicationURI with the correct port number, in this case, 5001. The line should look similar to the following snippet:

    "applicationUrl": "https://localhost:5001;http://localhost:{port}",

Next step