Tutorial: Create an ASP.NET web app that uses the Microsoft identity platform for authentication - Microsoft Entra

Article
01/30/2023
14 minutes to read

In this tutorial, you build an ASP.NET MVC web app that signs in users by using the Open Web Interface for .NET (OWIN) middleware and the Microsoft identity platform.

When you've completed this guide, your application will be able to accept sign-ins of personal accounts from the likes of outlook.com and live.com. Additionally, work and school accounts from any company or organization that's integrated with the Microsoft identity platform will be able to sign in to your app.

In this tutorial:

Create an ASP.NET Web Application project in Visual Studio
Add the Open Web Interface for .NET (OWIN) middleware components
Add code to support user sign-in and sign-out
Register the app in the Azure portal
Test the app

Prerequisites

Visual Studio 2019 with the ASP.NET and web development workload installed

How the sample app generated by this guide works

Shows how the sample app generated by this tutorial works

The sample application you create is based on a scenario where you use the browser to access an ASP.NET website that prompts a user to authenticate through a sign-in button. In this scenario, most of the work to render the web page occurs on the server side.

Libraries

This guide uses the following libraries:

Library	Description
Microsoft.Owin.Security.OpenIdConnect	Middleware that enables an application to use OpenIdConnect for authentication
Microsoft.Owin.Security.Cookies	Middleware that enables an application to maintain a user session by using cookies
Microsoft.Owin.Host.SystemWeb	Middleware that enables OWIN-based applications to run on Internet Information Services (IIS) by using the ASP.NET request pipeline

Set up your project

This section describes how to install and configure the authentication pipeline through OWIN middleware on an ASP.NET project by using OpenID Connect.

Prefer to download this sample's Visual Studio project instead? Download a project and skip to the Register your application to configure the code sample before executing.

Create your ASP.NET project

In Visual Studio: Go to File > New > Project.
Under Visual C#\Web, select ASP.NET Web Application (.NET Framework).
Name your application and select OK.
Select Empty, and then select the check box to add MVC references.

Add authentication components

In Visual Studio: Go to Tools > NuGet Package Manager > Package Manager Console.

Add OWIN middleware NuGet packages by typing the following in the Package Manager Console window:

Install-Package Microsoft.Owin.Security.OpenIdConnect
Install-Package Microsoft.Owin.Security.Cookies
Install-Package Microsoft.Owin.Host.SystemWeb

About these libraries

These libraries enable single sign-on (SSO) by using OpenID Connect through cookie-based authentication. After authentication is completed and the token representing the user is sent to your application, OWIN middleware creates a session cookie. The browser then uses this cookie on subsequent requests so that the user doesn't have to retype the password, and no other verification is needed.

Configure the authentication pipeline

The following steps are used to create an OWIN middleware Startup class to configure OpenID Connect authentication. This class is executed automatically when your IIS process starts.

Tip

If your project doesn't have a Startup.cs file in the root folder:

Right-click the project's root folder, and then select Add > New Item > OWIN Startup class.
Name it Startup.cs.

Make sure the class selected is an OWIN Startup class and not a standard C# class. Confirm this by verifying that you see [assembly: OwinStartup(typeof({NameSpace}.Startup))] above the namespace.

Add OWIN and Microsoft.IdentityModel references to Startup.cs:

using Microsoft.Owin;
using Owin;
using Microsoft.IdentityModel.Protocols.OpenIdConnect;
using Microsoft.IdentityModel.Tokens;
using Microsoft.Owin.Security;
using Microsoft.Owin.Security.Cookies;
using Microsoft.Owin.Security.OpenIdConnect;
using Microsoft.Owin.Security.Notifications;

Replace Startup class with the following code:

public class Startup
{
    // The Client ID is used by the application to uniquely identify itself to Microsoft identity platform.
    string clientId = System.Configuration.ConfigurationManager.AppSettings["ClientId"];

    // RedirectUri is the URL where the user will be redirected to after they sign in.
    string redirectUri = System.Configuration.ConfigurationManager.AppSettings["RedirectUri"];

    // Tenant is the tenant ID (e.g. contoso.onmicrosoft.com, or 'common' for multi-tenant)
    static string tenant = System.Configuration.ConfigurationManager.AppSettings["Tenant"];

