Quickstart: Sign in users and call the Microsoft Graph API from an ASP.NET web app

In this quickstart, you download and run a code sample that demonstrates an ASP.NET web application that can sign in users with Microsoft Entra accounts.

See How the sample works for an illustration.

Prerequisites

• An Azure account with an active subscription. Create an account.
• Visual Studio 2022
• .NET Framework 4.7.2+

Register and download the app

You have two options to start building your application: automatic or manual configuration.

Automatic configuration

If you want to automatically configure your app and then download the code sample, follow these steps:

1. Sign in to the Microsoft Entra admin center quickstart experience as at least a Cloud Application Administrator.
2. Enter a name for your application and select Register.
3. Follow the instructions to download and automatically configure your new application in one click.

Manual configuration

If you want to manually configure your application and code sample, use the following procedures.

Step 1: Register your application

1. Sign in to the Microsoft Entra admin center as at least a Cloud Application Administrator.
2. If you have access to multiple tenants, use the Settings icon in the top menu to switch to the tenant in which you want to register the application from the Directories + subscriptions menu.
3. Browse to Identity > Applications > App registrations and select New registration.
4. For Name, enter a name for your application. For example, enter ASPNET-Quickstart. Users of your app will see this name, and you can change it later.
5. Set the Redirect URI type to Web and value to https://localhost:44368/.
6. Select Register.
7. Under Manage, select Authentication.
8. In the Implicit grant and hybrid flows section, select ID tokens.
9. Select Save.

Step 2: Download the project

Download the ASP.NET code sample

Step 3: Run the project

1. Extract the .zip file to a local folder that's close to the root folder. For example, extract to C:\Azure-Samples.

   We recommend extracting the archive into a directory near the root of your drive to avoid errors caused by path length limitations on Windows.

2. Open the solution in Visual Studio (AppModelv2-WebApp-OpenIDConnect-DotNet.sln).

3. Depending on the version of Visual Studio, you might need to right-click the project AppModelv2-WebApp-OpenIDConnect-DotNet and then select Restore NuGet packages.

4. Open the Package Manager Console by selecting View > Other Windows > Package Manager Console. Then run Update-Package.

5. Edit appsettings.json and replace the parameters ClientId, Tenant, and redirectUri with:

   "ClientId" :"Enter_the_Application_Id_here" />
   "TenantId": "Enter_the_Tenant_Info_Here" />
   "RedirectUri" :"https://localhost:44368/" />
   

   In that code:

   • Enter_the_Application_Id_here is the application (client) ID of the app registration that you created earlier. Find the application (client) ID on the app's Overview page in App registrations in the Microsoft Entra admin center.

   • Enter_the_Tenant_Info_Here is one of the following options:

     • If your application supports My organization only, replace this value with the directory (tenant) ID or tenant name (for example, contoso.partner.onmschina.cn). Find the directory (tenant) ID on the app's Overview page in App registrations in the Microsoft Entra admin center.
     • If your application supports Accounts in any organizational directory, replace this value with organizations.

   • redirectUri is the Redirect URI you entered earlier in App registrations in the Microsoft Entra admin center.

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, what the main arguments are, and how to add sign-in to an existing ASP.NET application.

How the sample works

OWIN middleware NuGet packages

You can set up the authentication pipeline with cookie-based authentication by using OpenID Connect in ASP.NET with OWIN middleware packages. You can install these packages by running the following commands in Package Manager Console within Visual Studio:

Install-Package Microsoft.Identity.Web.Owin
Install-Package Microsoft.Identity.Web.GraphServiceClient
Install-Package Microsoft.Owin.Security.Cookies

OWIN startup class

The OWIN middleware uses a startup class that runs when the hosting process starts. In this quickstart, the startup.cs file is in the root folder. The following code shows the parameters that this quickstart uses:

    public void Configuration(IAppBuilder app)
    {
        app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);

        app.UseCookieAuthentication(new CookieAuthenticationOptions());
        OwinTokenAcquirerFactory factory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();

        app.AddMicrosoftIdentityWebApp(factory);
        factory.Services
            .Configure<ConfidentialClientApplicationOptions>(options => { options.RedirectUri = "https://localhost:44368/"; })
            .AddMicrosoftGraph()
            .AddInMemoryTokenCaches();
        factory.Build();
    }

Where	Description
ClientId	The application ID from the application registered in the Azure portal.
Authority	The security token service (STS) endpoint for the user to authenticate. It's usually https://login.partner.microsoftonline.cn/{tenant}/v2.0 for the public cloud. In that URL, {tenant} is the name of your tenant, your tenant ID, or common for a reference to the common endpoint. (The common endpoint is used for multitenant applications.)
RedirectUri	The URL where users are sent after authentication against the Microsoft identity platform.
PostLogoutRedirectUri	The URL where users are sent after signing off.
Scope	The list of scopes being requested, separated by spaces.
ResponseType	The request that the response from authentication contains an authorization code and an ID token.
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 work, or school account type.
Notifications	A list of delegates that can be run on OpenIdConnect messages.

Authentication challenge

You can force a user to sign in by requesting an authentication challenge in your controller:

public void SignIn()
{
    if (!Request.IsAuthenticated)
    {
        HttpContext.GetOwinContext().Authentication.Challenge(
            new AuthenticationProperties{ RedirectUri = "/" },
            OpenIdConnectAuthenticationDefaults.AuthenticationType);
    }
}

Attribute for protecting a controller or a controller actions

You can protect a controller or controller actions by using the [Authorize] attribute. This attribute restricts access to the controller or actions by allowing only authenticated users to access the actions in the controller. An authentication challenge will then happen automatically when an unauthenticated user tries to access one of the actions or controllers decorated by the [Authorize] attribute.

Call Microsoft Graph from the controller

You can call Microsoft Graph from the controller by getting the instance of GraphServiceClient using the GetGraphServiceClient extension method on the controller, like in the following code:

    try
    { 
        var me = await this.GetGraphServiceClient().Me.GetAsync();
        ViewBag.Username = me.DisplayName;
    }
    catch (ServiceException graphEx) when (graphEx.InnerException is MicrosoftIdentityWebChallengeUserException)
    {
        HttpContext.GetOwinContext().Authentication.Challenge(OpenIdConnectAuthenticationDefaults.AuthenticationType);
        return View();
    }

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

For a complete step-by-step guide on building applications and new features, including a full explanation of this quickstart, try out the ASP.NET tutorial.