Kailash_pic

Kailash B is a developer at Auth0. He is passionate about simplifying identity and access management for .NET developers, deeply committed to enhancing developer experience within the complex world of IAM.

Senior Software Engineer

Kailash B

Announcing the new Auth0 ASP.NET Core API SDK. Simplify API security with built-in DPoP support, JWT Bearer compatibility, flexible configuration, and zero lock-in.

A New Auth0 ASP.NET SDK to Secure Your API


andrea-chiarelli

I have over 20 years of experience as a software engineer and technical author. Throughout my career, I've used several programming languages and technologies for the projects I was involved in, ranging from C# to JavaScript, ASP.NET to Node.js, Angular to React, SOAP to REST APIs, etc.

In the last few years, I've been focusing on simplifying the developer experience with Identity and related topics, especially in the .NET ecosystem.

Principal Developer Advocate

Andrea Chiarelli

Learn how to implement fine-grained, relationship-based authorization in an ASP.NET Core minimal API using Auth0 FGA.

Fine-Grained Authorization in ASP.NET Core with Auth0 FGA

Checking your customers' email addresses is a basic rule for securely onboarding them in your B2B SaaS application. Learn how to do it in your Blazor Web App.

The very first thing to do when a user signs up for your application is to verify that they actually have access to the email address they provide. Although email verification is not the only security measure you should take to ensure the user's identity, this contributes to reducing spam and fraud. Auth0 provides [a few approaches to email verification](https://auth0.com/docs/manage-users/user-accounts/verify-emails), depending on your specific use case. In this article, you will learn how to leverage the built-in email verification process based on verification links to validate the email address provided by the user during their signup for a Blazor Web application.

## The Sample Application