    // Authority is the URL for authority, composed of the Microsoft identity platform and the tenant name (e.g. https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0)
    string authority = String.Format(System.Globalization.CultureInfo.InvariantCulture, System.Configuration.ConfigurationManager.AppSettings["Authority"], tenant);

    /// <summary>
    /// Configure OWIN to use OpenIdConnect
    /// </summary>
    /// <param name="app"></param>
    public void Configuration(IAppBuilder app)
    {
        app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);

        app.UseCookieAuthentication(new CookieAuthenticationOptions());
        app.UseOpenIdConnectAuthentication(
            new OpenIdConnectAuthenticationOptions
            {
                // Sets the ClientId, authority, RedirectUri as obtained from web.config
                ClientId = clientId,
                Authority = authority,
                RedirectUri = redirectUri,
                // PostLogoutRedirectUri is the page that users will be redirected to after sign-out. In this case, it is using the home page
                PostLogoutRedirectUri = redirectUri,
                Scope = OpenIdConnectScope.OpenIdProfile,
                // ResponseType is set to request the code id_token - which contains basic information about the signed-in user
                ResponseType = OpenIdConnectResponseType.CodeIdToken,
                // ValidateIssuer set to false to allow personal and work accounts from any organization to sign in to your application
                // To only allow users from a single organizations, set ValidateIssuer to true and 'tenant' setting in web.config to the tenant name
                // To allow users from only a list of specific organizations, set ValidateIssuer to true and use ValidIssuers parameter
                TokenValidationParameters = new TokenValidationParameters()
                {
                    ValidateIssuer = false // This is a simplification
                },
                // OpenIdConnectAuthenticationNotifications configures OWIN to send notification of failed authentications to OnAuthenticationFailed method
                Notifications = new OpenIdConnectAuthenticationNotifications
                {
                    AuthenticationFailed = OnAuthenticationFailed
                }
            }
        );
    }

    /// <summary>
    /// Handle failed authentication requests by redirecting the user to the home page with an error in the query string
    /// </summary>
    /// <param name="context"></param>
    /// <returns></returns>
    private Task OnAuthenticationFailed(AuthenticationFailedNotification<OpenIdConnectMessage, OpenIdConnectAuthenticationOptions> context)
    {
        context.HandleResponse();
        context.Response.Redirect("/?errormessage=" + context.Exception.Message);
        return Task.FromResult(0);
    }
}

Note

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

More information

The parameters you provide in OpenIDConnectAuthenticationOptions serve as coordinates for the application to communicate with Microsoft identity platform. Because the OpenID Connect middleware uses cookies in the background, you must also set up cookie authentication as the preceding code shows. The ValidateIssuer value tells OpenIdConnect not to restrict access to one specific organization.

To create a new controller to expose sign-in and sign-out methods, follow these steps:

Right-click the Controllers folder and select Add > Controller.
Select MVC (.NET version) Controller – Empty.
Select Add.
Name it HomeController and then select Add.

Add OWIN references to the class:

using Microsoft.Owin.Security;
using Microsoft.Owin.Security.Cookies;
using Microsoft.Owin.Security.OpenIdConnect;

Add the following two methods to handle sign-in and sign-out to your controller by initiating an authentication challenge:

/// <summary>
/// Send an OpenID Connect sign-in request.
/// Alternatively, you can just decorate the SignIn method with the [Authorize] attribute
/// </summary>
public void SignIn()
{
    if (!Request.IsAuthenticated)
    {
        HttpContext.GetOwinContext().Authentication.Challenge(
            new AuthenticationProperties{ RedirectUri = "/" },
            OpenIdConnectAuthenticationDefaults.AuthenticationType);
    }
}

/// <summary>
/// Send an OpenID Connect sign-out request.
/// </summary>
public void SignOut()
{
    HttpContext.GetOwinContext().Authentication.SignOut(
            OpenIdConnectAuthenticationDefaults.AuthenticationType,
            CookieAuthenticationDefaults.AuthenticationType);
}

In Visual Studio, create a new view to add the sign-in button and to display user information after authentication:

Right-click the Views\Home folder and select Add View.
Name the new view Index.

Add the following HTML, which includes the sign-in button, to the file:

<html>
<head>
    <meta name="viewport" content="width=device-width" />
    <title>Sign in with Microsoft Guide</title>
</head>
<body>
@if (!Request.IsAuthenticated)
{
    <!-- If the user is not authenticated, display the sign-in button -->
    <a href="@Url.Action("SignIn", "Home")" style="text-decoration: none;">
        <svg xmlns="http://www.w3.org/2000/svg" xml:space="preserve" width="300px" height="50px" viewBox="0 0 3278 522" class="SignInButton">
        <style type="text/css">.fil0:hover {fill: #4B4B4B;} .fnt0 {font-size: 260px;font-family: 'Segoe UI Semibold', 'Segoe UI'; text-decoration: none;}</style>
        <rect class="fil0" x="2" y="2" width="3174" height="517" fill="black" />
        <rect x="150" y="129" width="122" height="122" fill="#F35325" />
        <rect x="284" y="129" width="122" height="122" fill="#81BC06" />
        <rect x="150" y="263" width="122" height="122" fill="#05A6F0" />
        <rect x="284" y="263" width="122" height="122" fill="#FFBA08" />
        <text x="470" y="357" fill="white" class="fnt0">Sign in with Microsoft</text>
        </svg>
    </a>
}
else
{
    <span><br/>Hello @System.Security.Claims.ClaimsPrincipal.Current.FindFirst("name").Value;</span>
    <br /><br />
    @Html.ActionLink("See Your Claims", "Index", "Claims")
    <br /><br />
    @Html.ActionLink("Sign out", "SignOut", "Home")
}
@if (!string.IsNullOrWhiteSpace(Request.QueryString["errormessage"]))
{
    <div style="background-color:red;color:white;font-weight: bold;">Error: @Request.QueryString["errormessage"]</div>
}
</body>
</html>

More information

This page adds a sign-in button in SVG format with a black background:
Sign in with Microsoft button
For more sign-in buttons, go to the Branding guidelines.

Add a controller to display user's claims

This controller demonstrates the uses of the [Authorize] attribute to protect a controller. This attribute restricts access to the controller by allowing only authenticated users. The following code makes use of the attribute to display user claims that were retrieved as part of sign-in:

Right-click the Controllers folder, and then select Add > Controller.
Select MVC {version} Controller – Empty.
Select Add.
Name it ClaimsController.

Replace the code of your controller class with the following code. The code adds the [Authorize] attribute to the class:

[Authorize]
public class ClaimsController : Controller
{
    /// <summary>
    /// Add user's claims to viewbag
    /// </summary>
    /// <returns></returns>
    public ActionResult Index()
    {
        var userClaims = User.Identity as System.Security.Claims.ClaimsIdentity;

        //You get the user's first and last name below:
        ViewBag.Name = userClaims?.FindFirst("name")?.Value;

        // The 'preferred_username' claim can be used for showing the username
        ViewBag.Username = userClaims?.FindFirst("preferred_username")?.Value;

        // The subject/ NameIdentifier claim can be used to uniquely identify the user across the web
        ViewBag.Subject = userClaims?.FindFirst(System.Security.Claims.ClaimTypes.NameIdentifier)?.Value;

        // TenantId is the unique Tenant Id - which represents an organization in Azure AD
        ViewBag.TenantId = userClaims?.FindFirst("http://schemas.microsoft.com/identity/claims/tenantid")?.Value;

        return View();
    }
}

More information

Because of the use of the [Authorize] attribute, all methods of this controller can be executed only if the user is authenticated. If the user isn't authenticated and tries to access the controller, OWIN initiates an authentication challenge, and forces the user to authenticate. The preceding code looks at the list of claims for specific user attributes included in the user's ID token. These attributes include the user's full name and username, and the global user identifier subject. It also contains the Tenant ID, which represents the ID for the user's organization.

Create a view to display the user's claims

In Visual Studio, create a new view to display the user's claims in a web page:

Right-click the Views\Claims folder, and then select Add View.
Name the new view Index.

Add the following HTML to the file:

<html>
  <head>
    <meta name="viewport" content="width=device-width" />
    <title>Sign in with Microsoft Sample</title>
    <link href="@Url.Content("~/Content/bootstrap.min.css")" rel="stylesheet"
    type="text/css" />
  </head>
  <body style="padding:50px">
    <h3>Main Claims:</h3>
    <table class="table table-striped table-bordered table-hover">
      <tr>
        <td>Name</td>
        <td>@ViewBag.Name</td>
      </tr>
      <tr>
        <td>Username</td>
        <td>@ViewBag.Username</td>
      </tr>
      <tr>
        <td>Subject</td>
        <td>@ViewBag.Subject</td>
      </tr>
      <tr>
        <td>TenantId</td>
        <td>@ViewBag.TenantId</td>
      </tr>
    </table>
    <br />
    <h3>All Claims:</h3>
    <table
      class="table table-striped table-bordered table-hover table-condensed"
    >
      @foreach (var claim in
      System.Security.Claims.ClaimsPrincipal.Current.Claims) {
      <tr>
        <td>@claim.Type</td>
        <td>@claim.Value</td>
      </tr>
      }
    </table>
    <br />
    <br />
    @Html.ActionLink("Sign out", "SignOut", "Home", null, new { @class = "btn
    btn-primary" })
  </body>
</html>

Register your application

To register your application and add your application registration information to your solution, you have two options:

Option 1: Express mode

To quickly register your application, follow these steps:

Go to the Azure portal - App registrations quickstart experience.
Enter a name for your application and select Register.
Follow the instructions to download and automatically configure your new application in a single click.

Option 2: Advanced mode

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

Open Visual Studio, and then:
1. in Solution Explorer, select the project and view the Properties window (if you don't see a Properties window, press F4).
2. Change SSL Enabled to True.
3. Right-click the project in Visual Studio, select Properties, and then select the Web tab. In the Servers section, change the Project Url setting to the SSL URL.
4. Copy the SSL URL. You'll add this URL to the list of Redirect URIs in the Registration portal's list of Redirect URIs in the next step.
Sign in to the Azure portal.
If you have access to multiple tenants, use the Directories + subscriptions filter in the top menu to switch to the tenant in which you want to register the application.
Search for and select Azure Active Directory.
Under Manage, select App registrations > New registration.
Enter a Name for your application, for example ASPNET-Tutorial. Users of your app might see this name, and you can change it later.
Add the SSL URL you copied from Visual Studio in step 1 (for example, https://localhost:44368/) in Redirect URI.
Select Register.
Under Manage, select Authentication.
In the Implicit grant and hybrid flows section, select ID tokens, and then select Save.

Add the following code in the web.config file, located in the root folder in the configuration\appSettings section:

<add key="ClientId" value="Enter_the_Application_Id_here" />
<add key="redirectUri" value="Enter_the_Redirect_URL_here" />
<add key="Tenant" value="common" />
<add key="Authority" value="https://login.microsoftonline.com/{0}/v2.0" />

Replace ClientId with the Application ID you registered.
Replace redirectUri with the SSL URL of your project.

Test your code

To test your application in Visual Studio, press F5 to run your project. The browser opens to the http://localhost:{port} location, and you see the Sign in with Microsoft button. Select the button to start the sign-in process.

When you're ready to run your test, use an Azure AD account (work, or school account) or a personal Microsoft account (live.com or outlook.com) to sign in.

Applications that integrate with the Microsoft identity platform follow an authorization model that gives users and administrators control over how data can be accessed. After a user authenticates with the Microsoft identity platform to access this application, they'll be prompted to consent to the permissions requested by the application ("View your basic profile", and "Maintain access to data you've given it access to"). The user consent to permissions and continue to application results. However, the user may instead be prompted with a Need admin consent page if either of the following occur:

The application developer adds any more permissions that require Admin consent.
Or the tenant is configured (in Enterprise Applications -> User Settings) where users can't consent to apps accessing company data on their behalf.

For more information, see Permissions and consent in the Microsoft identity platform.

View application results

After you sign in, the user is redirected to the home page of your website. The home page is the HTTPS URL that's specified in your application registration info in the Microsoft Application Registration Portal. The home page includes a "Hello <user>" welcome message, a link to sign out, and a link to view the user's claims. The link for the user's claims connects to the Claims controller that you created earlier.

View the user's claims

To view the user's claims, select the link to browse to the controller view that's available only to authenticated users.

View the claims results

After you browse to the controller view, you should see a table that contains the basic properties for the user:

Property	Value	Description
Name	User's full name	The user's first and last name
Username	user@domain.com	The username that's used to identify the user
Subject	Subject	A string that uniquely identifies the user across the web
Tenant ID	Guid	A guid that uniquely represents the user's Azure AD organization

Additionally, you should see a table of all claims that are in the authentication request. For more information, see the list of claims that are in an ID token.

Test access to a method that has an Authorize attribute (optional)

To test access as an anonymous user to a controller that's protected by the Authorize attribute, follow these steps:

Select the link to sign out the user, and complete the sign-out process.
In your browser, type http://localhost:{port}/claims to access your controller that's protected by the Authorize attribute.

Expected results after access to a protected controller

You're prompted to authenticate to use the protected controller view.

Advanced options

Protect your entire website

To protect your entire website, in the Global.asax file, add the AuthorizeAttribute attribute to the GlobalFilters filter in the Application_Start method:

GlobalFilters.Filters.Add(new AuthorizeAttribute());

By default when you build the application created by this guide, your application will accept sign-ins of personal accounts (including outlook.com, live.com, and others) as well as work and school accounts from any company or organization that's integrated with Microsoft identity platform. This is a recommended option for SaaS applications.

To restrict user sign-in access for your application, multiple options are available.

This option is frequently used for LOB applications: If you want your application to accept sign-ins only from accounts that belong to a specific Azure AD instance (including guest accounts of that instance), follow these steps:

In the web.config file, change the value for the Tenant parameter from Common to the tenant name of the organization, such as contoso.onmicrosoft.com.
In your OWIN Startup class, set the ValidateIssuer argument to true.

Option 2: Restrict access to users in a specific list of organizations

You can restrict sign-in access to only those user accounts that are in an Azure AD organization that's on the list of allowed organizations:

In your OWIN Startup class, set the ValidateIssuer argument to true.
Set the value of the ValidIssuers parameter to the list of allowed organizations.

Option 3: Use a custom method to validate issuers

You can implement a custom method to validate issuers by using the IssuerValidator parameter. For more information about how to use this parameter, see TokenValidationParameters class.

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

Learn about calling protected web APIs from web apps with the Microsoft identity platform:

Web apps calling web APIs

Prerequisites

How the sample app generated by this guide works

Libraries

Set up your project

Create your ASP.NET project

Add authentication components

About these libraries

Configure the authentication pipeline

More information

More information

Add a controller to display user's claims

More information

Create a view to display the user's claims

Register your application

Option 1: Express mode

Option 2: Advanced mode

Test your code

View application results

View the user's claims

View the claims results

Test access to a method that has an Authorize attribute (optional)

Expected results after access to a protected controller

Advanced options

Protect your entire website

Option 2: Restrict access to users in a specific list of organizations

Option 3: Use a custom method to validate issuers

Help and support

Next steps

Feedback

Additional resources

Additional resources

Tutorial: Add sign-in to Microsoft to an ASP.NET web app

Prerequisites

How the sample app generated by this guide works

Libraries

Set up your project

Create your ASP.NET project

Add authentication components

About these libraries

Configure the authentication pipeline

More information

Add a controller to handle sign-in and sign-out requests

Create the app's home page for user sign-in

More information

Add a controller to display user's claims

More information

Create a view to display the user's claims

Register your application

Option 1: Express mode

Option 2: Advanced mode

Test your code

Permissions and consent in the Microsoft identity platform

View application results

View the user's claims

View the claims results

Test access to a method that has an Authorize attribute (optional)

Expected results after access to a protected controller

Advanced options

Protect your entire website

Restrict who can sign in to your application

Option 1: Restrict users from only one organization's Active Directory instance to sign in to your application (single-tenant)

Option 2: Restrict access to users in a specific list of organizations

Option 3: Use a custom method to validate issuers

Help and support

Next steps

Feedback

Additional resources

Additional resources