A previous article showed [how to manage the onboarding of a customer](https://auth0.com/blog/enable-self-subscription-in-blazor-b2b-saas-application/) who signs up for a service offered by a B2B SaaS application implemented with Blazor. On that occasion, we did not consider verifying the client's email address as we wanted to focus mainly on self-registration and creating an Organization via code. Now, we will integrate that application by adding the verification step for the self-registering customer's email address.

Download the sample project to start with this command:

```shell
git clone --branch organization-via-code --single-branch https://github.com/andychiare/MyBlazorSaaS
```

Follow the attached README file instructions to register and configure the application with Auth0. If you don't have an Auth0 account, [you can sign up for free](https://a0.to/blog_signup).

## The Email Verification Process

By default, Auth0 sends a verification link to users when they sign up, but it's up to you to check if their email is verified before allowing them to access your application or perform specific actions.

In the context of your Blazor application, you will implement the following email verification process:

1. Once the customer signs up, Auth0 automatically sends an email to the user, and your application shows a message inviting the user to check their inbox.
2. The page showing the message provides a button to resend a new verification link in case the user didn't receive the first email.
3. If the user attempts to access any other application page, your app checks if the user's email has been verified before granting access.
4. Once the email is verified, the customer can create the Organization for their new subscription.

## Wait for Email Verification

The current customer onboarding flow implemented in your Blazor App allows users to create their Organizations as soon as they sign up. From a visual perspective, they pass from the signup form to the Organization creation form. You need to make sure the customer's email has been verified before allowing them to create their new Organization. Let's start by implementing a page that fulfills points 1. and 2. mentioned earlier.

### The verification waiting page

In the `MyBlazorSaaS/Components/Pages/Onboarding` folder, create a new file named `Verify.razor` and add the following code:

```csharp


@page "/Onboarding/Verify"
@rendermode InteractiveServer
@using Auth0.ManagementApi.Models
@using System.Security.Claims

@inject NavigationManager NavigationManager
@inject IAuth0Management auth0Management

<h1>Verify your email</h1>
<p>
 Please check your inbox for a verification link to continue creating your account.
</p>

<div>
  <button class="btn btn-primary" @onclick="ResendVerificationEmail">Resend Verification</button>
</div>

<div>
@Message
</div>

@code {
  [CascadingParameter]
  private Task<AuthenticationState>? authenticationState { get; set; }
  private string Message = "";

  private async Task ResendVerificationEmail()
  {
    if (authenticationState is not null)
    {
      var state = await authenticationState;
      var userId = state?.User?.FindFirst(c => c.Type == ClaimTypes.NameIdentifier)?.Value;

      try {
        var managementClient = await auth0Management.getClient();
        await managementClient.Jobs.SendVerificationEmailAsync(new VerifyEmailJobRequest() { UserId = userId });
        Message = "The verification e-mail has successfully been sent. Please check your inbox";
      } catch (Exception) {
        Message = "Failed to resend verification e-mail.";
      }      
    } else {
        NavigationManager.NavigateTo("/Onboarding/Signup");
    }
  }
}
```

This page will display a message that invites the user to check their inbox and offers a button to resend the verification link if needed. It will be rendered as shown in the following image:

![Verify email screen in your Blazor Web app](https://images.ctfassets.net/23aumh6u8s0i/72gdEry0IJzomAqT4P95gF/a099d96c8531367d3c8b567ac3853081/blazor-verify-email-screen.png)

Since the current onboarding flow shows the Organization creation page after the user signup, you need to change it. Open the `Program.cs` file in the `MyBlazorSaaS` folder and replace the line of code shown below:

```csharp
// MyBlazorSaaS/Program.cs

//...existing code...

app.MapGet("/account/signup", async (HttpContext httpContext, string login_hint) =>
{
  var authenticationProperties = new LoginAuthenticationPropertiesBuilder()
          //.WithRedirectUri("/onboarding/createOrganization") // 👈 old code
          .WithRedirectUri("/onboarding/verify")  // 👈 new code
          .WithParameter("screen_hint", "signup")
          .WithParameter("login_hint", login_hint)
          .Build();

  await httpContext.ChallengeAsync("OnboardingScheme", authenticationProperties);
});

//...existing code...
```

This ensures that the user will be redirected to the verification waiting page instead of the Organization creation page.

### Resend the verification link

The verification waiting page shows a "Resend Verification" button. Let's take a closer look at the code triggered by that button to learn how to resend the verification link:

```csharp

  
//...existing code...

@code {
  [CascadingParameter]
  private Task<AuthenticationState>? authenticationState { get; set; }
  private string Message = "";

  private async Task ResendVerificationEmail()
  {
    if (authenticationState is not null)
    {
      var state = await authenticationState;
      var userId = state?.User?.FindFirst(c => c.Type == ClaimTypes.NameIdentifier)?.Value;

      try {
        var managementClient = await auth0Management.getClient();
        await managementClient.Jobs.SendVerificationEmailAsync(new VerifyEmailJobRequest() { UserId = userId });
        Message = "The verification e-mail has successfully been sent. Please check your inbox";
      } catch (Exception) {
        Message = "Failed to resend verification e-mail.";
      }      
    } else {
        NavigationManager.NavigateTo("/Onboarding/Signup");
    }
  }
}
```

The `ResendVerificationEmail()` method gets the user ID from the authentication state, gets an instance of the management client, and uses the `SendVerificationEmailAsync()` method, passing an instance of `VerifyEmailJobRequest` with the user ID value. This method of the Management API client corresponds to calling [the email address verification endpoint](https://auth0.com/docs/api/management/v2/jobs/post-verification-email), which will generate a new ticket, include it in a verification link, and send it to the user via email.

## Customize the Email Verification Template

The default email message with the verification link sent to the user will look like the following:

![Email verification message](https://images.ctfassets.net/23aumh6u8s0i/6cP7skL9tqxBUnCAwC1cOa/0e31a5311fbd6506e75e010c091218a9/email-verification-message.png)

You can customize this message using your Auth0 dashboard. Go to the [Branding > Email Templates](https://manage.auth0.com/#/templates) page, select the *Verification Email (Link)* template, and apply the changes you want. You can customize the sender address, the subject, and the message body using [HTML and Liquid syntax](https://auth0.com/docs/customize/email/email-templates/use-liquid-syntax-in-email-templates). You can also customize other settings and use [common variables](https://auth0.com/docs/customize/email/email-templates#common-variables) to include some contextual values in your message. Read [this document](https://auth0.com/docs/customize/email/email-templates) to learn more about email template customization.

By default, nothing visible happens on your application when a user clicks the verification link. Auth0 will mark the user's email field as verified and show a page confirming that the email verification process was successful, as you can see in the following image:

![£mail address verified by Auth0](https://images.ctfassets.net/23aumh6u8s0i/4pgKFqZDlk93OnekyTrElS/1b3bf679d107f68279e8c4f711267836/email-address-verified.png)

However, in our self-subscription flow, we would like the user to be redirected to the next onboarding step after their email is verified, which is the organization creation screen. The email verification template provides a *Redirect To* field that allows you to specify the URL of the page you want the user to land after the email verification. You can parametrize the URL using one of the common variables mentioned above. Specifically, enter the following value in the *Redirect To* field and click the *Save* button:

```
{{ application.callback_domain }}/onboarding/createOrganization
```

That's all! Now, your user will be redirected to the Organization creation page after the email verification.

<include src="Auth0TemplatesForDotnetCTA" />

## Require Email Verification

One small piece is missing to complete the customer onboarding flow. You need to ensure that they cannot access the protected pages of your application if their email has not been verified yet. This means that when you check if the user is authenticated, you also need to consider checking that their email is verified too.

### A basic approach

You don't need to check if the user's email is verified when they access the `Home.razor` page, `Signup.razor`, and `Verify.razor` pages: the first two are public pages, and the third one is specifically designed for users who haven't verified their email yet.

You need to check the validity of the user's email on the `CreateOrganization.razor` page. To this purpose, apply the changes highlighted here on the `CreateOrganization.razor` page:

```csharp


//...existing code...

  protected override async Task OnInitializedAsync()
  {
    if (authenticationState is not null)
    {
      var state = await authenticationState;

      // 👇 new code
      var isEmailVerified = state.User?.FindFirst(c => c.Type == "email_verified")?.Value?.ToLowerInvariant() == "true";
      // ☝️ new code

      // 👇 changed code
      if (state.User?.Identity?.IsAuthenticated??false && isEmailVerified)
      // ☝️ changed code
      {
        Email = state.User?.FindFirst(c => c.Type == ClaimTypes.Email)?.Value??String.Empty;
        UserId = state.User?.FindFirst(c => c.Type == ClaimTypes.NameIdentifier)?.Value??String.Empty;
      } else {
        NavigationManager.NavigateTo("/Onboarding/Signup");
      }
    }
  }

//...existing code...
```

You can see that a new variable `isEmailVerified` has been introduced. This variable gets a boolean value coming from the value of the `email_verified` claim. You will use this variable as an additional condition to go ahead with the Organization creation step.

### A more structured approach

You need to apply the email verification check to most of the protected pages of your application. This depends on your application, of course. In our case, you should also apply the same check to the `Weather.razor` page on the server side and the `Counter.razor` and `FetchDat.razor` pages on the client side.

Applying the earlier approach would work, but it's ineffective in terms of code duplication and maintenance. You will use [ASP.NET Core policy-based authorization](https://learn.microsoft.com/en-us/aspnet/core/security/authorization/policies) instead.

First, open the `Program.cs` file in the `MyBlazorSaaS` folder and add the code highlighted below:

```csharp
// MyBlazorSaaS/Program.cs

//... existing code...

// 👇 new code
builder.Services
    .AddAuthorization(options => {
      options.AddPolicy("VerifiedEmail", policy =>
        policy.RequireAssertion(context =>
          context.User.HasClaim(claim =>
            ( claim.Type == "email_verified" &&
              claim.Value?.ToLowerInvariant() == "true")
          )
        )
      );
    });
// ☝️ new code

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents()
    .AddInteractiveWebAssemblyComponents()
    .AddAuthenticationStateSerialization();

//... existing code...
```

This code defines an authorization policy named `"VerifiedEmail"`. This policy checks if the current user has a claim `email_verified` set to `true`. This is the [standard claim](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) coming from the ID token issued by Auth0.

Now, let's create a page to which the user will be redirected when attempting to access a page without the required authorization. By default, Blazor redirects unauthorized users to an `Account/AccessDenied` page. So, create an `Account` folder in the `MyBlazorSaaS/Components/Pages` folder and add an `AccessDenied.razor` page with the following code:

```csharp

  
@page "/account/accessdenied"

<PageTitle>Access Denied</PageTitle>

<h2>You are not authorized to access this page</h2>

<p>@Reason</p>

@code {
  [CascadingParameter]
  private Task<AuthenticationState>? authenticationState { get; set; }
  private string Reason = "";

  protected override async Task OnInitializedAsync()
  {
    if (authenticationState is not null)
    {
      var state = await authenticationState;

      var isEmailVerified = state.User?.FindFirst(c => c.Type == "email_verified")?.Value?.ToLowerInvariant() == "true";

      if (state.User?.Identity?.IsAuthenticated??false && isEmailVerified)
      {
        Reason = "Your email is not verified yet!";
      }
    }
  }
}
```

This page shows a generic message to the unauthorized user and attempts to show a specific message about the actual reason. In particular, it checks if the user has the `email_verified` claim set to `true` and displays a message accordingly.

Finally, specify the policy `VerifiedEmail` in the `Authorize` attribute of your protected pages as shown below:

```csharp

  
@page "/weather"
// 👇 changed code
@attribute [Authorize(Policy = "VerifiedEmail")]
// ☝️ changed code
@attribute [StreamRendering]

//...existing code...
```

Apply this change to the `Counter.razor` and `FetchData.razor` pages in the `MyBlazorSaaS.Client/Pages` folder as well.

That's all! Your customer onboarding flow now includes the email verification step to mitigate the risks of spam and fraud.

<include src="SignupCTA" text="Try out Auth0 authentication for free." linkText="Get started →" />

## Recap

Auth0 always sends an email verification message when a user signs up for your application. However, it's up to you to determine in which scenario to check whether the user's email has been verified.

In the example shown in this article, we took the case of onboarding a customer of a B2B SaaS application developed with Blazor and added the email verification step before allowing them to create a new Organization.

We also saw how to allow the resend of the verification email and prevent access to the application's protected pages when the user's email has not been verified yet.

You can find the final code of the project created during the article on [this GitHub repository](https://github.com/andychiare/MyBlazorSaaS/tree/email-verification).

Enforce Customer Email Verification in Your B2B Blazor Web App

Let's explore the scenarios where ASP.NET Core Identity shows its limitations and what the alternatives are.

When it comes to handling identity and access management in the .NET platform, ASP.NET Core Identity is a fantastic starting point. It provides a full-featured, out-of-the-box solution for managing users, roles, and authentication in ASP.NET Core applications that is simple to set up and use. However, as applications grow in complexity and authentication and authorization requirements become more challenging, ASP.NET Core Identity may start showing its limitations.  
This article explores the limitations of ASP.NET Core Identity, the technical reasons behind these challenges, and discusses alternative solutions.

## Why ASP.NET Core Identity?

Before diving into its limitations, let’s first understand why ASP.NET Core Identity is so popular. ASP.NET Core Identity is a membership system that provides common features like user registration, login, role management, and claims-based authentication. It is tightly integrated with the ASP.NET Core ecosystem and supports both [cookie-based and token-based authentication](https://auth0.com/blog/cookies-tokens-jwt-the-aspnet-core-identity-dilemma/) (starting with .NET 8). It offers several key features out of the box:

* **User Registration and Login**. ASP.NET Core Identity simplifies user registration and login processes, including options for password recovery, email confirmation, and Multi-Factor Authentication (MFA).  
* **Role-based Authorization**. The system allows for granular control over user roles and permissions, which is essential for access control.  
* **External Authentication**. ASP.NET Core Identity supports various external authentication providers, such as Google, Facebook, and Microsoft, allowing users to sign in using their existing credentials from these platforms.  
* **Customizability**. Developers can customize the system to fit their needs, adding additional fields to the user model, integrating with other services, and defining custom password policies.

While ASP.NET Core Identity is highly effective for small to medium-sized applications with basic authentication needs, its limitations become apparent in more advanced scenarios.

## Limitations of ASP.NET Core Identity

What are the limitations you may encounter when your application needs to grow in the context of ​​security and user management? Let's explore some of the main scenarios.

### Support for Standard Authentication Protocols

One of the primary limitations of ASP.NET Core Identity is its lack of support for advanced authentication protocols, such as OAuth 2.0, OpenID Connect (OIDC), and SAML. These protocols are crucial for implementing [Single Sign-On (SSO)](https://auth0.com/docs/authenticate/single-sign-on) across multiple applications and integrating with third-party Identity providers.  
While it can integrate with an external authentication service, this requires external libraries or a separate service to handle the authentication and authorization, adding complexity to the application.

### Single Sign-On and Federation

SSO is an essential feature for many organizations. It allows users to log in once and access multiple systems without needing to authenticate again. This is particularly important for enterprises with multiple applications that rely on centralized authentication.  
ASP.NET Core Identity is designed primarily for a single application context. While it’s possible to set up SSO in ASP.NET Core Identity by manually configuring external authentication providers (like Google, Microsoft, Facebook, or other enterprise systems), doing so is cumbersome and doesn’t scale well.  
Setting up SSO with complex protocols like SAML 2.0 or OpenID Connect can be challenging. You often need to rely on third-party libraries and write a lot of boilerplate code, which can be time-consuming and error-prone.  
In addition, if your application totally relies on an external Identity provider, the ASP.NET Core infrastructure, including the user database, becomes useless.

### Token Management

While .NET 8 introduced token-based authentication endpoints for Single-Page Applications (SPAs), these endpoints are limited in functionality compared to full-fledged OIDC or OAuth 2.0 implementations. For instance:

* By default, the tokens generated by ASP.NET Core Identity are not configured as JSON Web Tokens (JWTs).  
* Advanced OAuth flows like [client credentials](https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-credentials-flow) or [device authorization](https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow) are not natively supported.  
* Handling token refresh, revocation, or issuing custom tokens for various clients can be cumbersome with ASP.NET Core Identity.

### Microservices and Distributed Architectures

In modern application architectures, microservices are becoming increasingly popular. A key challenge in microservices is managing authentication and authorization across multiple services, each potentially using a different technology stack.  
ASP.NET Core Identity isn’t designed with microservices in mind. While it can work in monolithic applications, when dealing with a microservices architecture, you often need a solution that can provide centralized authentication and authorization, preferably using token-based authentication.  
In a microservices-based system, you might need to authenticate users once (e.g., OpenID Connect) and propagate tokens across multiple services (e.g., using OAuth 2.0). ASP.NET Core Identity is not ideal for this setup as it’s typically used for stateful session management, which is not optimal for distributed systems.

### Scalability and Performance

For high-traffic applications with millions of users, the default ASP.NET Core Identity database schema might become a bottleneck. While adequate for smaller applications, it isn't optimized for high-volume scenarios. Customizing the schema or implementing caching strategies is necessary but requires a deep understanding of the underlying database.

### Multitenancy

ASP.NET Core Identity is inherently designed for single-tenant applications, i.e., an application that manages a single set of users, typically belonging to one organization. A multi-tenant application is one in which a single instance serves multiple organizations or customers, each with its own set of users. This is a common scenario in SaaS (Software-as-a-Service) applications, where each customer (tenant) has different users, roles, and permissions.  
ASP.NET Core Identity does not provide built-in support for multi-tenant architectures. While it is possible to configure the system to work in a multi-tenant environment by creating separate user stores for each tenant, this approach can be cumbersome to manage and doesn’t scale well.

### Advanced Security Features

Implementing advanced security features like MFA with complex policies, FIDO2 credentials and passkeys, adaptive authentication, or risk-based authentication requires significant custom development. While ASP.NET Core Identity supports basic MFA, it lacks the flexibility to implement dynamic policies based on user behavior or risk profiles.  
Also, exposing protected APIs to third-party applications with ASP.NET Core Identity is possible, but it requires careful implementation of JWT-based authentication and authorization. Managing token issuance, validation, and revocation becomes critical, and inconsistencies can lead to security vulnerabilities. This is definitely a task for OAuth 2.0 and OIDC-compliant identity providers.

### Advanced Customization Requirements 

ASP.NET Core Identity's default implementation often requires significant customization to meet unique business requirements:

* Customizing the Identity API endpoints is challenging. For example, you cannot easily modify the data required for user registration or add unsupported authentication methods like WebAuthn.  
* The default UI for identity management forces you to use server-rendered pages unless you override them entirely.  
* Managing hierarchical roles or permissions is not natively supported.  
* Implementing fine-grained authorization for specific resources requires significant additional work.

### Security Concerns

Security is a major consideration when building any authentication system. While ASP.NET Core Identity provides some basic security features, the default configuration of ASP.NET Core Identity may expose vulnerabilities:

* Endpoints like `/register` are not natively protected, allowing [unauthorized access if not explicitly secured](https://auth0.com/blog/cookies-tokens-jwt-the-aspnet-core-identity-dilemma/#Some-Caveats-About-Identity-API-Endpoints).

* Without careful configuration, token expiration and refresh mechanisms [can introduce security risks](https://www.telerik.com/blogs/new-net-8-aspnet-core-identity-how-implement).

Also, it does not cover all the advanced security needs that modern applications require. Features like brute-force protection, IP whitelisting, user account lockouts, and MFA are important for securing an application’s authentication system. While ASP.NET Core Identity does provide some of these features (like MFA and account lockouts), more sophisticated threat protection features are often needed in high-risk environments.

## Self-Hosted Alternative Solutions

When you encounter one or more of the limitations discussed in the previous section, it is time to look for alternative solutions. A first option could be to replace ASP.NET Core Identity with a self-hosted standards-based Identity and access management solution.

Among the most popular self-hosted solutions in the .NET ecosystem, we can mention [Identity Server](https://duendesoftware.com/products/identityserver) and [Keycloak](https://www.keycloak.org/). Both offer more advanced identity and access management capabilities than ASP.NET Core Identity. Specifically:

* They **support standard protocols**, such as OpenID Connect and OAuth 2.0. Both products are OIDC-certified, which means they passed the tests that ensure compliance with the OIDC specifications. In terms of SAML support, while Keycloak supports it natively, Identity Server supports SAML via [a specific component](https://www.identityserver.com/articles/saml-20-integration-with-duende-identityserver).  
* They offer a **centralized authentication** solution enabling SSO and Federated Identity.  
* Support for **mutitenancy** depends on the specific product you are going to use. While Keycloak has native support for mutitenancy through [*realms*](https://www.keycloak.org/docs/latest/server_admin/index.html#_configuring-realms), supporting robust mutitenancy with Identity Server requires careful planning and implementation.  
* Support for **advanced authentication mechanisms** like passkeys is natively available in recent versions of Keycloak while it requires specific integration of third-party libraries in Identity Server.

Using a self-hosted solution like Identity Server or Keycloak certainly overcomes some of ASP.NET Core Identity's major limitations, especially regarding SSO and standards compliance. In terms of other features, much depends on the specific product and your needs in protecting your users' identities.

## Cloud-Based Solutions

Using a self-hosted solution, you still have to deal with issues that can become problematic as your application and its needs grow.

Leaving aside the features that your specific scenario requires, you still have to deal with your application's performance, high availability, and security. In other words, maintaining the efficiency and security of the Identity management solution is entirely up to you. You will have to follow the evolutions of the chosen self-hosted solution and apply updates promptly after verifying them. You will have to deal with scaling the authentication system as the number of users and concurrent requests grows. You will have to learn to do a job that is probably not yours.

Cloud-based solutions such as [Auth0](https://auth0.com/) offer you significant benefits in this regard.  
In addition to [features](https://auth0.com/features) that certainly go beyond those offered by self-hosted solutions and advanced customization possibilities, a cloud solution like Auth0 allows you to delegate the task of taking care of the security and maintenance of the Identity management of your application. No need to keep the system updated and take care of configuring the entire infrastructure to keep the identity of your users safe. In addition, you can take advantage of advanced security tools such as Anomaly Protection, Brute Force Protection, Bot Detection, and other features to armor your application's authentication system.

<include src="SignupCTA" text="Try out Auth0 authentication for free." linkText="Get started →" />

## Wrapping Up

Choosing the right IAM solution depends on your specific needs and priorities. If you're building a simple application and need basic user management, ASP.NET Core Identity might be sufficient. For complex scenarios requiring SSO, federation, or advanced security features, IdentityServer or Keycloak are excellent self-hosted alternatives. If you prefer to offload the complexities of IAM and prioritize scalability and ease of use, a managed solution like Auth0 is a great option.

Here is a table that summarizes the main features supported by ASP.NET Core Identity compared with Identity Server, Keycloak, and Auth0 for your quick reference:

![Comparison table between ASP.MET Core Identity, Identity Servre, Keycloak, and Auth0](https://images.ctfassets.net/23aumh6u8s0i/4LpbsTxQhzyj2LXjULjWBz/29e1ddd3c5f245901ea9d951a98ea2a5/aspnet-core-identity-keycloak-auth0-comparison-table.png)

Remember to carefully evaluate your requirements and consider the tradeoffs between cost, complexity, and control before making a decision.  


When ASP.NET Core Identity Is No Longer Enough

Learn how to overcome ASP.NET Core authentication configuration issues when your application is behind a proxy, load balancer, gateway, container, or similar system.

When your ASP.NET Core application runs behind a proxy, a load balancer, or even within a container, its authentication flow may break. Let's try to understand why and what solutions we can adopt.

## The Broken Behavior

You have built your awesome ASP.NET Core application and have integrated it with authentication. Everything works like a charm in your local development environment. It's time to deploy it on your stage environment (or do you prefer to go directly into production? 😏).

Let's assume you don't serve your web application directly through a web server. You may need a slightly more complex infrastructure for several reasons:

- Load balancing, caching, compression, and other performance features.
- Request and response processing.
- Request filtering and other security features.
- Portability, process isolation, and other containerization features.

Whatever your reason is, there are chances that your application will run within a container or behind a reverse proxy, a load balancer, an application gateway, etc. Regardless of the specific function, we can call this intermediary between a client and your application a [proxy](https://en.wikipedia.org/wiki/Proxy_server). The following diagram describes this generic scenario:

![Generic proxy scenario](https://images.ctfassets.net/23aumh6u8s0i/4VCtaFCTenYuMYklZY5NRb/3c3e4eda73f1ef68e93592586f477767/generic-proxy-scenario.png)

In this scenario, your awesome application that was perfectly working in your local development environment may stop working.

The specific error depends on your particular environment and configuration, but typically, the type of error falls into one of the following categories:

- The callback URL uses HTTP instead of HTTPS.
- The callback URL uses an internal domain name instead of the public domain name.
- An unexpected error occurs.

Let's take a look at each of these categories in the following subsections considering a scenario with Auth0 as the Identity provider.

### The callback URL uses HTTP instead of HTTPS

Assume that your application is reachable at the address `https://my-awesome-app.com` and everything is correctly configured on the Auth0 side. When you try to authenticate, you get an error similar to the following:

```shell
Callback URL mismatch.
http://my-awesome-app.com/callback is not in the list of allowed callback URLs.
```

Actually, you have registered the callback URL on the Auth0 side, but your registered its scheme as `https` while the error message reports `http`. Why is your actual callback URL using `http`?

Usually, this type of problem occurs when your application runs within a container service such as [Azure Container Apps](https://learn.microsoft.com/en-us/azure/container-apps/overview), [AWS Elastic Container Service](https://aws.amazon.com/ecs/), or other similar services.

### The callback URL does not use the public domain name

Another possible scenario is when you get an error like the following:

```shell
Callback URL mismatch.
https://localhost/callback is not in the list of allowed callback URLs.
```

You correctly defined the callback URL with your domain &mdash; `my-awesome-app.com` &mdash; on the Auth0 dashboard, but your application builds the callback URL using `localhost`. In some scenarios, the domain of the callback URL can be an internal domain, such as the subdomain name assigned to your application instance by Azure or AWS (e.g., `internal-name.azure.com` or `internal-name.amazonws.com`).

Usually, this issue occurs when an application runs behind services like [Azure Gateway](https://azure.microsoft.com/en-us/products/application-gateway/), [Azure Front Door](https://azure.microsoft.com/en-us/products/frontdoor/), [AWS Elastic Load Balancing](https://aws.amazon.com/elasticloadbalancing/), [AWS CloudFront](https://aws.amazon.com/cloudfront/), etc. but also behind reverse proxies like [nginx](https://nginx.org/) or [Caddy](https://caddyserver.com/).

### An unexpected error occurs

Other different errors may occur depending on your specific infrastructure. For example, you may experience error messages like the following:

```shell
An unhandled exception occurred while processing the request. Exception: Correlation failed.
```

This does not directly say what the reason for the problem is, but it may depend on the same scenario we are going to illustrate in a moment.

### A few considerations

Let's consider a few things before analyzing the issue that may cause this type of error and how to solve it.

We mentioned Blazor as the framework used for building your awesome application, but consider it just an example. Any ASP.NET Core-based framework is subject to the problem we described: ASP.NET Core MVC, Blazor, and Razor Pages.

Also, we are using Auth0 as an example of an OpenID Connect Identity provider, but this is NOT a problem on the Auth0 side or the side of other identity providers. It's not even an OpenID Connect problem. As you will learn, it's a problem of ASP.NET Core. Specifically it's a problem with the [OpenID Connect middleware](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.authentication.openidconnect).

> More in general, the problem may affect any web application regardless of its development stack, but we are focusing on ASP.NET Core because of its specific behavior and solution.

## Why Does My Application Not Work?

To understand why these problems occur, you need to know how the ASP.NET Core OpenID Connect middleware works internally &mdash; at least at a high level &mdash; and how the HTTP traffic flows in an infrastructure where proxies are included.

### How OpenID Connect middleware works

To implement user authentication using OpenID Connect, you should implement the details of the [protocol](https://openid.net/specs/openid-connect-core-1_0.html). This would be a daunting task, but fortunately, ASP.NET Core provides specific middleware that alleviates some of this burden.

> The [Auth0 SDK for ASP.NET Core](https://github.com/auth0/auth0-aspnetcore-authentication) makes things even easier, but it also relies on the OpenID Connect middleware, so you cannot avoid the problems we are dealing with here.

Without going into the details of the protocol, one of the tasks of the middleware is to build the URL of the application to which the user's browser will be redirected after authentication. Through this URL, the application receives the authorization code that enables it to get the ID and access tokens. This URL is the so-called **redirect URI** or **callback URL**.

The middleware automatically builds this URL based on internal parameters and uses some properties of the HTTP request to build the base URL.

For example, suppose the middleware handles an HTTP request to `https://example.com/login`. The callback URL will be built as `https://example.com/signin-oidc`.

> If you are using the [Auth0 SDK for ASP.NET Core](https://github.com/auth0/auth0-aspnetcore-authentication), the default callback URL will be `https://example.com/callback`.

As you can see, the base path of the callback URL is the same as the request URL.

### HTTP requests and proxies

Consider the diagram shown above:

![Generic proxy scenario](https://images.ctfassets.net/23aumh6u8s0i/4VCtaFCTenYuMYklZY5NRb/3c3e4eda73f1ef68e93592586f477767/generic-proxy-scenario.png)

As said, the proxy between the client and your application can have several tasks. Reverse proxying is one of these tasks. Basically, a [reverse proxy](https://en.wikipedia.org/wiki/Reverse_proxy) accepts requests from a client and forwards them to one or more applications.

In some scenarios, the reverse proxy is also used as [TLS termination proxy](https://en.wikipedia.org/wiki/TLS_termination_proxy): it encrypts and decrypts communications outside your hosting infrastructure via TLS tunnels. In other words, a reverse proxy accepts secure HTTPS requests but uses plain HTTP to forward the request internally, as highlighted in the following diagram:

![TLS reverse proxy scenario](https://images.ctfassets.net/23aumh6u8s0i/7zUeXNHMR82jeAdX6DyKwC/4443d5a0f9289a16a460b64d2ac85fa7/tls-reverse-proxy-scenario.png)

In this case, your application will receive a request to `http://example.com` and then the middleware will build  `http://example.com/signin-oidc` as the callback URL. This will differ from the allowed callback URL you registered with Auth0, and this is why you will get the first case of error: your callback URL has the HTTP scheme instead of HTTPS.

> We mentioned earlier that the HTTP vs. HTTPS issue often affects applications running within a container service. The reason is that these services use a proxy to route the traffic, and this proxy provides [TLS termination](https://en.wikipedia.org/wiki/TLS_termination_proxy).

In the example above, we supposed that the internal domain name of your application instance is the same as the public one: `example.com`. This rarely happens. Usually, your internal application instance is reachable through an IP address or an internal name, such as `my-app-instance.example.com`, as shown below:

![Reverse proxy internal name scenario](https://images.ctfassets.net/23aumh6u8s0i/1SIzuxF8qhmNPPSZrkBrS4/92126bb3cb0215effb4bfa69b493a474/reverse-proxy-internal-name-scenario.png)

In this case, your application will receive a request to `https://my-app-instance.example.com` and the middleware will build a callback URL as `https://my-app-instance.example.com/signin-oidc`. Again, this URL differs from the allowed callback URL you registered with Auth0. By the way, depending on the configuration of your hosting environment, the internal URL of your application may not be publicly reachable.

Different error messages may arise in other scenarios or configurations, but often the problems are related to this difference between the public address and the internal address of your application.

<include src="Auth0TemplatesForDotnetCTA" />

## How to Fix the Broken Behavior

Once you understand why these errors occur, it's time to learn how to fix these issues.

As you learned in the previous section, when your ASP.NET Core application runs behind a reverse proxy, load balancer, or similar network component, it may lose access to some information coming with the original HTTP request. You need a way to access this information and provide it to the OpenID Connect middleware to build a correct callback URL.

### Meet the `X-Forwarded-*` headers

Most reverse proxies forward the original HTTP request data through specific HTTP headers. The most common are:

- `X-Forwarded-For`. This header contains the IP address of the original client.
- `X-Forwarded-Host`. This one has the original value of the `Host` header included in the original client's request.
- `X-Forwarded-Proto`. In this header, you can find the protocol used for the original request &mdash; HTTP or HTTPS.

Thanks to these headers, you can access the relevant values of the original HTTP request and build your callback URL correctly.

Despite what is commonly thought, `X-Forwarded-*` headers do not derive from an official standard but are so widely used that they can be considered a de facto standard. Actually a [standard](https://datatracker.ietf.org/doc/html/rfc7239) exists and it's based on a single header: [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded). However, the `X-Forwarded-*` headers are still more popular.

> Make sure your proxy is correctly configured in order to trust the values forwarded via `X-Forwarded-*` headers. In fact, the client's request may go through a chain of proxies on the Internet, and if your proxy simply forwards the  `X-Forwarded-*` headers it receives, you may be exposed to security risks.  Well-configured proxies don’t accept forwarded headers. Instead, they populate these headers with reliable values like the TCP connection and original HTTP headers such as `Host`.
> Read [this article](https://blog.ircmaxell.com/2012/11/anatomy-of-attack-how-i-hacked.html) for an example of security issues to which a misconfigured proxy can lead.

### Using Forwarded Headers middleware

Fortunately, you don't need to directly access HTTP requests to extract the values of `X-Forwarded-*` headers. ASP.NET Core provides you with middleware that simplifies your life: the *Forwarded Headers middleware* implemented by the [ForwardedHeadersMiddleware](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.httpoverrides.forwardedheadersmiddleware) class.

Basically, this middleware extracts the original values of the client request forwarded by the proxy and makes them available to you as first-hand values of the `Request` object. This saves you from writing specific code for your application when it runs behind a proxy.

To enable the Forwarded Headers middleware, include it in the request pipeline of your application by adding the line highlighted below to your `Program.cs` file:

```csharp
// Program.cs

//...existing code

var app = builder.Build();

//👇 new code
app.UseForwardedHeaders(new ForwardedHeadersOptions
{
  ForwardedHeaders = ForwardedHeaders.XForwardedProto |
                     ForwardedHeaders.XForwardedHost;
});
//👆 new code

app.UseAuthentication();

//...existing code
```

> Make sure you call the `UseForwardedHeaders()` method before other middleware. The middleware order is important, and adding it as the first middleware in the request pipeline ensures that the values of the original request are propagated consistently.

In the example above, you enabled the mapping of the `X-Forwarded-Proto` and `X-Forwarded-Host` headers, which are needed to make the OpenID Connect middleware build the callback URL correctly. In addition, any statement that accesses `HttpContext.Request.Scheme` and `HttpContext.Request.Host` will get the value coming from the original request.

Optionally, you can also configure the Forwarded Headers middleware to only accept `X-Forwarded-*` headers coming from a trusted proxy, as shown in the following code snippet:

```csharp
// Program.cs

//...existing code

var app = builder.Build();

app.UseForwardedHeaders(new ForwardedHeadersOptions
{
  ForwardedHeaders = ForwardedHeaders.XForwardedProto |
                     ForwardedHeaders.XForwardedHost;
  KnownProxies.Add(IPAddress.Parse("10.0.0.42"); //👈 new code
});

//...existing code
```

You can also add multiple trusted proxies and configure the middleware to accept custom header names. See the [documentation](https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/proxy-load-balancer) for more details.

> Not all proxies or other network appliances add the `X-Forwarded-*` headers by default. They may need additional configuration. Consult their documentation to learn how to configure it.

<include src="SignupCTA" text="Try out Auth0 authentication for free." linkText="Get started →" />

### No code alternative?

If you don't want to or cannot change the code of your ASP.NET Core application, an alternative exists. You can set the environment variable `ASPNETCORE_FORWARDEDHEADERS_ENABLED` to `true`, and the Forwarded Headers middleware is automatically added to the request pipeline and configured.

While this approach is very convenient, unfortunately [it only maps](https://github.com/dotnet/aspnetcore/blob/v8.0.10/src/DefaultBuilder/src/ForwardedHeadersOptionsSetup.cs) the `X-Forwarded-For` and `X-Forwarded-Proto` headers. This means that it could not be sufficient if your scenario also requires using the original host name, as in the authentication case we are discussing here. Also, consider that this approach does not allow you to define your trusted proxies and handle customized headers.

## Conclusion

Now you know the type of errors you can run into when you publish your application on an infrastructure a little more complex than a simple web server.

We have explored a number of cases where OpenID Connect-based authentication no longer works due to the loss of original HTTP request information. However, we have seen how to fix the problem simply by using the Forwarded Headers middleware.

Before concluding, we want to highlight that this type of problem is related to more than just authentication. It involves any functionality that requires dynamic URL generation, as well as client geolocation and other processing based on the client's original request. For more information on the different scenarios, see [this document](https://learn.microsoft.com/en-us/azure/architecture/best-practices/host-name-preservation).


ASP.NET Core Authentication Behind Proxies

A new release of the package Auth0 Templates for .NET is out with new project templates and other improvements.

A new awesome version of the [Auth0 Templates for .NET package](https://www.nuget.org/packages/Auth0.Templates/) has been released! It brings you new templates and other improvements, which we will discover in a moment. Install now the latest release of the templates by running the following command in a terminal window:

```bash
dotnet new install Auth0.Templates
```

> ⚠️ Make sure you have uninstalled any previous version of the package from your machine before installing the new one.

Ready to learn what's new in the latest release? Let's go!

## New Project Templates

The first big news is that two new templates are now available: the Blazor Web App and the MAUI templates.

### The Blazor Web App template

The Blazor Web App template allows you to create a web application using the .NET 8 Blazor application model. As you may know, this new type of Blazor application has some complexities in properly supporting authentication. Take a look at [this article](https://auth0.com/blog/auth0-authentication-blazor-web-apps/) to learn more about it. Now you can have a starting point for your new Blazor application with Auth0 embedded in a snap by simply running the following command:

```bash
dotnet new auth0blazor -o MyNewBlazorApp
```

As usual, if you also have the [Auth0 CLI](https://github.com/auth0/auth0-cli) installed on your machine and logged in, you can automatically register your app with Auth0. Of course, you can still use the templates with Visual Studio:

![Auth0 Blazor Web App template in Visual Studio](https://images.ctfassets.net/23aumh6u8s0i/1fmXTCgaPVzvKGGiW0QPon/edd5f2a979472be788c9c6d448dc1ed0/auth0-blazor-web-app-vs.png)

Read [more about the Blazor Web App template here](https://github.com/auth0/auth0-dotnet-templates/blob/main/docs/auth0blazor.md).

### The MAUI template

With the MAUI template, you can build desktop and mobile applications with Auth0 authentication for Windows, macOS, iOS, and Android using a single code base. In this case, the command to use is as follows:

```bash
dotnet new auth0maui -o MyNewMauiApp
```

Building your new MAUI app using this template will save you a lot of time, as you can see from reading [this article](https://auth0.com/blog/add-authentication-to-dotnet-maui-apps-with-auth0/).

Check out [this document to learn more about the MAUI template](https://github.com/auth0/auth0-dotnet-templates/blob/main/docs/auth0maui.md).

## Other Improvements

In addition to the new templates, the new package brings you other internal and external improvements. To mention just a few of them:

- The Blazor WebAssembly template now supports .NET 8.
- The program that registers your application with Auth0 is no longer tied to .NET 7.0.
- A few issues with the auto-registration script have been fixed.

These improvements help provide a better experience when scaffolding and registering your application with Auth0.

<include src="ebook-ads/dotnetIdentity" />

## JetBrains Rider Support

Now you can use the Auth0 Templates with JetBrains Rider! Starting with [version 2024.1](https://www.jetbrains.com/rider/whatsnew/), Rider fully supports custom templates, so now you can choose your preferred IDE to build your .NET applications with Auth0 integrated, regardless of your operating system. This is especially important now that [Visual Studio for Mac is close to its retirement](https://learn.microsoft.com/en-us/visualstudio/mac/what-happened-to-vs-for-mac?view=vsmac-2022).

Previously, Rider [didn't support parameters for custom templates](https://youtrack.jetbrains.com/issue/RIDER-16759), which was a clear barrier to using the Auth0 Templates. Now you can use them just like in Visual Studio!

![Auth0 Blazor Web App Template in JetBrains Rider](https://images.ctfassets.net/23aumh6u8s0i/2wWfc13e4He4h6Ob3H7Eyu/d4fcd35aab3ae5a1ed41f6ec25fc486b/auth0-blazor-web-app-rider.png)

## A Look Back and a Glimpse Forward

The first version of the package was released one year ago. Since then, the project has grown with new templates and integration with the Auth0 CLI for automatic registration of your applications. During this year, the package has been downloaded over 8,000 times, and we have received suggestions and contributions.

We want to continue improving the current templates by adding features and improving the developer experience. Your feedback is very important. Share your thoughts by leaving a message below, or by opening a [new issue](https://github.com/auth0/auth0-dotnet-templates/issues/new/choose) to report problems and request new features.
If you like the project, don't forget [to star it on GitHub](https://github.com/auth0/auth0-dotnet-templates).

New Templates for Building .NET Apps with Auth0 Authentication

Calling a protected API from a .NET 8 Blazor Web App can be a bit tricky. Let's see what the problems are and how to solve them.

Call Protected APIs from a Blazor Web App

A new version of the Auth0 Templates for .NET package has been released: discover the new powerful features.

In May, we [announced the release of Auth0 Templates for .NET](https://auth0.com/blog/introducing-auth0-templates-for-dotnet/), a NuGet package that allows .NET developers to scaffold a new project with Auth0 embedded. Today, we are announcing the release of a new powerful version of the package: [Auth0 Templates for .NET 2.1](https://www.nuget.org/packages/Auth0.Templates). 🎉

Go to your terminal window and install the new package by running the following command:

```bash
dotnet new install Auth0.Templates
```

> ⚠️ If you already have a previous version of the package installed on your machine, please uninstall it using the following command before installing the new package:
>
> ```bash
> dotnet new uninstall Auth0.Templates
> ```
>
> 

Let's explore what's new and how you can now create **a working application with Auth0 authentication in less than a minute!**

## Auth0 CLI integration

The most prominent feature introduced in this new release is the integration with the [Auth0 CLI](https://github.com/auth0/auth0-cli), the command line tool that allows you to manage your Auth0 tenants and your application registration from your terminal window.

> 📖 If you are new to the Auth0 CLI, take a look at [the Auth0 CLI Basics Lab](https://developer.auth0.com/resources/labs/tools/auth0-cli-basics) to learn how to use it.

If you have the Auth0 CLI installed on your machine and are already logged in to your Auth0 tenant, you can have your new application automatically registered. Let's do an example to better explain.

### Self-Registration in .NET CLI

Suppose you want to create a Blazor Server application with Auth0 authentication embedded. You can start by running the following command in a terminal window:

```bash
dotnet new auth0blazorserver -o MyBlazorServerApp
```

This command uses the `auth0blazorserver` template to create a Blazor Server application in the `MyBlazorServerApp` folder.

After launching the command, you will see a message similar to the following:

```bash
The template "Auth0 Blazor Server App" was created successfully.

Processing post-creation actions...

Template is configured to run the following action:
Actual command: register-with-auth0.cmd 
Do you want to run this action [Y(yes)|N(no)]?
```

With this message, the template engine asks if you want to register the newly created application with Auth0.

Once you confirm, the new Blazor application will be registered on your current Auth0 tenant. You will see the registration data onscreen for documentation purposes only, as you don't need to configure it manually. In fact, your new application will be automatically configured. All you need to do is run your Blazor application with `dotnet run`!

As you can see, using the integration with the Auth0 CLI allows you to have **an application up and running in less than a minute!**

Of course, you can still pass the configuration options on the command line in case you don't have the Auth0 CLI installed or if you have already registered the application with Auth0. See the [specific options for each template](https://github.com/auth0/auth0-dotnet-templates#usage) for more details.

### Auth0 registration in Visual Studio

If you are using the templates with Visual Studio, you can't leverage the self-registering feature. This is not a limitation of the template, but a restriction imposed by Visual Studio (see [this issue](https://github.com/dotnet/templating/issues/4575) for context).

However, you can run the registration action manually. So, assuming you want to create your Blazor Server application with Visual Studio, select the Auth0 Blazor Server App template as shown in the following picture:

![Auth0 Blazor Server template in Visual Studio](https://images.ctfassets.net/23aumh6u8s0i/4vIKOhrrozhmSDMkYPsEUr/5bd66766af25db726fb3aca5c4d731ab/auth0-blazorserver-app-vs.png)

Then, accept the default values proposed by the template configuration window and create the project.

After the project is created, go to the newly created application and run the following command:

```bash
./register-with-auth0.cmd
```

This command will automatically register your Blazor Server application with Auth0 and configure your application.

> Note: On MacOS you must enable the script to execute. Run the following command before launching the automatic registration:
>
> ```bash
> chmod +x register-with-auth0.cmd
> ```

## .NET 8 Support

The new release of Auth0 Templates for .NET supports .NET 8 by default for most templates. When you use the `dotnet new` command without specifying a framework version, you will get a .NET project with .NET 8 as the target framework. This is also the default .NET version when you are using Visual Studio, as shown below:

![Auth0 Template for ASP.NET Core MVC targeting .NET 8](https://images.ctfassets.net/23aumh6u8s0i/1mnYGKi2t006MED0sC2raQ/902bd9cb7b94be9e4b0d4c6c14b9d3ea/auth0-mvc-app-vs-options.png)

Blazor templates do not currently support .NET 8, but they still target .NET 7. The reason for this choice depends on the new .NET 8 Blazor model, which provides a more fluid approach between the Server and the WebAssembly hosting models. Currently, there are no official guidelines on how to integrate OpenID Connect with the new Blazor model. If you are interested in this topic, you can follow [this thread in the Auth0 Community forum](https://community.auth0.com/t/net-8-0-blazor/119691) to stay updated.

<include src="ebook-ads/dotnetIdentity" />

## Minimal API Template

The [Auth0 Templates for .NET package](https://www.nuget.org/packages/Auth0.Templates/) contains four templates since its first release:

- ASP.NET Core MVC
- ASP.NET Core Web API
- Blazor Server
- Blazor WebAssembly (ASP.NET Core hosted)

This new release adds a new template for [ASP.NET Core minimal API](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis). To use this template, add the `--minimal` option to the `dotnet new auth0webapi` command, as shown in the following example:

```bash
dotnet new auth0webapi -o MyWebAPI --minimal
```

This command creates a minimal API project in the `MyWebAPI` folder, and if you have the .NET CLI installed on your machine, it also registers it with Auth0.

In Visual Studio, you can simply select the *Use minimal API* checkbox as shown in the following picture:

![Options for the Auth0 ASP.NET Core Web API template in Visual Studio](https://images.ctfassets.net/23aumh6u8s0i/30Wl7yaOdnuWBhmdbRZa3v/259aa7ca9bb215da9fba8e62bfee8d87/auth0-webapi-app-vs-options.png)

## Looking Ahead

We hope that these new features will help .NET developers set up their new applications with Auth0 more easily than before. Our goal for the next release is to include a template for the missing Blazor model and add templates for other .NET application types.

Your feedback is valuable. If you experience a problem or have a request, please [open an issue](https://github.com/auth0/auth0-dotnet-templates/issues/new/choose) on the project's GitHub repository.

Remember that [Auth0 Templates for .NET](https://github.com/auth0/auth0-dotnet-templates) is an open source project, so your contribution is welcome! If you think you can help, check out [our contribution policy](https://github.com/auth0/auth0-dotnet-templates/tree/main#contributing) and get involved.



Auth0 Templates for .NET: A New Powerful Version Released

Should you use cookie-based or token-based authentication in ASP.NET Core Identity? Or should you use JWT and OpenID Connect?

.NET 8 has been released and many new exciting features are available to developers. In particular, this release brings [new options for authentication and authorization for ASP.NET Core Identity](https://auth0.com/blog/whats-new-dotnet8-authentication-authorization/). While these features have been long awaited, it seems that not everyone is happy with Microsoft's implementation choices, and there is some confusion among developers about the proper approach to use in their ASP.NET Core Identity-based applications. Let's try to shed some light on this not-so-simple topic.

## ASP.NET Core Identity: What’s New

One of the most criticized features of ASP.NET Core Identity until .NET 7 has been [its lack of *modern* authentication support for Single Page Applications](https://github.com/dotnet/aspnetcore/issues/42158). Whatever *modern* means, [ASP.NET Core Identity](https://learn.microsoft.com/en-us/aspnet/core/security/authentication/identity) has provided support for cookie-based authentication since version 3.1. It has also provided a set of web pages that allow users to register, authenticate, recover passwords, etc.

However, the current trend in authentication for SPAs seems to be token-based rather than cookie-based, and ASP.NET Core Identity didn't support it. The only option provided with the built-in SPA templates was based on Identity Server, a third-party [OpenID Connect](https://openid.net/developers/how-connect-works/) server. This approach has been [deemed excessive for small projects](https://github.com/dotnet/aspnetcore/issues/42158#issuecomment-1153222403) by several developers, and in any case introduces a third-party dependency that not everyone may want.

To address this issue, .NET 8 introduces support for token-based authentication and a set of [Identity API endpoints](https://learn.microsoft.com/en-us/aspnet/core/security/authentication/identity-api-authorization) that let developers do through the API what they could already do through the old-style web pages.

> To learn more about [the new authentication and authorization features introduced by .NET 8, read this article](https://auth0.com/blog/whats-new-dotnet8-authentication-authorization).

Awesome! So the problem is fixed and we all live happily ever after.🎉

In fact, things are not quite like that. Some developers are not entirely happy. There are those who expected a different implementation, and those who are now confused about the correct use of the new options. Let's try to bring some order to all this confusion.

> Disclaimer: This article is not a step-by-step tutorial on how to add ASP.NET Core Identity to your application. Its purpose is to discuss the authentication modes that it supports as of .NET 8.0.

## Cookie or Token-based Authentication?

Now ASP.NET Core Identity provides you with two authentication options: cookie-based and token-based. But what is the actual difference between the two approaches?

### Cookie-based authentication

Cookie-based authentication is the typical approach used by the traditional server-side rendered web page model. This is the model used by ASP.NET Core MVC and Razor Pages, to put it bluntly. In this type of authentication, a server-generated cookie proves successful user authentication and represents the user session.

> To learn more about [the relationship between cookies and sessions, read this article](https://dev.to/andychiare/sessions-tokens-and-rocknroll-4pdc).

Roughly, the cookie-based authentication flow is as follows:

1. The user authenticates through a web page.
2. The server generates a cookie and sends it to the browser with the response page.
3. The browser sends the cookie with each new page request.
4. If the server finds the cookie in the incoming request, it can use it to get the relevant information to make its authorization decisions.

The fun fact is that the cookie's back and forth is automatically managed by the browser. Provided that the server applies all [the security best practices](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html#cookies) to protect its cookies, your application doesn't need to care about storing them and sending them back with each request.

### Token-based authentication

Token-based authentication doesn't rely on cookies to prove user authentication. It relies on a token, which is a unique string of characters that also represents the user's session.

> To learn more about [how tokens help build sessions, check out this article](https://dev.to/andychiare/sessions-tokens-and-rocknroll-4pdc).

Awesome! How does the token-based flow work? Here is a rough description:

1. The user authenticates via a client-side page that calls the login endpoint.
2. The server generates a token and sends it to the app in the login endpoint's response.
3. The app sends the token with each new HTTP request.
4. If the server finds the token in the incoming request, it can use it to get the relevant information to make its authorization decisions.

As you can see, this flow is basically the same as the cookie-based flow. The only difference is that this one mentions the token instead of the cookie. So what is the real difference between the two approaches?

<details>
  <summary>What does authentication mean in this context?</summary>

If you are an experienced developer, you should already know the difference between **authentication** and **authorization**. Very roughly, authentication verifies the identity of the user while authorization verifies what the user can do.

Cookie-based authentication and token-based authentication are somewhat ambiguous terms. In fact, in this context, the cookie and the token indicate that the user has been successfully authenticated. However, they are used to make authorization decisions. When the server receives a request from a client, it checks if a cookie or a token is included in it. If so, the cookie or the token allows the server to somehow retrieve information to determine whether or not the request can be fulfilled. This information may also include the user profile data, of course. The specific way used to retrieve this information does not really matter.

This means that there is no real user authentication when sending a request to the server. User authentication has already taken place at the beginning of the session.
</details>

### Cookies and tokens: a quick comparison

As you learned in the previous sections, cookie-based and token-based authentication are very similar. The main visible difference is the artifact they rely on to prove authentication and support session creation. However, there are significant differences. I will not go into a detailed comparison between cookies and tokens, but I can't help but mention at least the following:

- **Cookies** are *tied to a domain*, require *little storage*, and are *automatically managed by the browser*. However, without proper precautions, they are vulnerable to [CSRF](https://auth0.com/blog/cross-site-request-forgery-csrf/) and [XSS attacks](https://auth0.com/blog/cross-site-scripting-xss/), are *not suitable for multi-domain applications*, and have *scalability issues*.
- **Tokens** are *not tied to only web applications* and they *promote server scalability*. However, *their management and security is left to the developer*. Depending on the type of token, there may be an *invalidation problem*, i.e. a revoked token may still be used by the client, and a *data transfer overhead* if the token size becomes significant.

> It's worth noting that while cookies in general can lead to scalability issues when used as pointers to server-side data, this is not the case with the authentication cookie issued by ASP.NET Core Identity. By default, this cookie contains encrypted data that allows the server to retrieve the user's identity information without having to access a server-side store. However, you need to [properly configure your servers](https://learn.microsoft.com/en-us/aspnet/core/security/data-protection/configuration/overview) in order to share the same encryption/decryption key.

That said, when should you use one type of authentication over the other?

### Which authentication type to use?

There's a common belief that cookie-based authentication should be used for traditional server-side page-rendered applications, while token-based authentication is for SPAs and native applications.

Actually, the ASP.NET Core Identity framework uses the cookie-based authentication approach for ASP.NET Core MVC and Razor Pages applications. With these types of applications, each request triggers a complete reload of the entire web page in the browser. In previous versions of .NET, if you wanted to leverage the ASP.NET Core Identity built-in authentication pages in your SPA, the user experience would be disrupted. Users would pass from the partial page reload experience typical of a SPA to a full page reload experience. This is one of the reasons behind the request of token-based authentication from many developers. They feel that having a token and a set of authentication APIs, such as the Identity API, allows them to build a consistent user experience for SPAs. In addition, this API can also be used by native applications, i.e., desktop and mobile applications, which were excluded by the traditional cookie-based approach.

This criterion may seem reasonable, but...

## Wait! Identity API Endpoints Have Cookies Too?

So, in general, you might think that cookie-based authentication is meant for traditional server-rendered applications, while token-based authentication is meant for SPAs and native applications.

However, if you dig into [the currently sparse documentation](https://devblogs.microsoft.com/dotnet/whats-new-with-identity-in-dotnet-8/#securing-blazor-webassembly-apps), you will find that you can call the authentication endpoint (`/login`) with the `useCookies=true` parameter. In other words, you can call the following endpoint: `/login?useCookies=true`. What does this mean? What scenario does it cover?

Well, despite many developers thinking that SPA should use token-based authentication, this is not always the case. Think about this for a moment:

- Why should you use tokens and manage the back-and-forth and their security when you can use cookies to take advantage of the built-in capabilities of browsers?
- What can you do with a token that you can't do with a cookie?
- In other words, do you really need a token in your specific scenario?

As a general rule, you should use the right tool for your specific needs. Over-designing or following common sense can lead to extra work and possible risks because you have to worry about token security.

If the client of your Web API application is a native client, you are forced to use token-based authentication. Supporting cookies in native applications would be impractical. However, you can use cookies in your SPA. Provided that your application lives in a single domain, you can use cookies and their automatic management by browsers. Why not?

If your application consists of a SPA and a Web API, and you authenticate users locally using ASP.NET Core Identity, you should use cookie-based authentication. Technically, your application is a first-party application, and even [OAuth best practices](https://www.ietf.org/archive/id/draft-ietf-oauth-browser-based-apps-14.html#section-6.1) recommend using this approach.

## Why Are These Tokens Not JWTs?

Another common misconception is that *token* means *JSON Web Token* (JWT). I've seen many developers react as shown in the following picture when they learn that the token issued by the Identity API is not in JWT format:

![Why not JWT?](https://images.ctfassets.net/23aumh6u8s0i/4CaZUMohAdvA2AiEDtfGjx/6585793bf36b74b70f29610f448ceb97/why-not-jwt.png)

Actually, that token has a proprietary format, although you can partially decode it. Read [this article](https://nestenius.se/2023/08/29/bearertoken-the-new-authentication-handler-in-net-8/) if you want to learn more about what's inside the access and refresh tokens issued by the Identity API.

Again, why do developers think the JWT format would have been better in this context? If your application is a first-party application in the authentication context, why do you need JWT?

The JWT format was invented to share information between two trusted parties. In the authentication and authorization context, a typical example of JWT adoption is when a third-party entity authenticates or authorizes a user. In this case, the third-party entity (the Identity provider or authorization server) issues a JWT containing the information related to the authentication or authorization result.

The need for a JWT arises from the fact that the third-party entity and your application are independent; they do not share a common data source.

Your application receives the result of the requested operation in the form of a JWT and it can verify that this information was actually issued by that entity by validating the token's signature. To be precise, only OpenID Connect defines a [JWT-based format for ID tokens](https://openid.net/specs/openid-connect-core-1_0.html#IDToken). OAuth 2.0 doesn't recommend [a specific format for access tokens](https://datatracker.ietf.org/doc/html/rfc6749#section-1.4), although [one is available](https://datatracker.ietf.org/doc/html/rfc9068).

> To learn more about [ID token and access token differences, see this article](https://auth0.com/blog/id-token-access-token-what-is-the-difference).

The point is, does your application really need the JWT format for access tokens? If so, your scenario may be different from what the Identity API was designed for. In a first-party scenario, your server should have all the information it needs to make authorization decisions.

<include src="ebook-ads/dotnetIdentity" />

## When Do You Need OpenID Connect and OAuth 2.0?

Developer reactions to the new Identity API make me think that they have been waiting for a built-in OpenID Connect and OAuth 2.0 implementation. They would probably expect Microsoft to have replaced Identity Server with its own OpenID Connect server. However, this may sound somewhat contradictory, since many have complained about the complexity of Identity Server in simple authentication scenarios.

Leaving aside speculation about what some developers expected, .NET 8 and its version of ASP.NET Core Identity is now here with its new authentication options. When should you use it in your applications and when do you need OpenID Connect and OAuth 2.0?

ASP.NET Core Identity can be the right solution if you need to build an application with basic authentication needs. Your users are authenticated locally, you don't expect much traffic and therefore don't plan to scale anytime soon, you don't have complex custom authentication needs. You can also integrate with external identity providers. I recommend using cookie-based authentication for web applications (including SPAs) and token-based authentication only for native apps.

OpenID Connect comes into play when your needs go beyond a simple authentication. You should look for a standards-compliant Identity provider if you need [Single Sign-On](https://auth0.com/docs/authenticate/single-sign-on) (SSO), for example. If you expose your API to third parties, you can leverage the benefits of a standard authorization approach such as OAuth 2.0. In these cases, ASP.NET Core Identity is not a good fit.

Check [this document](https://learn.microsoft.com/en-us/aspnet/core/security/how-to-choose-identity-solution?view=aspnetcore-8.0) for some guidance on when ASP.NET Core Identity is sufficient or when you need an OpenID Connect server.

## Some Caveats About Identity API Endpoints

The discussion so far is intended to help you make the right choices for authentication in your .NET applications based on your specific application scenario. This will help you avoid overdesign and make an informed choice about the right approach.

If you have decided to use the Identity API for your SPA and native application, there are still a few caveats that you still need to be aware of.

The Identity API is a great addition that allows you to leverage the user authentication and management under the hood, while you can customize your own UI. However, there is currently no way to make its endpoints unavailable. All Identity API endpoints are exposed. For example, anyone can call the `/register` endpoint to create a new user, regardless your application's business logic expects self-registered users or not. Presumably this will be fixed in the future, but as for .NET 8, it's like this.

A second concern is that you can't customize the Identity API endpoints. In most cases, you may not need customization, but what can you do if you need to customize the data required in the `/registration` endpoint? Or even add an unsupported authentication method, such as [WebAuthn](https://webauthn.me/introduction)?

Include these questions in your ASP.NET Core Identity evaluation.

<include src="SignupCTA" />

## Recap

In summary, .NET 8 brings exciting new features to ASP.NET Core Identity: token-based authentication and the Identity API.

However, this does not mean that they are the right approach for your specific scenario. Take some time to analyze what you need right now and in the near future. Don't follow the trend without carefully analyzing your needs and what ASP.NET Core Identity can offer you. You probably don't need token-based authentication for your SPA. Perhaps the simple token format for the Identity API is enough for your needs.

Anyway, if your analysis leads you to use OpenID Connect, don't forget that [Auth0 can help you](https://a0.to/blog_signup)! 😎


Cookies, Tokens, or JWTs? The ASP.NET Core Identity Dilemma

Let’s explore the new features brought by .NET 8 to support authentication and authorization in your applications.

The release of **.NET 8** is just around the corner. Among the amazing features it brings to developers, it offers a minor revolution in support for authentication and authorization: moving ASP.NET Core Identity from a page-oriented approach to an API-oriented approach.

Let's explore what's going on.

## ASP.NET Core Identity and Token-based Authentication

ASP.NET Core developers have the built-in [ASP.NET Core Identity](https://learn.microsoft.com/en-us/aspnet/core/security/authentication/identity) framework to add support for local authentication and authorization. The identity framework includes everything that developers typically need to authenticate and authorize users against a local user store. By default, a SQL Server database is created on Windows and a SQLite database is created on macOS, but you can change it to the DBMS of your choice.

The ASP.NET Core Identity framework is designed for server-rendered web applications, such as ASP.NET Core MVC or Razor Pages applications, and has challenges with SPAs, where token-based authentication seems more appropriate. To address this problem, Microsoft has provided built-in project templates for SPAs based on Angular and React with Identity Server support since .NET Core 3.1. However, the .NET community [has not been totally happy with this approach](https://github.com/dotnet/aspnetcore/issues/42158). To [meet the community's demands](https://github.com/dotnet/aspnetcore/issues/42158#issuecomment-1481742187), Microsoft removed the default support for Identity Server in .NET 8 and redesigned the internal architecture of ASP.NET Core Identity to be more suitable for SPAs and native apps. .NET 8 introduces a new set of Identity API endpoints and support for token-based authentication. But let's go in order.

## Bearer Token Authentication Handler

The first building block of this new infrastructure is the new [bearer token authentication handler](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.dependencyinjection.bearertokenextensions.addbearertoken). This handler is similar to the classic [cookie authentication handler](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.dependencyinjection.cookieextensions.addcookie) that ASP.NET Core Identity uses by default. The cookie authentication handler is responsible for two things:

- Creating a new session cookie after the user authenticates.
- Building a `ClaimsPrincipal` user object based on a valid session cookie received in the incoming HTTP request.

Similarly, the bearer token authentication handler is responsible for:

- Creating a new token after the user authenticates.
- Building a `ClaimsPrincipal` user object based on a valid token received in the incoming HTTP request.

In other words, the bearer token handler mimics the behavior of the cookie handler to manage authenticated sessions based on a token instead of a cookie.

> Note that the tokens generated by the bearer token handler are not in JWT format. Also, they don't follow any specific standard. While the documentation mentions [access tokens](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.authentication.bearertoken.accesstokenresponse.accesstoken?view=aspnetcore-8.0) and [refresh tokens](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.authentication.bearertoken.accesstokenresponse.refreshtoken?view=aspnetcore-8.0), they do not implement the [OAuth 2.0 authorization framework](https://oauth.net/2/).

How can this bearer token handler be used in practice?

Consider the following code:

```csharp
// Program.cs

using Microsoft.AspNetCore.Authentication.BearerToken; //👈
using System.Security.Claims;
 
var builder = WebApplication.CreateBuilder(args);
 
builder.Services
    .AddAuthentication()
    .AddBearerToken();  //👈
builder.Services.AddAuthorization();
 
var app = builder.Build();
 
app.MapGet("/login", (string username) =>
    {
        var claimsPrincipal = new ClaimsPrincipal(
          new ClaimsIdentity(
            new[] { new Claim(ClaimTypes.Name, username)},
            BearerTokenDefaults.AuthenticationScheme  //👈
          )
        );

        return Results.SignIn(claimsPrincipal);
    });
 
app.MapGet("/user", (ClaimsPrincipal user) =>
    {
        return Results.Ok($"Welcome {user.Identity.Name}!");
    })
    .RequireAuthorization();
 
app.Run();
```

This application defines two API endpoints:

- The `/login` endpoint creates a `ClaimsPrincipal` user object based on the username sent in the HTTP request and returns the result of signing in.
- The `/user` endpoint returns the username of the authenticated user.

Note the highlighted lines in the code. You have a reference to the new `Microsoft.AspNetCore.Authentication.BearerToken` namespace, which gives you access to the `BearerTokenDefaults.AuthenticationScheme` value. You also configure the bearer token middleware by using the `AddBearerToken()` extension method.

Now, assume you call the `login` endpoint with curl, as shown below:

```bash
curl 'https://<YOUR_HOST>/login?username=joe'
```

You will see a result like the following:

```json
{
  "token_type": "Bearer",
  "access_token": "CfDJ8Ha5YkqG...omitted content...",
  "expires_in": 3600,
  "refresh_token": "CfDJ8Ha5YkqG...omitted content..."
}
```

This JSON contains an access token and a refresh token that you can use to make your calls to the protected APIs exposed by your application. For example, you can now call the protected `/user` endpoint as follows:

```bash
curl -i https://<YOUR_HOST>/user \
-H 'Authorization: Bearer CfDJ8Ha5YkqG...omitted content...'
```

And you will get the following response:

```json
Welcome joe!
```

In summary, the bearer token authentication handler makes it very easy to set up token-based authentication. This is the building block of the whole ASP.NET Core Identity transition to token-based authentication.

## Identity API Endpoints

The second step in adding token-based authentication to ASP.NET Core Identity is to introduce the Identity API endpoints. Basically, this is an API version of the actions that you can perform with ASP.NET Core Identity through the classic web UI. Once you enable the [Identity API endpoints](https://github.com/dotnet/aspnetcore/blob/main/src/Identity/Core/src/IdentityApiEndpointRouteBuilderExtensions.cs), you will get endpoints like `/register`, `/login`, `/forgotPassword`, `confirmEmail`, etc.

The Identity API endpoints solve two of the most complained problems:

- You can build your own UI for user authentication and account management while maintaining the overall UI style of your application.
- After authentication, your app can get access tokens instead of cookies, so it's a more suitable approach for SPAs and native applications.

> Keep in mind that the Identity API endpoints do not implement [OpenID Connect (OIDC)](https://auth0.com/docs/authenticate/protocols/openid-connect-protocol). They simply expose the standard functionality provided by the ASP.NET Core Identity UI through a custom API. They are intended for first-party authentication.

Adding the Identity API endpoints to an ASP.NET Core application relies on two new methods:

- `AddIdentityApiEndpoints()`, which configures the token-based authentication using the bearer token handler in addition to the cookie authentication, and adds a set of identity services.
- `MapIdentityApi()`, which actually adds the Identity endpoints to your application.

The code in your `Program.cs` file will look like the following:

```csharp
// Program.cs

using System.Security.Claims;
using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthorization();

builder.Services.AddDbContext<ApplicationDbContext>(
    options => options.UseSqlite(builder.Configuration["ConnectionString"]));

builder.Services.AddIdentityApiEndpoints<IdentityUser>()
    .AddEntityFrameworkStores<ApplicationDbContext>();

var app = builder.Build();

app.MapIdentityApi<IdentityUser>();

app.MapGet("/user", (ClaimsPrincipal user) =>
    {
        return Results.Ok($"Welcome {user.Identity.Name}!");
    })
    .RequireAuthorization();

app.Run();
```

Your client will be able to register a user by calling the `/register` endpoint, authenticate the user through the `/login` endpoint, and so on.

While the Identity API endpoints seem to solve the two main complaints about the classic ASP.NET Core Identity, there are [some concerns about using them in a production context](https://andrewlock.net/should-you-use-the-dotnet-8-identity-api-endpoints/), mainly on the security and scalability side.

## Blazor Identity UI

In addition to the changes to ASP.NET Core Identity, .NET 8 integrates the authentication framework into the Blazor project template. You can create a new .NET 8 Blazor application with identity support by running the following command:

```bash
dotnet new blazor -au Individual
```

You will get a Blazor application with everything you need to manage users and authentication locally. You will get a SQLite database to store the user accounts. You will get a SQL Server database if you use Visual Studio to scaffold the application instead of the .NET CLI. You also will get all the pages that allow users to register, authenticate, and manage their account.

The following image shows the built-in login page of a Blazor app:

![Blazor login page](https://images.ctfassets.net/23aumh6u8s0i/3J8DlVMk9qsHw9tLIAwpue/cd94d62d51ce5dc6627bda3c75d14a42/blazor-identity-ui-login.png)

The user authentication and management pages that implement the Blazor Identity UI are not Razor pages as it happens with the classic ASP.NET Core Identity, but [Razor components](https://learn.microsoft.com/en-us/aspnet/core/blazor/components). The template provides you with the source code for all of the UI components in the `Pages/Account` folder of the project. This allows you to customize them according to your application design.

<include src="ebook-ads/dotnetIdentity" />

## Custom Authorization Policies Simplification

Apart from the new features related to ASP.NET Core Identity, .NET 8 introduces a simplification to the definition of custom authorization policies. Previously, you had to write a lot of code to define a parameterized authorization policy to apply to an API endpoint.

For example, suppose you want to define a policy for an endpoint that only authorizes users over the age of 18 and that can be used as shown below:

```csharp
[ApiController]
[Route("api/[controller]")]
public class DrinkController : Controller
{
    [MinimumAgeAuthorize(18)]
    [HttpGet("beer")]
    public string BeerDispenser(ClaimsPrincipal user) => $"Here is your beer, {user.Identity?.Name}!";
}
```

With previous .NET versions, to implement your custom authorization policy, you must write the code outlined in the following code snippet:

```csharp
class MinimumAgeAuthorizeAttribute : AuthorizeAttribute
{
  ...
}

class MinimumAgePolicyProvider : IAuthorizationPolicyProvider
{
  ...
}

class MinimumAgeRequirement : IAuthorizationRequirement
{
  ...
}

class MinimumAgeAuthorizationHandler : AuthorizationHandler<MinimumAgeRequirement>
{
  ...
}
```

You must define an `AuthorizeAttribute`. Then you need to implement an `IAuthorizationPolicyProvider` to handle your custom policy and an `IAuthorizationRequirement` to define the requirement. Finally, you have to implement the `AuthorizationHandler`.

The code snippet shown above outlines the classes you need to implement. To see an example of the actual implementation, take a look at this [code sample](https://gist.github.com/captainsafia/309e408cb5e2c2e5acd44d2e19f7f88e).

Using the new `IAuthorizationRequirementData` interface, your implementation code becomes as follows:

```csharp
class MinimumAgeAuthorizeAttribute : AuthorizeAttribute, IAuthorizationRequirement, IAuthorizationRequirementData
{
  public MinimumAgeAuthorizeAttribute(int age) => Age =age;
  public int Age { get; }

  public IEnumerable<IAuthorizationRequirement> GetRequirements()
  {
    yield return this;
  }
}

class MinimumAgeAuthorizationHandler : AuthorizationHandler<MinimumAgeAuthorizeAttribute>
{
  protected override Task HandleRequirementAsync(AuthorizationHandlerContext context, MinimumAgeAuthorizeAttribute requirement) 
  {
    ...
  }
}
```

You only need to implement two classes instead of four as in the previous example. See [here](https://gist.github.com/captainsafia/7c54e92d12df695ff0908e989fb8531f) for the complete code.

## Summary

Throughout this article, you have learned about the new features that .NET 8 brings to support authentication and authorization. Most of these features are related to the extension of the ASP.NET Core Identity framework to support token-based authentication, which paves the way for authentication in SPAs and native applications.

As a side effect, you get access to the bearer token authentication handler, which allows you to issue access tokens, and to the Identity API endpoints, which allow you to embed authentication support in your Web API.

In addition, the Blazor project template now supports authentication through the Identity API endpoints and a rich set of Razor components designed for user authentication and management.

Finally, the new `IAuthorizationRequirementData` interface allows you to create custom authorization policies with less code.


.NET 8: What's New for Authentication and Authorization

Learn how to validate a JSON Web Token (JWT) in different contexts using C# in .NET.

**JSON Web Tokens (JWTs)** have become very popular. Many developers use them in their applications for authentication and authorization purposes, but not all of them really know why and how to validate their JWTs.

This article will explain why you need to validate a JWT, what it means in general, and give you an overview of the many ways you can do it in the .NET platform.

## What Are JWTs?

If you landed on this article, you probably know what a JSON Web Token is. If not, [here is a great introduction to JWTs](https://jwt.io/introduction) and [a tool to decode them](https://jwt.io/#debugger-io).

Simply put, JSON Web Token is an [open standard](https://datatracker.ietf.org/doc/html/rfc7519) that defines how to share information between parties using the [JSON format](https://datatracker.ietf.org/doc/html/rfc8259). The [JWT structure](https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-token-structure) consists of three concatenated Base64 url-encoded strings, separated by dots: the header, the payload, and the signature The information carried by a JWT is **digitally signed so you can verify its origin and trust it**. The digital signature also guarantees the integrity of the information, but it doesn't guarantee privacy unless explicitly encrypted.

Besides this, the JWT specification doesn't define the specific purpose of a token. While most developers think of authentication when dealing with JWTs, this is not an intrinsic property of tokens in the JWT format. JWT is just a format. The meaning of the token depends on the specific context or application.

For example, in the [OpenID Connect](https://openid.net/developers/how-connect-works/) (OIDC) context, the JWT format is used for the ID token, which is the token that proves a user is authenticated. In the [OAuth 2.0](https://auth0.com/docs/authenticate/protocols/oauth) context, the [JWT format can optionally be used for the access token](https://datatracker.ietf.org/doc/html/rfc9068), which is the token that allows a client application to access a specific resource on behalf of the user.

> To learn more about ID and access tokens and their differences, you can read [this blog post](https://auth0.com/blog/id-token-access-token-what-is-the-difference/) or watch [this video](https://www.youtube.com/watch?v=vVM1Tpu9QB4) instead.

<include src="ebook-ads/JwtHandbook" />

## What Does Token Validation Mean?

The main purpose of a JWT is to carry information that the recipient can trust. So, the first thing your application needs to do when it receives a JWT is to ensure that the information it carries is trustworthy. This is where validation comes in.

In short, validating a JSON Web Token means ensuring that the token has the structure defined in the standard specification and that you can trust the information it carries.

The JWT validation is based on the following five criteria:

- **Token structure**. The first check is about the token's structure. Does the token match the structure of a JSON Web Token? If the token doesn't follow the standard guidelines, it's not valid.

- **Token integrity**. The next check is for the token's integrity. Has the token been tampered with? You can verify this by checking the signature. If you verify that the token's signature is valid, then it has not been altered in any way.
- **Token expiration**. JWTs have an expiration time defined in the `exp` claim. Is the token expired when it has been received? If a token has expired, you should no longer trust its contents.
- **Expected authority**. The next check is to verify that the token was issued and signed by the expected sender (authority). There are two steps to this check:
  - Verify that the authority is the one expected by your application by comparing it to the `iss` claim (issuer).
  - Verify that the key used to sign the JWT actually belongs to the expected authority.
- **Expected audience**. Finally,  verify that the token is intended for your application. In other words, you should check that the `aud` claim matches with the value that identifies your application. For example, in an ID token, the value for the audience is the client ID; in an access token in JWT format, the value for the audience is the [API identifier](https://auth0.com/docs/get-started/apis/api-settings#general-settings).

> To learn more about [digital signatures, read this article](https://auth0.com/blog/how-to-explain-public-key-cryptography-digital-signatures-to-anyone/). Check out [this article](https://auth0.com/blog/rs256-vs-hs256-whats-the-difference/) for the differences between the signing algorithms used in a JWT.

Token validation doesn't involve the custom information carried by the token. This is an application-specific logic, which is out of the scope of token validation. For example, validating an ID token does not include verifying that the user's email address in the `email` claim exists.

## Validate a JWT Using an Auth0 SDK

Now that you know what validating a JWT means, you are ready to learn how to validate your tokens in .NET.

Before jumping into the validation code, you should evaluate whether you really need to explicitly validate the JWTs you receive from an issuer like Auth0. Depending on the specific application, you may want to use an Auth0 SDK, which will take care of all the validation steps for you. For example, if you are developing an ASP.NET Core MVC application or a Blazor Server application, you can use the [Auth0 ASP.NET Core Authentication SDK](https://github.com/auth0/auth0-aspnetcore-authentication). This SDK will take care of the entire process of obtaining the JWT tokens for your application, including token validation. Check out [this article](https://auth0.com/blog/exploring-auth0-aspnet-core-authentication-sdk/) for an overview of this specific SDK.

So, if your application can benefit from an SDK, the best move is to write less code and get the JWT validation for free. Take a look at [this article to learn which Auth0 SDK is right for your .NET application type](https://auth0.com/blog/choose-the-right-dotnet-sdk-for-auth0/). 

## Using the ASP.NET Core Middleware

If, for some reason, you can't use an Auth0 SDK, you can configure your ASP.NET Core application by using two middleware:

- The [OpenIdConnect middleware](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.OpenIdConnect), which allows your ASP.NET Core web applications to authenticate users and get ID and access tokens via [OpenId Connect](https://openid.net/developers/how-connect-works/).
- The [JwtBearer middleware](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.JwtBearer), which enables your ASP.NET Core web API to handle access tokens.

Both middleware provide you with a convenient way to obtain and validate JWT tokens. The following code snippet shows an example of how to configure OpenIdConnect middleware:

```csharp
// Program.cs

var builder = WebApplication.CreateBuilder(args);


builder.Services.AddAuthentication(options => {
    options.DefaultAuthenticateScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultSignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = CookieAuthenticationDefaults.AuthenticationScheme;
  })
  .AddCookie()
  .AddOpenIdConnect("Auth0", options => {
    options.Authority = $"https://{builder.Configuration["Auth0:Domain"]}";
    options.ClientId = builder.Configuration["Auth0:ClientId"];
    options.CallbackPath = new PathString("/callback");
  });

// ...other code...
```

The next example shows how to use the JwtBearer middleware:

```csharp
// Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
  .AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, options =>
  {
    options.Authority = $"https://{builder.Configuration["Auth0:Domain"]}";
    options.Audience = builder.Configuration["Auth0:Audience"];
  });

// ...other code...
```

In both cases, by configuring the `Authority` option, you implicitly ask the middleware to validate your tokens. The middleware will use this value to retrieve the issuer's signing key, which is needed to validate the token's signature. All the other required validation steps are performed automatically. There is nothing else you need to do.

### Simplified configuration for the JwtBearer middleware

Starting with .NET 7, you can [use the JwtBearer middleware in a simplified way](https://auth0.com/blog/whats-new-in-dotnet-7-for-authentication-and-authorization/#Simplified-Configuration). You define your validation values in the `appsettings.json` file, as in the following example:

```json
// appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Authentication": {
    "Schemes": {
      "Bearer": {
        "Authority": "https://{DOMAIN}",
        "ValidAudiences": [ "{AUDIENCE}" ],
        "ValidIssuer": "{DOMAIN}"
      }
    }
  }
}
```

Then you can simply add the middleware to your ASP.NET Core application, as follows:

```csharp
// Program.cs

// ...existing code...

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication().AddJwtBearer();

// ...existing code...
```

The behavior is exactly the same as before but with much less code.

### Custom validation with the ASP.NET Core middleware

If you have specific needs, you can customize the JWT validation using the `TokenValidationParameters` option. For example, if you already have the issuer's public key stored on your file system, you can configure your middleware as shown in the following example:

```csharp
// Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
  .AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, options =>
  {
    options.Audience = builder.Configuration["Auth0:Audience"];
    options.TokenValidationParameters = 
      new Microsoft.IdentityModel.Tokens.TokenValidationParameters
      {
        ValidateIssuer = true,
        ValidIssuer = $"{builder.Configuration["Auth0:Domain"]}",
        ValidateIssuerSigningKey = true,
        IssuerSigningKey = new X509SecurityKey(new X509Certificate2(certificateFilePath)),
        ValidateLifetime = true
      };
  });

// ...other code...
```

You can see that the `Audience` option is still there while the `Authority` option is missing. Instead of the `Authority` option, you find the `TokenValidationParameters` option, which is assigned an instance of the `TokenValidationParameters` class. The properties of this instance define what to check in order to complete the JWT validation. Specifically, you ask to validate the issuer (`ValidateIssuer`) and provide the value to match with (`ValidIssuer`). You ask to validate the issuer's signature (`ValidateIssuerSigningKey`) and provide the issuer's public signing key (`IssuerSigningKey`) embedded in a certificate stored in the file system. And finally, you ask to check the expiration time (`ValidateLifetime`).

You can see how removing the `Authority` option from the middleware configuration forces you to manually specify what to check in order to validate the token.

## Validate a JWT “By Hand”

In case you can't use the ASP.NET Core middleware, for example, when you are not developing a web application, don't get desperate. .NET gives you what you need, although this requires some effort on your side.

### Validate your token

First, you need to install the `Microsoft.IdentityModel.Tokens` package from NuGet:

```bash
dotnet add package Microsoft.IdentityModel.Tokens
```

This package provides everything you need for token manipulation, including validation, of course.

Have a look at the following function:

```csharp
public bool ValidateToken(
  string token, 
  string issuer, 
  string audience, 
  ICollection<SecurityKey> signingKeys,
  out JwtSecurityToken jwt
)
{
  var validationParameters = new TokenValidationParameters {
          ValidateIssuer = true,
          ValidIssuer = issuer,
          ValidateAudience = true,
          ValidAudience = audience
          ValidateIssuerSigningKey = true,
          IssuerSigningKeys = signingKeys,
          ValidateLifetime = true
  };

  try
  {
    var tokenHandler = new JwtSecurityTokenHandler();
    tokenHandler.ValidateToken(token, validationParameters, out SecurityToken validatedToken);
    jwt = (JwtSecurityToken)validatedToken;
    
    return true;
  } catch (SecurityTokenValidationException ex) {
    // Log the reason why the token is not valid
    return false
  }
}
```

This function takes a token and validates it by using the other parameters: the issuer, the audience, and the signing keys. If the token is valid, it returns `true` and provides a `JwtSecurityToken` instance representing the token as the `jwt` output parameter.

Once again, you see the `TokenValidationParameters` class, which allows you to define the validation criteria. This time there is no implicit validation. You need to specify all the required validation criteria and the valid values. Then you create a token handler (`JwtSecurityTokenHandler`) and use it to validate the token against the validation parameters. If the validation succeeds, you get an object representing the token, which you assign to the output parameter after casting to `JwtSecurityToken`. Finally, the function returns `true`.

If the validation fails, it should log the reason for the failed validation and return `false`.

### Get the signing keys

The `ValidateToken()` function expects you to pass the basic information for the token validation: the token issuer identifier, the audience, and the issuer's signing keys. You may have all this information on hand or need to retrieve some of it. For example, you can obtain the signing key of the issuer online. According to the [OIDC standard](https://openid.net/specs/openid-connect-discovery-1_0.html), you can find the set of keys (*JSON Web Key Sets*) to verify the issuer's signatures at a public and well-defined URL: `https://{DOMAIN}/.well-known/openid-configuration`.

Read [this document to learn more about the JSON Web Key Sets](https://auth0.com/docs/secure/tokens/json-web-tokens/locate-json-web-key-sets).

To validate a JWT using the `ValidateToken()` function, you must first retrieve the signing key from this URL. As you can see, things start to get complex. This is why I suggest using an Auth0 SDK in the first place, or at least the ASP.NET Core middleware, if possible.

However, if using one of these tools is not feasible in your specific case, here is what you need to do to get the issuer's signing keys.

First, you need to install another package from NuGet: the `Microsoft.IdentityModel.Protocols.OpenIdConnect` package:

```bash
dotnet add package Microsoft.IdentityModel.Protocols.OpenIdConnect
```

This package provides you with the `ConfigurationManager` class, which helps you retrieve the JSON Web Key Sets. The following code shows you how to obtain the signing key of your JWT issuer:

```csharp
var configurationManager = new ConfigurationManager<OpenIdConnectConfiguration>(
  $"https://{builder.Configuration["Auth0:Domain"]/.well-known/openid-configuration}",
  new OpenIdConnectConfigurationRetriever(),
  new HttpDocumentRetriever());

  var discoveryDocument = await configurationManager.GetConfigurationAsync();
  var signingKeys = discoveryDocument.SigningKeys;
```

Once you have the signing keys, you are ready to use the `ValidateToken()` function.

## Recap

Throughout this article, you have learned what JWT validation is and why you need to do it. You also learned that as a .NET developer, you have many options for validating the JWTs your application receives: from a zero-code approach to an almost manual validation.

With the Auth0 SDKs, you get the JWT validation for free. No specific code is required. The SDKs validate tokens for you.

Using the ASP.NET Core middleware, OpenIdConnect and JwtBearer, you get implicit token validation in the default cases. However, you can customize your validation criteria if you are dealing with special cases.

In case you need full control over the validation process, you can rely on the `Microsoft.IdentityModel.Tokens` package for the JWT manipulation and validation and on the `Microsoft.IdentityModel.Protocols.OpenIdConnect` package for retrieving the issuer's signing keys.

Of course, the suggestion is to delegate as much as possible to the SDKs and middleware because the less code you write, the fewer bugs you may create 🙂.


How to Validate JWTs in .NET

Explore the logout issues with Blazor Server applications and learn how to resolve them.

Blazor Server and the Logout Problem

Create your .NET applications secured with Auth0 in less than a minute with Auth0 Templates for .NET.

<div class="alert alert-info alert-icon">
   <i class="icon-budicon-500"></i>
   <strong>A new version of Auth0 Templates for .NET is available!<br/>
Check out <a href="/blog/auth0-templates-for-dotnet-powerful-version/">Auth0 Templates for .NET: A New Powerful Version Released</a> to learn what new features it brings to you.
   </strong>
 </div>

Project templates are a handy way to scaffold an application in minutes, if not seconds. .NET developers are used to templates since Microsoft provides several built-in project templates for .NET through the [.NET SDK](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-new-sdk-templates) or [Visual Studio](https://learn.microsoft.com/en-us/visualstudio/ide/creating-project-and-item-templates).

Now you have .NET templates with Auth0 embedded, including the right Auth0 SDK and best practices for a given type of application! You can build your .NET projects integrated with Auth0 in seconds using the .NET CLI or the IDE you prefer: Visual Studio or Visual Studio Code.

## What Is Auth0 Templates for .NET?

[Auth0 Templates for .NET](https://github.com/auth0/auth0-dotnet-templates) is a project that provides you with a set of project templates to help you scaffold your application with Auth0 support for authentication and authorization. Currently, the project offers templates for the following application types:

- ASP.NET Core MVC
- ASP.NET Core Web API
- Blazor Server
- Blazor WebAssembly (ASP.NET Core hosted)

More templates will be added in the near future. The templates target .NET 7 and allow you to create your applications by using the typical approach you are accustomed to using the built-in templates.

## Install the Package

The Auth0 Templates for .NET project uses the [modern template approach](https://learn.microsoft.com/en-us/dotnet/core/tools/custom-templates), which guarantees high compatibility across different development environments and operating systems. This means that you can use the templates with your preferred development environment: .NET CLI, Visual Studio for Windows and Mac, or Visual Studio Code.

Even JetBrains Rider is supported, but at the time of writing, there is still an [issue with parameter support](https://youtrack.jetbrains.com/issue/RIDER-16759) that prevents the full power of the templates from being used.

To install the [Auth0 Templates for .NET NuGet package](https://www.nuget.org/packages/Auth0.Templates/), run the following command in a terminal window:

```bash
dotnet new install Auth0.Templates::2.0.1
```

Once the package is installed, use your preferred IDE to create your application.

## Create Your .NET Project

Let's see how you can use the templates to create a new .NET application. First, there are some preliminary steps to take. The templates assume that you have already registered your application with Auth0 and have all the necessary configuration settings at hand.

To integrate your application with Auth0, you need an Auth0 account. You can <a href="https://a0.to/blog_signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">sign up for a free one now</a>. Then you need to [register your application](https://auth0.com/docs/get-started/auth0-overview/create-applications) or [your API](https://auth0.com/docs/get-started/auth0-overview/set-up-apis) in the Auth0 dashboard. The registration step will return some data that you will use to set up your app through the templates. Basically, this data is a subset of the following:

- the Auth0 domain, 
- the client ID, 
- the client secret, 
- the API identifier or audience.

Once you have this data from the Auth0 dashboard, you are ready to use the Auth0 templates for building your app.

### Use the templates in .NET CLI

You can leverage the `dotnet new` command to list the available templates. For example, you can run the following command to get the list of available Auth0 templates:

```bash
dotnet new list auth0
```

As a result of this command, you should see the following list:

```bash
Template Name                 Short Name         Language  Tags                        
----------------------------  -----------------  --------  ----------------------------
Auth0 ASP.NET Core Web API    auth0webapi        [C#]      Web/WebAPI/Auth0            
Auth0 ASP.NET Core Web App    auth0webapp        [C#]      Web/MVC/Razor Pages/Auth0   
Auth0 Blazor Server App       auth0blazorserver  [C#]      Web/Blazor/Auth0            
Auth0 Blazor WebAssembly App  auth0blazorwasm    [C#]      Web/Blazor/WebAssembly/Auth0
```

Suppose you want to learn the CLI syntax for using the Blazor Server template. You run the following command in your terminal:

```bash
dotnet new auth0blazorserver --help
```

This command will show you all the options you can provide to build an already configured Blazor Server application.

To create a new Blazor Server app through the Auth0 template, use the following command:

```bash
dotnet new auth0blazorserver \
    --domain <YOUR_AUTH0_DOMAIN> \
    --client-id <YOUR_CLIENT_ID> \
    -o MyBrandNewApp
```

> The line continuation character (`\`) shown above is just for presentation purposes. Use the appropriate character for your command line shell if you want to use it in your operating system.

Replace the placeholders `<YOUR_AUTH0_DOMAIN>` and `<YOUR_CLIENT_ID>` with the actual values you got when registering your app in the Auth0 dashboard. This command will create your Blazor Server application in the `MyBrandNewApp` folder.

After creating the app, you can run it and test authentication support in a minute!

> Read [this document to learn how to use the available Auth0 templates](https://github.com/auth0/auth0-dotnet-templates/tree/main#usage).

### Use the templates in Visual Studio

The templates installed with the above command are also available in Visual Studio. Select the Auth0 template for the app you want to create, as shown in the following picture for Visual Studio for Windows:

![Auth0 templates in Visual Studio for Windows](https://images.ctfassets.net/23aumh6u8s0i/5A53ehX7663L0HxkB65Aos/2cbbbb09f3ad4c4979e052f4f02b2ac2/auth0-blazorserver-app-vs.png)

The following picture comes from Visual Studio for Mac:

![Auth0 templates in Visual Studio for Mac](https://images.ctfassets.net/23aumh6u8s0i/7nyet9ozGX1bk4Kf4AFipb/00d4a3fbb394bde20e132526244161ce/auth0-blazorserver-app-vs-mac.png)

You will then be prompted for the registration information, as shown in the following picture (Visual Studio for Windows):

![Auth0 template options in Visual Studio for Windows](https://images.ctfassets.net/23aumh6u8s0i/3YMXIB1UY58WD2iFCeydyX/8e03f036e38cc6a6a5136328c3077947/auth0-blazorserver-app-vs-options.png)

This is the corresponding screen on Visual Studio for Mac:

![Auth0 template options in Visual Studio for Mac](https://images.ctfassets.net/23aumh6u8s0i/2rctCGwBn68ACigGj6wf2L/98b0805b10d53e76d49014f53c9123f9/auth0-blazorserver-app-vs-mac-options.png)

Next, you specify the project's name and where you want to save it, as you would with standard templates. That's it! Once the application is created, you can run it and test authentication.

> Read [this document to learn how to use the available Auth0 templates](https://github.com/auth0/auth0-dotnet-templates/tree/main#usage).

<include src="ebook-ads/dotnetIdentity" />

## Looking Forward

This is the first release of the [Auth0 Templates for .NET](https://www.nuget.org/packages/Auth0.Templates/) package, but we want to add new templates and improve the developer experience as well. Your feedback is highly appreciated, so please leave your comments below and let us know what you think about this project.

The [Auth0 Templates for .NET project](https://github.com/auth0/auth0-dotnet-templates) is open source, so your contribution is also welcome! If you think you can help with this project, check out [our contribution policy](https://github.com/auth0/auth0-dotnet-templates/tree/main#contributing) and get involved.


Introducing Auth0 Templates for .NET

How to use the new user-jwts tool to test a protected ASP.NET Core Web API without involving an authorization server.

Test Authorization in ASP.NET Core Web APIs With the user-jwts Tool

Let’s explore the new .NET 7 features for improving and simplifying authentication and authorization support in .NET applications.

The release of .NET 7 continues the simplification effort that began with .NET 5. Following this line, the new release provides .NET developers with a few features related to authentication and authorization that make .NET developers' lives a bit easier. Let's take a quick look at those features, which range from simplifications in authentication configuration to the addition of new authorization test tools, to improvements to Blazor's authentication support.

## Default Authentication Scheme

When you configure authentication for your application, you need to register the authentication service through `AddAuthentication()`. For example, the following is the code needed to configure `JwtBearer` as the authentication scheme in an ASP.NET Core Web API:

```csharp
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
     .AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, options =>
     {
         options.Authority = $"https://{builder.Configuration["Auth0:Domain"]}";
         options.TokenValidationParameters = 
           new Microsoft.IdentityModel.Tokens.TokenValidationParameters
         {
             ValidAudience = builder.Configuration["Auth0:Audience"],
             ValidIssuer = $"{builder.Configuration["Auth0:Domain"]}"
         };
     });
```

Although you are defining just one authentication scheme (`JwtBearerDefaults.AuthenticationScheme`), the  `AddAuthentication()` method requires that you specify the default scheme to use when it is not specified in your API endpoints (see [this document for more details on multiple authentication schemes in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/security/authorization/limitingidentitybyscheme?view=aspnetcore-6.0#use-multiple-authentication-schemes)).

Starting with .NET 7, the default scheme is no longer required when you define just one authentication scheme. It is automatically inferred by the framework. In practice, you can write the previous code as follows:

```csharp
builder.Services.AddAuthentication() //👈 no default scheme specified
     .AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, options =>
     {
         options.Authority = $"https://{builder.Configuration["Auth0:Domain"]}";
         options.TokenValidationParameters = 
           new Microsoft.IdentityModel.Tokens.TokenValidationParameters
         {
             ValidAudience = builder.Configuration["Auth0:Audience"],
             ValidIssuer = $"{builder.Configuration["Auth0:Domain"]}"
         };
     });
```

In case you need to restore the old behavior for any reason, you can disable the new feature using the following statement:

```csharp
AppContext.SetSwitch("Microsoft.AspNetCore.Authentication.SuppressAutoDefaultScheme", true);
```

## Simplified Configuration

One of the recurrent critiques of .NET authentication and authorization is its complexity (see [this thread](https://www.reddit.com/r/dotnet/comments/vttrib/is_auth_way_too_hard_in_net/) and [this one](https://social.msdn.microsoft.com/Forums/en-US/4d3844d5-9175-49ba-8c2f-8257f2c67639/authentication-and-authorization-is-too-complicated-too-abstract?forum=aspdotnetcore), for example). Actually, .NET provides developers with an articulate system for managing authentication and authorization. This system is great for the flexibility it offers, but it may be hard for a beginner to digest all the details. It may be hard even for a more experienced developer who is not used to dealing with the identity features every day.

To overcome this issue, the .NET team started an initiative aiming at simplifying the authentication and authorization configuration. The .NET 7 release introduces the first step in this direction, bringing you a simplified approach to configure ASP.NET Core Web APIs authorization based on access tokens in JWT format.

> Check out [this article to learn how to protect your ASP.NET Core Web API](https://auth0.com/blog/aspnet-web-api-authorization/).

If you ever had secured an ASP.NET Core Web API with Auth0, the following code should look familiar to you:

```csharp
using Microsoft.AspNetCore.Authentication.JwtBearer;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
     .AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, options =>
     {
         options.Authority = $"https://{builder.Configuration["Auth0:Domain"]}";
         options.TokenValidationParameters = 
           new Microsoft.IdentityModel.Tokens.TokenValidationParameters
         {
             ValidAudience = builder.Configuration["Auth0:Audience"],
             ValidIssuer = $"{builder.Configuration["Auth0:Domain"]}"
         };
     });

builder.Services.AddAuthorization();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();
```

Now, you can directly rely on the built-in configuration system to define your Web API's authorization options. In fact, in addition to default authentication schemes, .NET 7 automatically loads the options to configure the authentication service from the new  `Authentication` section of the `appsettings.json` configuration file. With this new feature, the code shown earlier becomes as follows:

```csharp
using Microsoft.AspNetCore.Authentication.JwtBearer;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication().AddJwtBearer(); //👈 new feature

builder.Services.AddAuthorization();

var app = builder.Build();
```

All the configuration settings are moved to the `appsetting.json` file as follows:

```json
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  //👇 new section
  "Authentication": {
    "Schemes": {
      "Bearer": {
        "Authority": "https://YOUR_AUTH0_DOMAIN",
        "ValidAudiences": [ "YOUR_AUDIENCE" ],
        "ValidIssuer": "YOUR_AUTH0_DOMAIN"
      }
    }
  }
  //👆 new section
}
```

The new `Authentication` section keeps the configuration settings for any authentication scheme supported by your application, although currently only the `JwtBearer` scheme is supported.

Notice that now you don't need anymore to call `UseAuthentication()` and `UseAuthorization()`. The framework takes care of automatically adding the required middleware to the request pipeline.

## Authorization Policies for Specific Endpoints

ASP.NET Core allows you to specify policies to make more accurate authorization decisions based on the access token content or other advanced criteria. Usually, these policies are defined globally at the application level and attached to the endpoint definitions the policy applies to.

> Take a look at [this article to learn how to use policies to protect ASP.NET Core Web APIs](https://auth0.com/blog/permission-based-security-aspnet-webapi/), for example.

Defining policies globally is pretty good for reuse. However, sometimes you may need just a specific policy for one endpoint. In this case, you can specify your policy directly on the endpoint definition.

The following is an example of how you can use this new feature:

```csharp
app.MapGet("/api/special-endpoint", () => "A special endpoint!")
    .RequireAuthorization(p => p.RequireClaim("scope", "api:special"));
```

## The `user-jwts` Tool

Testing a token-protected Web API could be complex. You can easily use tools like curl or Postman, but you need to pass a valid access token along with your HTTP request. To get a valid access token, you usually need a working identity and access management system at your disposal, such as [Auth0](https://auth0.com/). You need to configure your API with this system and log in by providing valid credentials.

Auth0 allows you to test your registered API using a token issued directly in the [Auth0 dashboard](https://manage.auth0.com/), but you still need to register your application with Auth0.

.NET 7 brings a new CLI tool that helps simplify protected Web API testing: `user-jwts`. This tool is integrated with the .NET CLI and allows you to generate access tokens in JWT format. The tool is based on the same infrastructure as the [secret manager](https://auth0.com/blog/secret-management-in-dotnet-applications/) and enables your application to validate the generated access token. Basically, the following command allows you to generate a new access token:

```bash
dotnet user-jwts create
```

You can use this token with curl, Postman, or any other HTTP client to make your call to the protected endpoints of your Web API without the need to register your application with an actual identity and access management system.

Beyond the basic usage, the `user-jwts` tool allows you to customize your access token by specifying the scopes, custom claims, and other properties so that you can also test endpoints with access policies. See the [official documentation](https://learn.microsoft.com/en-us/aspnet/core/security/authentication/jwt-authn) to learn more.

<include src="ebook-ads/dotnetIdentity" />

## Dynamic Authentication Requests in Blazor WASM

Blazor WebAssembly uses the `Microsoft.AspNetCore.Components.WebAssembly.Authentication` package to handle OpenID Connect authentication. This package allows you to statically define at the startup time how authentication will occur. However, there are scenarios where you may need to authenticate users at runtime with a different configuration. For example, you may need to perform [step-up authentication](https://auth0.com/docs/secure/multi-factor-authentication/step-up-authentication) or may want the user to change their account.

In .NET 7, Blazor WebAssembly supports the creation of dynamic authentication requests using the new `InteractiveRequestOptions` class and the `NavigateToLogin()` method of the `NavigationManager` object.

The following example shows the basic use of these new features:

```csharp
InteractiveRequestOptions requestOptions = new()
{
    Interaction = InteractionType.SignIn,
    ReturnUrl = NavigationManager.Uri,
};
NavigationManager.NavigateToLogin("authentication/login", requestOptions);
```

The `InteractiveRequestOptions` class also provides a way to add custom parameters to the authentication request. For example, consider [Auth0's `screen_hint` parameter](https://auth0.com/docs/authenticate/login/auth0-universal-login/new-experience#signup) that allows you to show the signup form instead of the default login form. You can send this parameter to Auth0 as shown below:

```csharp
InteractiveRequestOptions requestOptions = new()
{
    Interaction = InteractionType.SignIn,
    ReturnUrl = NavigationManager.Uri,
};
requestOptions.TryAddAdditionalParameter("screen_hint", "signup");
NavigationManager.NavigateToLogin("authentication/login", requestOptions);
```

## Blazor WASM Authentication Diagnostics

Detecting authentication issues is not easy, especially if you are running a WebAssembly code, as it happens with Blazor WebAssembly applications. The .NET 7 release tries to improve its support for authentication diagnostics by introducing the debug level for the `Microsoft.AspNetCore.Components.WebAssembly.Authentication` library. After [enabling logging for Blazor WebAssembly](https://learn.microsoft.com/en-us/aspnet/core/blazor/fundamentals/configuration?view=aspnetcore-7.0#logging-configuration), you can add the following setting in the `wwwroot/appsettings.json` configuration file to get detailed information about the authentication process:

```json
"Logging": {
    "LogLevel": {
        "Microsoft.AspNetCore.Components.WebAssembly.Authentication": "Debug"
    }
}
```

<include src="SignupCTA" text="Try out Auth0 authentication for free." linkText="Get started →" />

## Conclusion

Probably the new features introduced by .NET 7 to mitigate the complexity of authentication and authorization support will not drastically change your life as a developer. However, they confirm the effort Microsoft is making to simplify the use of its development platform. In the area of authentication and authorization, the commitment to reduce configuration complexity with an [initiative](https://github.com/dotnet/aspnetcore/issues/34545) that will continue in subsequent .NET releases looks pretty promising.

I hope that the combination of these and future simplifications will go in the right direction of making authentication and authorization integration into .NET applications less and less challenging.


What's New in .NET 7 for Authentication and Authorization

A map to choose the right SDK to integrate Auth0 in your .NET application.

The .NET ecosystem has become quite complex. On the one hand, developers can create different types of applications for different platforms. On the other hand, in its 20-year history, .NET has generated different versions of the development platform, some incompatible with each other or compatible under specific criteria.

Auth0 provides developers with a few SDKs for different application types and different versions of the platform. Which one is right for your application? Let's find out together!

> If you want to find out directly what is the SDK or package to use in your .NET application to integrate with Auth0 without sitting through the rationale behind it, jump to the section [The Matrix of Solutions](#The-Matrix-of-Solutions).

## The Dimensions of the Problem

Let's start by exploring the dimensions of the problem, that is, the factors that influence the choice: the application type, the .NET target, and the role of Auth0.

### The application type

As the first dimension, you need to consider your **application type**. As a .NET developer, you know that the development platform allows you to create applications of several types: from Web to desktop apps, from Web APIs to mobile apps. You can also use different frameworks to build your app. For example, you leverage ASP.NET or ASP.NET Core to build a Web application, but you can use ASP.NET Core MVC or Razor Pages or Blazor as the frameworks that support your UI and application architecture. Something similar happens for desktop app UIs: you can use WinForms, Windows Presentation Foundation (WPF), Universal Windows Platform (UWP), Multiplatform Applcation UI (MAUI), etc.

Identifying your application type and the technology you use or you are going to use is the first step to determining which SDK you must use.

### The .NET target

The second dimension is the .NET version your application runs on, which in the .NET lingo is called **your application's target**. The .NET platform has evolved over the past two decades and has undergone several transformations. From the initial multi-language framework for Windows programming, it has now become a cross-platform development environment that enables the creation of Web, desktop, and mobile applications. You can take into account the following targets:

- *.NET Framework*. This was the initial Windows framework, which will be deprecated, but on which many applications still run.
- *.NET Core*. The initial cross-platform version of .NET, which is not fully compatible with the .NET Framework. The last .NET Core version was 3.1.
- *.NET Standard*. Actually, this is not a true .NET version. It is a specification that aims at defining a common set of APIs between .NET Framework and .NET Core to ensure a degree of compatibility between the two versions. Auth0 SDKs follow .NET Standard 2.0 specifications to keep this compatibility.
- *.NET*. This is the current and universal version of the development platform that aims to replace all the previous ones. From the Auth0 point of view, it can be seen as the evolution of .NET Core.

To learn more about [the differences between the .NET targets, check out this article](https://auth0.com/blog/navigating-dotnet-maze).

### The role of Auth0

The third dimension is **the purpose of using the Auth0 platform** in your application. Your application can use Auth0 for three main reasons:

- To add *authentication* so that your users can log in using the [Auth0 Universal Login](https://auth0.com/docs/authenticate/login/auth0-universal-login) page, Single Sign-On (SSO), Passwordless, Social Login, and the [other approaches available with Auth0](https://auth0.com/docs/authenticate).
- To *control access* so that only authorized users can use your application's functionality.
- To *manage users and other features* provided by your [Auth0 tenant](https://auth0.com/docs/get-started/auth0-overview/create-tenants).

Clarifying the purpose of Auth0 in your application is also important to determine which SDK you must use.

## The Auth0 SDKs and Packages

After analyzing the dimensions of the problem, let's see what Auth0 offers to meet the needs of .NET developers. You can use a few SDKs to integrate Auth0's authentication, authorization, and management features into your .NET applications. Each SDK includes one or more packages that you can install from [NuGet](https://www.nuget.org/profiles/auth0).

Let's take a look at these SDKs and their packages.

### Auth0 ASP.NET Core Authentication SDK

The [Auth0 SDK for ASP.NET Core Authentication](https://github.com/auth0/auth0-aspnetcore-authentication) is designed for adding authentication support to your Web application built with server-side frameworks: ASP.NET Core MVC, Blazor Server, and Razor Pages. It provides you with one package &mdash; [**Auth0.AspNetCore.Authentication**](https://www.nuget.org/packages/Auth0.AspNetCore.Authentication), which hides most of the complexity of the authentication and authorization process.

Check out [this article for a quick introduction to the Auth0 ASP.NET Core Authentication SDK's main features](https://auth0.com/blog/exploring-auth0-aspnet-core-authentication-sdk/).

### Auth0 OIDC Client for .NET

The [Auth0 OIDC Client for .NET](https://github.com/auth0/auth0-oidc-client-net) supports [OpenID Connect](https://auth0.com/docs/authenticate/protocols/openid-connect-protocol)-based authentication in your .NET desktop application as well as in your mobile application based on Xamarin and MAUI. The SDK provides multiple packages depending on the framework used for your application's UI:

- [**Auth0.OidcClient.UWP**](https://www.nuget.org/packages/Auth0.OidcClient.UWP). This package supports Universal Windows Platform (UWP). Check out [this document to learn how to use it](https://auth0.com/docs/quickstart/native/windows-uwp-csharp).
- [**Auth0.OidcClient.WPF**](https://www.nuget.org/packages/Auth0.OidcClient.WPF). This package supports authentication for desktop apps using Windows Presentation Foundation (WPF). Take a look at [this document to learn how to use this package](https://auth0.com/docs/quickstart/native/wpf-winforms).
- [**Auth0.OidcClient.WinForms**](https://www.nuget.org/packages/Auth0.OidcClient.WinForms). With this package, you can add authentication to your WinForms-based desktop application. [This document](https://auth0.com/docs/quickstart/native/wpf-winforms) will guide you on how to use it.
- [**Auth0.OidcClient.Android**](https://www.nuget.org/packages/Auth0.OidcClient.Android). This package adds authentication to Xamarin-based mobile apps for Android. Read [this document](https://auth0.com/docs/quickstart/native/xamarin) to learn how to start.
- [**Auth0.OidcClient.iOS**](https://www.nuget.org/packages/Auth0.OidcClient.iOS). This package adds authentication to Xamarin-based mobile apps for iOS. Check out [this document](https://auth0.com/docs/quickstart/native/xamarin) to learn how to use it.
- [**Auth0.OidcClient.MAUI**](https://www.nuget.org/packages/Auth0.OidcClient.MAUI). With this package, you can add authentication to your MAUI applications. Get started with [this document](https://auth0.com/docs/quickstart/native/maui).

### Auth0 .NET SDK

The [Auth0 .NET SDK](https://github.com/auth0/auth0.net) enables your .NET Framework and .NET Standard application to authenticate users and manage your Auth0 tenant. It implements two packages:

- [**Auth0.AuthenticationApi**](https://www.nuget.org/packages/Auth0.AuthenticationApi). This package is a wrapper around the [Auth0 Authentication API](https://auth0.com/docs/api/authentication), which allows you to add login, logout, signup, and other functionality to your application. This is not a high-level authentication library, since you need to handle the steps of the [authentication and authorization process](https://auth0.com/docs/get-started/authentication-and-authorization-flow). It assists you in building authorization URLs through a few [URL Builders](https://auth0.github.io/auth0.net/#using-url-builders), but it's up to you to [run validation](https://github.com/auth0/auth0.net#authentication).
  Check out [this document for an introduction to how to use the *Auth0.AuthenticationApi* package](https://auth0.github.io/auth0.net/#using-the-authentication-api).
- [**Auth0.ManagementApi**](https://www.nuget.org/packages/Auth0.ManagementApi). This package allows you to interact with your Auth0 tenant programmatically. It is a wrapper around the [Auth0 Management API](https://auth0.com/docs/api/management/v2) and basically allows you to do with your .NET application what you can do with your [Auth0 dashboard](https://manage.auth0.com/): you can manage users and roles, create and get application settings, manage your Auth0 Actions, control your branding, and so on.
  Check out [this document for a quick introduction to how to use the *Auth0.ManagementApi* package](https://auth0.github.io/auth0.net/#using-the-management-api).

<include src="ebook-ads/dotnetIdentity" />

## The Matrix of Solutions

Now that you've reviewed the dimensions of the problem and the available Auth0 packages let's create a map that allows you to find on the fly which package to use for a given application type.
In the following, you will see three sections, one for each Auth0 role in your application. Within each section, you will find a matrix that matches the application type with the .NET target and proposes the appropriate package.
Note that a specific SDK may not be available for some combinations because native .NET support is sufficient or because there are viable third-party alternatives.

### Authentication

If your application uses Auth0 to add authentication support, check out this matrix to choose the right package:

<style>
  table {
    width: 100%;
    border-collapse: collapse;
    font-size: 15px;
  }
  table, td, th {
    border: 1px solid;
  }
  table th {
    background-color:#eeeee4;
  }
  table tr td:first-child {
    background-color:#eeeee4;
  }
  table a:link {
    inline-size: 250px;
    /* overflow-wrap: break-word; */
    word-break: break-all;
    font-size: 15px;
  }
  td {
    padding: 5px;
  }
</style>

| | .NET Framework | .NET (Core)|
| ------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| **ASP.NET MVC** | [Microsoft.Owin.Security.OpenIdConnect](https://www.nuget.org/packages/Microsoft.Owin.Security.OpenIdConnect) | |
| **ASP.NET Core MVC** | | [Auth0.AspNetCore.Authentication](https://www.nuget.org/packages/Auth0.AspNetCore.Authentication) |
| **Razor Pages** | | [Auth0.AspNetCore.Authentication](https://www.nuget.org/packages/Auth0.AspNetCore.Authentication) |
| **Blazor Server**<br/>**Blazor WebApps** | | [Auth0.AspNetCore.Authentication](https://www.nuget.org/packages/Auth0.AspNetCore.Authentication) |
| **Blazor WebAssembly** | | [Microsoft.AspNetCore.Components.WebAssembly.Authentication](https://www.nuget.org/packages/Microsoft.AspNetCore.Components.WebAssembly.Authentication/) |
| **Xamarin** | [Auth0.OidcClient.Android](https://www.nuget.org/packages/Auth0.OidcClient.Android)<br />[Auth0.OidcClient.iOS](https://www.nuget.org/packages/Auth0.OidcClient.iOS) | [Auth0.OidcClient.Android](https://www.nuget.org/packages/Auth0.OidcClient.Android)<br />[Auth0.OidcClient.iOS](https://www.nuget.org/packages/Auth0.OidcClient.iOS) |
| **WPF** | [Auth0.OidcClient.WPF](https://www.nuget.org/packages/Auth0.OidcClient.WPF) | |
| **WinForms** | [Auth0.OidcClient.WinForms](https://www.nuget.org/packages/Auth0.OidcClient.WinForms) | |
| **UWP** | [Auth0.OidcClient.UWP](https://www.nuget.org/packages/Auth0.OidcClient.UWP) | |
| **MAUI** | | [Auth0.OidcClient.MAUI](https://www.nuget.org/packages/Auth0.OidcClient.MAUI) |
| **Console** | [Auth0.AuthenticationApi](https://www.nuget.org/packages/Auth0.AuthenticationApi) | [Auth0.AuthenticationApi](https://www.nuget.org/packages/Auth0.AuthenticationApi) |

<br/>

Notice that for ASP.NET MVC, we suggest using [Microsoft's standard OWIN library](https://learn.microsoft.com/en-us/aspnet/aspnet/overview/owin-and-katana/). Similarly, you can use [Microsoft's standard library for Bazor WebAssembly applications](https://www.nuget.org/packages/Microsoft.AspNetCore.Components.WebAssembly.Authentication/).

### Access control

If your application uses Auth0 to check access control to server resources, that is, you are implementing a Web API, check out this matrix to choose the right package:

| | .NET Framework | .NET (Core) |
| -------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| **ASP.NET Web API** | [Microsoft.Owin.Security.Jwt](https://www.nuget.org/packages/Microsoft.Owin.Security.Jwt) | |
| **ASP.NET Core Web API** | | [Microsoft.AspNetCore.Authentication.JwtBearer](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.JwtBearer) |

<br/>

As you can see, you can use Microsoft's standard libraries to check JWT tokens in Web APIs.

### Auth0 tenant management

If your application needs to manage users and other Auth0 tenant features, refer to this table:

| | .NET Framework | .NET (Core) |
| ------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| **Any app type** | [Auth0.ManagementApi](https://www.nuget.org/packages/Auth0.ManagementApi) | [Auth0.ManagementApi](https://www.nuget.org/packages/Auth0.ManagementApi) |

<br/>

The Auth0 Management API can be used for any application type targeting any .NET version.

<include src="SignupCTA" text="Try out Auth0 authentication for free." linkText="Get started →" />

## Summary

Throughout this article, you learned the criteria you must follow to determine the appropriate SDK and package for your .NET application. The current platform complexity is reflected in the complexity of choosing the right package, of course. With the [.NET platform unification](https://auth0.com/blog/dotnet-5-whats-new/), general simplification is expected in the near future, but we cannot forget the legacy code that is still up and running.

So, for your next .NET project, go and pick the right Auth0 SDK!


Choosing the Right .NET SDK for Auth0

Learn why and how to use refresh tokens in ASP.NET Core applications.

Use Refresh Tokens in ASP.NET Core Apps

Learn the right way to call a protected API using an access token in ASP.NET Core applications.

Call Protected APIs in ASP.NET Core

How to force your ASP.NET Core application to use only HTTPS? Learn the best practices for different scenarios.

HTTPS is mandatory to grant security to your web application, regardless of the programming framework you are using. But what happens if a client calls your web app with HTTP instead of HTTPS? How can you force it to use HTTPS? Let's delve into the options provided by ASP.NET Core.

## Use HTTPS Redirection

I guess that the first idea that comes to your mind is to redirect HTTP requests: if a client calls your application using HTTP, your application redirects it to the same URL starting with HTTPS. [URL redirection](https://developer.mozilla.org/en-US/docs/Web/HTTP/Redirections) is a well-known approach. The web application creates an HTTP response with a status code starting with `3` and a `Location` header like in the following example:

```
HTTP/1.1 301 Moved Permanently
Location: https://www.auth0.com/
```

While this approach doesn't resolve all the security risks, as you will learn along the way, it's a good starting point.

Fortunately, in ASP.NET Core, you don't need to go to the HTTP level to redirect your client's requests. You have a few options to choose from. Let's analyze each of them.

### The `RequireHttps` attribute

The first approach we'll explore is based on the `RequireHttps` attribute. You can use it in your Razor Pages applications to force a page to require HTTPS, as shown in the following code snippet:

```csharp
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;

namespace RazorApp.Pages;

[RequireHttps]
public class PrivacyModel : PageModel
{
  //...existing code...
}
```

If this page is called through HTTP, an HTTPS redirection response will be automatically created for you. For Razor Pages, you can apply the `RequireHttps` attribute only to classes inheriting from `PageModel`. You cannot apply the attribute to the class methods as well.

In ASP.NET Core MVC applications, you can apply the `RequireHttps` attribute to classes inherited from `Controller`, as in the following example:

```csharp
using System.Diagnostics;
using Microsoft.AspNetCore.Mvc;
using MvcApp.Models;

namespace MvcApp.Controllers;

[RequireHttps]
public class HomeController : Controller
{
  // ...existing code...
}
```

When the attribute is attached to the controller, the HTTP redirection is applied to any view returned by it. However, in the ASP.NET Core MVC case, you can apply the `RequireHttps` attribute to specific views. For example, the following code shows how to require HTTPS redirection only for the *Privacy* view:

```csharp
using System.Diagnostics;
using Microsoft.AspNetCore.Mvc;
using MvcApp.Models;

namespace MvcApp.Controllers;

public class HomeController : Controller
{
    public IActionResult Index()
    {
        return View();
    }

    [RequireHttps]
    public IActionResult Privacy()
    {
        return View();
    }
}
```

The redirection approach based on the `RequireHttps` attribute is pretty simple. You may also think that the opportunity to apply it selectively to specific pages or views is great because you can limit HTTPS to just pages with confidential content.

Actually, **mixing HTTP and HTTPS pages is a really bad idea!** Your web application is not secure because it is exposed to [HTTPS downgrade attacks](https://auth0.com/blog/preventing-https-downgrade-attacks/). To mitigate this risk, make all your web application's pages accessible only with the HTTPS protocol.

You may think of applying the `RequireHttps` attribute to all the pages to reduce the risk, but there are better approaches, as you will see in the next section.

### The HTTPS redirection middleware

When you create a web application using one of the standard ASP.NET project templates, the `Program.cs` file contains the method invocation highlighted in the following code snippet:

```csharp
// Program.cs

var builder = WebApplication.CreateBuilder(args);

// ...existing code...

var app = builder.Build();

// ...existing code...

app.UseHttpsRedirection();  //👈 HTTPS redirection
app.UseStaticFiles();

app.UseRouting();

// ...existing code...
```

The `UseHttpsRedirection()` method invocation enables the HTTPS redirection middleware. This means that each request to your application will be inspected and possibly redirected by the middleware. You don't need to look for pages missing the `RequireHttps` attribute. All the pages of your application will require HTTPS. If a client requests a page with HTTP, it will be automatically redirected to the corresponding HTTPS-based URL.

### Enable the HSTS middleware

The approach based on `UseHttpsRedirection()` looks awesome! With just one statement in your `Program.cs` file, your entire web application is forced to be called with the HTTPS protocol.

Unfortunately, while this approach is better than having mixed pages, there are still some potential security issues with your application. Forcing a client to switch from HTTP to HTTPS on each request might not be enough to [prevent HTTPS downgrade attacks](https://auth0.com/blog/preventing-https-downgrade-attacks). The attacker could intercept the client's HTTP request before it switches to the corresponding HTTPS request.

You need a way to tell the browser to mandatorily use HTTPS to request **any** resource of your web application. This way exists: the HTTP `Strict-Transport-Security` header (HSTS). Using HSTS, the browser will call your application using HTTP only the very first time. The subsequent requests against the same domain will be made using the HTTPS protocol, even in the presence of a URL using the HTTP scheme. To have [more details about HSTS, check out here](https://auth0.com/blog/preventing-https-downgrade-attacks/#Using-HSTS).

To enable HSTS in your ASP.NET Core application, you just need to invoke the `UseHsts()` method in your `Program.cs` file as shown below:

```csharp
// Program.cs

var builder = WebApplication.CreateBuilder(args);

// ...existing code...

var app = builder.Build();

// ...existing code...

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();    //👈 Enable HSTS middleware
}

// ...existing code...
```

By invoking the `UseHsts()` method, you enable the HSTS middleware. You have this code already in your application when you build it by starting from a standard ASP.NET Core template.

### Using HSTS in the development environment

From the code above, you may notice that the HSTS support is enabled only if your application is not running in your development environment. There is a practical reason behind this choice.

Chances are that you use *localhost* as your development environment domain. If you use HSTS in your development environment, any request made by your browser to *localhost* will use HTTPS. Actually, [using HTTPS in your development environment is a good practice](https://auth0.com/blog/using-https-in-your-development-environment/). But suppose your ASP.NET Core application enables HSTS. In that case, it causes your browser to make HTTPS requests to **any application** hosted on *localhost*, not just your ASP.NET Core application and not just ASP.NET Core applications in general. This may lead to headaches in case you have, say, an Angular application that doesn't use HTTPS and stops working overnight.

> HSTS settings include an expiration time, which by default is 30 days for ASP.NET Core applications. To change this and other settings, check out the [official documentation](https://docs.microsoft.com/en-us/aspnet/core/security/enforcing-ssl#http-strict-transport-security-protocol-hsts).

<include src="ebook-ads/WebSecurity" />

## HTTPS Redirection and APIs

At this point, we can feel happy with the HTTPS security of our ASP.NET Core application, right? Well, not really. Actually, it depends on the type of web application.

The HTTPS redirection approach relies on sending back to the client a `301` or another `30*` HTTP status code, regardless you are using the `RequireHttps` attribute or the HTTPS redirection middleware. The HSTS approach relies on sending the `Strict-Transport-Security` header.

Both approaches are well-understood by standard browsers. So, application types whose clients are browsers, such as ASP.NET Core MVC applications, Razor Pages applications, and Blazor Server applications, can rely on these approaches.

However, those approaches are usually ignored by non-browser clients, such as API clients. It's extremely rare for a mobile app or a SPA to take care of `301` status codes or HSTS headers. In this case, you have two alternative ways to deal with clients that make HTTP requests:

- Ignore HTTP requests.
- Respond with a `400 Bad Request` status code.

### Ignore HTTP requests

The first option can be done in different ways. One of the easiest ways is to use the `--urls` flag of the `dotnet run` command, as shown below:

```bash
dotnet run --urls "https://localhost:7123"
```

This approach allows you to override the URL settings configured in the `Properties/launchSettings.json` file of your ASP.NET Core project.

A more production-oriented approach to override those settings uses the `ASPNETCORE_URLS` environment variable. The following shows how to set this variable in PowerShell:

```powershell
$Env: ASPNETCORE_URLS = "https://localhost:7123"
```

This is an example in a bash shell:

```bash
export ASPNETCORE_URLS="https://localhost:7123"
```

Check out [this article](https://andrewlock.net/5-ways-to-set-the-urls-for-an-aspnetcore-app/) to learn other ways to override the current listening URLs in ASP.NET Core.

### Treat HTTP requests as bad requests

To implement the *Bad Request* approach, you need to create a custom middleware and use it instead of HTTPS redirection and HSTS middleware. The following example shows a simple version of such a middleware:

```csharp
// Program.cs

var builder = WebApplication.CreateBuilder(args);

// ...existing code...

var app = builder.Build();

// ...existing code...

// 👇 new code
//app.UseHttpsRedirection();
app.Use(async (context, next) => {
    if (!context.Request.IsHttps) {
        context.Response.StatusCode = StatusCodes.Status400BadRequest;
        await context.Response.WriteAsync("HTTPS required!");
    } else {
        await next(context);
    }
});
/ 👆 new code
  
app.UseStaticFiles();

app.UseRouting();

// ...existing code...
```

The highlighted code shows that the existing `UseHttpsRedirection()` method invocation is replaced by the custom middleware. The middleware's code just checks if the current request uses HTTPS. If this is not the case, it replies with a `400 Bad Request` status code and a message warning that HTTPS is required.

<include src="SignupCTA" text="Try out Auth0 authentication for free." linkText="Get started →" />

## HTTPS Redirection and Reverse Proxies

All the above makes sense if your ASP.NET Core application is directly exposed to the Internet. If your application is deployed in an environment with a reverse proxy that handles connection security, there is no need to use HTTPS redirection or HSTS middleware.

In this case, you can simply remove the `UseHttpsRedirection()` and the `UseHsts()` method calls from your ASP.NET Core applications. The same applies to ASP.NET Core Web API application as well: you don't need to create a custom middleware to deny HTTP requests. You delegate HTTP to HTTPS switching and control to the reverse proxy.

## Summary

This article guided you through the different approaches to force a client to use HTTPS when it calls an ASP.NET Core application. You started from the simple  `RequireHttps` attribute, which redirects to HTTPS-based requests on a page-by-page basis. You then explored the `UseHttpsRedirection()` method, which allows you to apply HTTPS redirection to all your application's pages.

You learned that redirecting from HTTP to HTTPS at each page request doesn't guarantee you are not exposed to HTTPS downgrade risks. You took a further step in mitigating this risk by learning about HSTS and the `UseHsts()` method.

You also learned that HTTPS redirection and HSTS are great approaches for regular web applications, such as ASP.NET Core MVC, Razor, and Blazor applications, but they are not suitable for APIs. In this case, you need to ignore HTTP requests or mark them as bad requests.

Finally, you only need to apply all these measures if your deployment environment doesn't take care of protocol switching and control. For example, if your application runs behind a reverse proxy, you can delegate all these checks to it.


Force HTTPS in ASP.NET Core Apps

Learn how to secure Blazor WebAssembly applications with Auth0.

Securing Blazor WebAssembly Apps

Learn how to build client-side Web apps using Blazor and how to secure them with Auth0.

What is Blazor? A Tutorial on Building Web Apps with Authentication

Learn what Dependency Injection and IoC are and what .NET Core provides you to support them.

Understanding Dependency Injection in .NET Core

Learn how to add authentication and authorization to gRPC for microservices in .NET Core.

Securing gRPC-based Microservices in .NET Core

Learn how to build efficient microservices in .NET Core 3.1 by leveraging gRPC.

"aspnet-core"