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 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

pablo-cibraro

Pablo is an internationally recognized expert and entrepreneur with more than 22 years of experience in designing and implementing large distributed systems with Microsoft technologies and a Connected System MVP. 
For the last few years, Pablo has helped numerous Microsoft teams develop tools and frameworks for building service-oriented and web applications with .NET. 
Pablo now focuses on technologies that enable developers to build large-scale systems and web applications on the cloud, such as HTML5, Node.js, ASP.NET, Windows Azure and Amazon AWS.

Agilesight Cofounder

Pablo Cibraro

Learn about the new ASP.NET minimal Web APIs introduced in .NET 6.0 and how to secure them with Auth0.

Securing ASP.NET Minimal Web APIs with Auth0

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** **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) [Auth0.OidcClient.iOS](https://www.nuget.org/packages/Auth0.OidcClient.iOS) | [Auth0.OidcClient.Android](https://www.nuget.org/packages/Auth0.OidcClient.Android) [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) |

 

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) |

 

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) |

 

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

What is the best way to apply Role-Based Access Control (RBAC) to your ASP.NET Web API? Let's find out together.

Role-Based Authorization for ASP.NET Web APIs

joydip-kanjilal

I received the Microsoft MVP award in ASP.NET for six consecutive years from 2007 to 2012. I'm a software architect, author, and speaker. I've more than 25 years of experience in the software industry, with more than 18 years in Microsoft .NET and its related technologies. These days I'm exploring AI and Machine Learning.

Software Architect and Advisor

Joydip Kanjilal

Learn what an API Gateway is and how to build yours in ASP.NET Core by using Ocelot.

Implementing an API Gateway in ASP.NET Core with Ocelot

Learn about the new features introduced by the .NET Core 3.0 release.

Exploring .NET Core 3.0. What's New?

An overall view of .NET, Microsoft's cross-platform development environment that allows you to build any type of application with C# and other languages.

Microsoft's ambition to provide developers with one platform to solve any type of problem has been fulfilled by .NET. For a couple of decades already, the .NET platform has been powering up web, desktop, and mobile applications in both the startup and enterprise scenes.

Without any doubt, .NET plays a central role in the software development industry. .NET popularity in the developer community is a fact. You can measure it through the number of open source projects around the world and the presence of [C# among the five most popular programming languages](https://www.tiobe.com/tiobe-index/). Its popularity is going to grow even more, especially after [the latest release (.NET 5)](https://auth0.com/blog/dotnet-5-whats-new/), which revolutionizes the industry by pioneering the concept of universal software development.

To understand the power of .NET, let's explore some of its technical foundations.

## What is .NET?

.NET is an open-source and cross-platform development platform for building many types of applications. Designed by Microsoft, the platform supports multiple programming languages and libraries to build web, mobile, desktop, IoT applications, and more.

![.NET 5 platform](https://images.ctfassets.net/23aumh6u8s0i/2bsVrNvzMOk64yfFw0ZU3O/b88d3412d42844d54011f31d69d5860f/dotnet5_platform)

<a href="https://devblogs.microsoft.com/dotnet/introducing-net-5/">[Source: Microsoft]</a>

Even if C# is considered the main programming language for .NET, you can use many other different languages of your choice. The languages directly supported by Microsoft are:

- [C# (C sharp)](https://docs.microsoft.com/en-us/dotnet/csharp/): A modern object-oriented programming language that belongs to the C language family. Its syntax may look familiar to C, C++, Java, and JavaScript developers.

- [F# (F sharp)](https://dotnet.microsoft.com/languages/fsharp): A functional-oriented programming language, member of the [ML](https://en.wikipedia.org/wiki/ML_(programming_language%29) language family. It also supports the object-oriented programming paradigm.

- [Visual Basic](https://docs.microsoft.com/en-us/dotnet/visual-basic/): The historical Microsoft programming language. It has become a full object-oriented programming language within the context of .NET.

.NET supports the [*Common Language Infrastructure*](https://en.wikipedia.org/wiki/Common_Language_Infrastructure) (CLI), so your source code is compiled into a [*Common Intermediate Language*](https://en.wikipedia.org/wiki/Common_Intermediate_Language) (CIL), independently of the programming language you use. This guarantees great interoperability between languages in the platform.

Besides the above mentioned languages supported directly by Microsoft, many other programming languages can compile to the .NET CIL. For example, ClojureCLR, Eiffel, IronPython, PowerBuilder, and many others. For a complete list, check out [this page](https://en.wikipedia.org/wiki/List_of_CLI_languages).

## .NET Architecture and Components

.NET allows you to build different application types, ranging from command-line to desktop applications, from web to mobile applications, from gaming to IoT applications.

This is possible thanks to its modular and optimized architecture.

### .NET Components

The .NET architecture is based on two main components:

- *CoreCLR*: This is the .NET runtime. It is responsible for executing CLI programs and includes a just-in-time compiler.

- *CoreFX*: The platform’s API implementing the CLI Standard Libraries, that is, the set of libraries that provide the most common functionalities, such as file system management, exception handling, network communication, threading, reflection, and so on. The CoreFX component is sometimes called the *Unified Base Class Library*.

### .NET Application Models

Above the core components, you have the different **application model frameworks**, that is, the libraries that offer support for developing different types of applications. So, for example, you have:

- [ASP.NET](https://dotnet.microsoft.com/apps/aspnet): The framework that allows you to build [web applications](https://auth0.com/docs/quickstart/webapp/aspnet-core-3) and [web APIs](https://auth0.com/blog/how-to-build-and-secure-web-apis-with-aspnet-core-3/).

- [Windows Presentation Foundation (WPF)](https://docs.microsoft.com/en-us/dotnet/desktop/wpf/?view=netdesktop-5.0): A graphical user interface for [Windows desktop applications](https://auth0.com/docs/quickstart/native/wpf-winforms).

- [Xamarin](https://auth0.com/blog/easy-authentication-xamarin-auth0/): The framework for building cross-platform mobile, TV, and desktop applications.

- [Blazor](https://auth0.com/blog/what-is-blazor-tutorial-on-building-webapp-with-authentication/): The framework to build client web applications by using C#. It also allows you to generate [client web apps in WebAssembly code](https://auth0.com/blog/securing-blazor-webassembly-apps/).

- [ML.NET](https://dotnet.microsoft.com/apps/machinelearning-ai): The machine learning framework that simplifies the integration of machine learning models in your .NET application.

In addition to application model frameworks, .NET offers you support for most of the common programming tasks: from file management to network communication, from security to database access. For example, on the networking side, it supports socket programming, HTTP communication, and [gRPC](https://auth0.com/blog/securing-grpc-microservices-dotnet-core/). This allows you to [create microservices](https://auth0.com/blog/implementing-microservices-grpc-dotnet-core-3/) with the protocol that better fits your needs.

For any other needs not embedded in the framework, you can find a huge number of specific libraries on the public [NuGet repository](https://www.nuget.org/). In fact, [NuGet](https://docs.microsoft.com/en-us/nuget/) is the package manager for .NET. It allows you to create, share, and use many .NET libraries for almost any purpose.

## .NET Design and Development Support

.NET support for software development is not limited to the multiple programming languages you can use. .NET also promotes the use of some best practices while letting you use the approach you prefer to build your application.

For example, it encourages you to [use dependency injection to decouple your application’s components](https://auth0.com/blog/dependency-injection-in-dotnet-core/). Dependency injection helps you design better software by limiting the component interdependence and facilitating reuse. In addition, it makes it easier to test your components.

By the way, on the testing side, .NET also comes with support for [unit and integration tests via xUnit](https://auth0.com/blog/xunit-to-test-csharp-code/).

On the front of the development experience, developers can choose from different approaches. They can use the [.NET CLI ](https://docs.microsoft.com/en-us/dotnet/core/tools/)environment, using the command line to create new projects, adding dependencies, build, run, and so on.

They can use [Visual Studio Code](https://code.visualstudio.com/) for an intermediate approach: an advanced cross-platform editor on top of the .NET CLI. Or they can use a powerful IDE like [Visual Studio](https://visualstudio.microsoft.com/vs/), available for both Windows and Mac, that provides you an interactive programming experience.

Regardless of the tool you choose, you can use many project templates to quickly start creating your new application. You can also [create your own .NET project template](https://auth0.com/blog/create-dotnet-project-template/).

## From the .NET Framework to the .NET Platform

Microsoft launched the .NET project in 2002. Since the beginning, the .NET goal was to create a universal platform for programming with any language. Of course, as the first step, Windows was the main .NET target.

However, Microsoft submitted the specifications of the .NET runtime infrastructure and the C# programming language to [ECMA](https://www.ecma-international.org/) for standardization. This led to the birth of a few porting projects on other platforms: Linux, embedded systems, mobile devices, browsers, and so on.

This also led to a fragmentation of the platform and sometimes generated confusion among developers. Take a look at [this article to learn more about the evolution of .NET](https://auth0.com/blog/navigating-dotnet-maze/).

Let’s try to clarify the differences among a few common concepts.

### .NET Framework

The .NET Framework was the initial flavor of .NET. It provides the developer with a set of APIs for the most common programming needs and interacts with the underlying operating system. It runs only on Windows, and its lifecycle is coming to an the end right now, after [the release of .NET 5](https://auth0.com/blog/dotnet-5-whats-new/).

### Mono

The Mono project brings .NET to Linux machines. It is the best known porting project based on the .NET standard specifications. Even if Mono's aim is to run on Linux applications built for the .NET Framework and vice versa, the compatibility is not always guaranteed. There are a couple of reasons for this: some .NET Framework features are too tied to the Windows operating system, and often the Mono implementation lags behind the newest .NET Framework features.

### .NET Core

.NET Core is a complete rewriting of the .NET Framework with the cross-platform goal in mind. Its redesigned architecture defines a minimal feature set as the common core across Windows, Linux, and Mac platforms. The rest of the features can be downloaded as library packages.

### .NET Standard

The .NET Standard is not another .NET implementation. It is a formal specification of .NET APIs that helps to create cross-platform libraries. If a platform supports a given .NET Standard version, then a library supporting the same version will run on it, regardless of the device type and the framework implementation (.NET Framework, Mono, .NET Core).

### .NET

Since the beginning, the .NET term has been used to indicate the universal development platform. However, many implementations arose since then, so the .NET name created ambiguities. .NET 5 aims to make concrete the initial vision of a universal development platform. It replaces the current existing implementations: .NET Framework, .NET Core, and even Mono. So, from .NET 5 on, only .NET will exist as a name and as a platform.

## Auth0 and .NET

Auth0 has extensive support for .NET that allows you to easily integrate modern authentication and authorization into your .NET applications: from specific SDKs to documentation, from blog posts to sample projects. In this section, you find a list of the .NET resources that Auth0 provides you.

### .NET QuickStarts

Auth0 Quickstarts help you in setting up your first [authentication](https://auth0.com/docs/authentication) and [authorization](https://auth0.com/docs/authorization) integration. They guide you in adding the needed code and the required configuration step by step. If you are logged in, the code snippets are configured for your account. If you don't have an account, you <a href="https://auth0.com/signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">can sign up for free with Auth0</a>.

The following .NET-related Quickstarts are available:

- [**ASP.NET Core Web API v3.1**](https://auth0.com/docs/quickstart/backend/aspnet-core-webapi): This Quickstart helps you to add authorization to an ASP.NET Core Web API using the standard [JWT](https://jwt.io/) middleware.
- [**ASP.NET Core v3.1 Web Application**](https://auth0.com/docs/quickstart/webapp/aspnet-core-3): This Quickstart demonstrates how to add user login to an ASP.NET Core Web Application.
- [**WPF/Windows Forms (WinForms**)](https://auth0.com/docs/quickstart/native/wpf-winforms): The Quickstart guides you in adding user login Windows desktop C# applications.
- [**Xamarin**](https://auth0.com/docs/quickstart/native/xamarin): This Quickstart helps you add user login to Xamarin applications.
- [**Windows Universal App**](https://auth0.com/docs/quickstart/native/windows-uwp-csharp): Reading this Quickstart, you will learn how to add user login to [Windows Universal](https://docs.microsoft.com/en-us/windows/uwp/get-started/universal-application-platform-guide) C# applications.

### Software Development Kits (SDKs)

Auth0 provides you the following SDKs to help you to integrate authentication and authorization in your .NET applications:

- [**.NET Client Library for Auth0**](https://github.com/auth0/auth0.net): This SDK supports two APIs:
 - *The Authentication API*: This API allows you to add [OIDC](https://auth0.com/docs/protocols/openid-connect-protocol)-based authentication to your application
 - *The Management API*: This API allows you to interact with the [Auth0 Management API](https://auth0.com/docs/api/management/v2) and deal with your [Auth0 tenant](https://auth0.com/docs/videos/get-started-series/architect-your-tenant).
- [**Auth0 OIDC Client for .NET** ](https://github.com/auth0/auth0-oidc-client-net): This library supports [OIDC authentication](https://auth0.com/docs/protocols/openid-connect-protocol) for .NET desktop applications based on WinForms, WPF, and UWP as well as Xamarin mobile applications.

### .NET blog posts

In addition to SDKs and Quickstarts, Auth0 provides you with specific content, use cases, and code examples through its [developer blog](https://auth0.com/blog/developers/). You can find [many .NET-related articles](https://auth0.com/blog/search/?query=.net) that help you build and secure your applications and keep up to date with the most recent features. Most articles include a sample project to demonstrate how to practically implement your apps. You can download them from GitHub, <a href="https://auth0.com/signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">sign up with Auth0</a> if needed, configure the app, run it, and explore the code.

So, enjoy building your next .NET project with Auth0!

What is .NET? An Overview of the Platform

Learn how to secure an ASP.NET Core Web API by granting access only to authorized users through Auth0 authentication and authorization services.

Having control over who can access your API is a necessary requirement to make your application secure. This article will show you how to restrict access to your ASP.NET Core Web API to authorized users only.

## Setting up the Web API Application

Let's start by setting up the ASP.NET Core Web API application to be protected. You can download a glossary Web API from [this GitHub repository](https://github.com/auth0-blog/glossary-web-api-aspnet/tree/starter) by running the following command in a terminal window:

```bash
git clone --branch starter --single-branch https://github.com/auth0-blog/glossary-web-api-aspnet.git

```

This ASP.NET application provides you with a CRUD Web API to manage a glossary of terms. You can learn the details of its implementation by reading [this article](https://auth0.com/blog/building-aspnet-web-api).

Once you download the application, move to the `glossary-web-api-aspnet` folder and launch it by typing `dotnet run` in a terminal window. By pointing your browser to `https://localhost:5001/swagger`, you should see a page like the following to interactively test the APIs:

![Swagger UI for Web API](https://images.ctfassets.net/23aumh6u8s0i/39X3FZbdleAybhhvH5hCV7/b0276f9319a0a8110fcffc1dd583f602/webapi-swagger-ui.png)

The Web API application allows you to get a list of term definitions or a single term definition. It also lets you create a new definition and modify or delete an existing one.

The current implementation of this glossary Web API allows anyone to perform all the available operations on the glossary. Most probably, you want to allow everyone to get a single glossary item or the full glossary. Still, only authorized users should be enabled to create, update, and delete glossary items.

Let's go and see how to protect these three actions by integrating your ASP.NET Core Web API with [Auth0](https://auth0.com) services.

## Registering the Web API with Auth0

To start securing your API with Auth0, you need an Auth0 account. If you haven't got one, 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</a>. Now, you can register your Web API through the [Auth0 Dashboard](https://manage.auth0.com/). Move to the [API section of the Dashboard](https://manage.auth0.com/#/apis) and follow these steps:

1. Click on *Create API*
2. Provide a friendly name for your API (for example, *Glossary API*) and a unique identifier in the URL format (for example, *https://glossary.com*)
3. Leave the signing algorithm as RS256 and click the *Create* button

These steps make Auth0 aware of your Web API and will allow you to control access.

> **Note**: While you are in the Auth0 Dashboard, take note of your Auth0 domain. You will need it soon. This is a string in the form `YOUR-TENANT-NAME.auth0.com` where `YOUR-TENANT-NAME` is the name you provided when you created your account with Auth0. For more information, [check the documentation](https://auth0.com/docs/getting-started/the-basics#domains).

<details>
 <summary>Using the Auth0 CLI</summary>
As an alternative to the Dashboard, you can use [the Auth0 CLI](https://auth0.com/blog/introducing-auth0-cli/) to register your API with Auth0.


In this case, [install the CLI on your machine](https://github.com/auth0/auth0-cli#installation) and [configure it to access your Auth0 tenant](https://github.com/auth0/auth0-cli#login). Then, run the following command in a terminal window:

```bash
auth0 apis create --name "Glossary API" --identifier https://glossary.com --scopes ""
```

This command creates an entry for your API with the name *Glossary API* and the unique identifier `https://glossary.com`. You are not specifying any [scope](https://auth0.com/docs/scopes) for this application right now.

Running this command has exactly the same effect as registering your API through the Auth0 Dashboard.

After the registration, you will get an output like the following:

```bash
=== <YOUR_AUTH0_DOMAIN> API created

 ID 60ac3b89f0cd4a003d42e850 
 NAME Glossary API 
 IDENTIFIER https://glossary.com 
 SCOPES 
```

Take note of the values for the `<YOUR_AUTH0_DOMAIN>` placeholder and the identifier.
</details>

## Enabling Authorization Support

The next step is to adapt the ASP.NET Core Web API application's code to use Auth0 authorization services.

### Configuring the Web API

Back in your ASP.NET application, open the `appsettings.json` configuration file and replace its content with the following:

```json
{
 "Logging": {
 "LogLevel": {
 "Default": "Information",
 "Microsoft": "Warning",
 "Microsoft.Hosting.Lifetime": "Information"
 }
 },
 "AllowedHosts": "*",
 "Auth0": {
 "Domain": "YOUR_AUTH0_DOMAIN",
 "Audience": "YOUR_UNIQUE_IDENTIFIER"
 }
}
```

Replace the `YOUR_AUTH0_DOMAIN` placeholder with your Auth0 domain and the `YOUR_UNIQUE_IDENTIFIER` placeholder with the value you provided as a unique identifier of your API (`https://glossary.com`, if you kept the value suggested above).

### Integrating with Auth0

In order to interact with the Auth0 authorization services, your application needs to be able to handle tokens in the [JWT](https://jwt.io/) (*JSON Web Token*) format. You can accomplish this by installing the `Microsoft.AspNetCore.Authentication.JwtBearer` library. Move to your application folder and type the following command in a terminal window:

```bash
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer
```

When the installation is complete, open the `Startup.cs` file and add the `JwtBearer` namespace. The `using` section of the file should look as shown below:

```c#
//Startup.cs
...existing code... 
using Microsoft.OpenApi.Models;
using Microsoft.AspNetCore.Authentication.JwtBearer; //👈 new code

namespace Glossary
{
 //...existing code...
}
```

In the same file, replace the `ConfigureServices()` method of the `Startup` class with the following code:

```c#
//Startup.cs

// ...existing code...
 public void ConfigureServices(IServiceCollection services)
 {
 //👇 new code
 services.AddAuthentication(options =>
 {
 options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
 options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
 }).AddJwtBearer(options =>
 {
 options.Authority = $"https://{Configuration["Auth0:Domain"]}/";
 options.TokenValidationParameters = 
 new Microsoft.IdentityModel.Tokens.TokenValidationParameters
 {
 ValidAudience = Configuration["Auth0:Audience"],
 ValidIssuer = $"{Configuration["Auth0:Domain"]}",
 ValidateLifetime = true,
 };
 });
 //👆 new code

 services.AddControllers();
 services.AddSwaggerGen(c =>
 {
 c.SwaggerDoc("v1", new OpenApiInfo { Title = "Glossary", Version = "v1" });
 });
 }
// ...existing code...
```

You added the authentication service by specifying the JWT bearer scheme. You also configured the JWT handler by using the domain and audience values from the `appsettings.json` configuration file. In particular, you built the authority URL based on the Auth0 domain and set the parameters that allow the access token to be validated. Specifically, a token is considered valid if it meets the following criteria:

- it has the expected audience,
- it was issued by the expected domain,
- it is not expired.

Finally, replace the `Configure()` method of the `Startup` class with the following code:

```c#
//Startup.cs

// ...existing code...
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
 if (env.IsDevelopment())
 {
 app.UseDeveloperExceptionPage();
 }

 app.UseHttpsRedirection();
 app.UseRouting();
 
 app.UseAuthentication(); //👈 new code
 app.UseAuthorization();
 
 app.UseEndpoints(endpoints =>
 {
 endpoints.MapControllers();
 });
}
// ...existing code...
```

Compared to the previous version, you just added the `app.UseAuthentication()` statement to enable authentication for your application.

<details>
 <summary>Why do you need authentication?</summary>
You may wonder why you need to register the authentication middleware in your ASP.NET Web API. After all, you should only manage authorization. The authentication middleware is needed because it is responsible for creating the security context under which the code is running.


Also, the registration order is important: you need to register the authentication middleware before the authorization middleware.

For more details, check out the [ASP.NET Web API authentication and authorization documentation](https://docs.microsoft.com/en-us/aspnet/web-api/overview/security/authentication-and-authorization-in-aspnet-web-api).
</details>

<include src="Auth0TemplatesForDotnetCTA" />

## Securing the API Endpoints

Almost everything is ready to secure your application. You just need to protect the actions that allow clients to create, update, and delete glossary items. So, open the `GlossaryController.cs` file in the `Controllers` folder and add the `Microsoft.AspNetCore.Authorization` namespace. The `using` section of the file will look like the following:

```c#
//Controllers/GlossaryController.cs
using System;
using System.Collections.Generic;
using Microsoft.AspNetCore.Mvc;
using System.IO;
using Microsoft.AspNetCore.Authorization; //👈 new code

namespace Glossary.Controllers
{
 // ...existing code...
}
```

Now, add the `Authorize` attribute to the `Post()`, `Put()`, and `Delete()` methods. As an example, your `Delete()` method should become like shown below:

```c#
//Controllers/GlossaryController.cs
// ...existing code...
 [HttpDelete]
 [Route("{term}")]
 [Authorize] //👈 new code
 public ActionResult Delete(string term)
 {
 var glossaryItem = Glossary.Find(item =>
 item.Term.Equals(term, StringComparison.InvariantCultureIgnoreCase));

 if (glossaryItem == null)
 {
 return NotFound();
 }
 else
 {
 Glossary.Remove(glossaryItem);
 return NoContent();
 }
 }
// ...existing code...
```

As you can see, the only difference is the `Authorize` attribute.

> **Note**: You may be wondering if the order of the attributes applied to a method or to a controller class matters. Their order is internally defined, and it depends on the stage of the HTTP pipeline they are bound to and on their scope (global, class, or method scope). So, from a syntactical point of view, it doesn't matter if you put, for example, the `Authorize` attribute before or after the `Route` one.
> For more information on this point, check the [official documentation](https://docs.microsoft.com/en-us/aspnet/core/mvc/controllers/filters?view=aspnetcore-3.0).

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

## Testing the Secure Web API

In order to ensure that all works as expected, run the application, point your browser to [https://localhost:5001/swagger](https://localhost:5001/swagger), and test the GET action on the `api/Glossary` endpoint. You should get the list of term definitions as before.

### Testing unauthorized accesses

Now, try to add a new item to the glossary by using the POST action on the `api/Glossary` endpoint as shown in the following picture:

![Calling HTTP POST on the Glossary Web API](https://images.ctfassets.net/23aumh6u8s0i/2Wj5qH5QGMcZC82KC47HVM/758a0589e4254ff6a013deb48808cba7/post-webapi-swagger-ui.png)

This time you should get a `401 Unauthorized` HTTP status code, as shown below:

![Unauthorized response from the Web API](https://images.ctfassets.net/23aumh6u8s0i/4GB1MoOEZ3VoKRddc5Vwxi/0510cf8164263b15d188fc5ab5751424/unauthorized-response.png)

This means that your endpoint is protected: only authorized users can add a new definition to the list. So, in order to add a new item to the glossary, you need to get an access token from Auth0 and make a request to the API endpoint using the [Bearer Authorization scheme](https://www.rfc-editor.org/rfc/rfc6750.html).

### Testing authorized accesses

However, before going ahead, you need a way to provide your access token to the interactive web API documentation. To achieve this goal, edit the `Startup.cs` file and apply the changes shown in the following code snippet to the `ConfigureServices()` method:

```csharp
//Startup.cs
// ...existing code...
 public void ConfigureServices(IServiceCollection services)
 {

 // ...existing code...
 services.AddControllers();

 services.AddSwaggerGen(c =>
 {
 c.SwaggerDoc("v1", new OpenApiInfo { Title = "MyProject", Version = "v1.0.0" });

 //👇 new code
 var securitySchema = new OpenApiSecurityScheme
 {
 Description = "Using the Authorization header with the Bearer scheme.",
 Name = "Authorization",
 In = ParameterLocation.Header,
 Type = SecuritySchemeType.Http,
 Scheme = "bearer",
 Reference = new OpenApiReference
 {
 Type = ReferenceType.SecurityScheme,
 Id = "Bearer"
 }
 };

 c.AddSecurityDefinition("Bearer", securitySchema);

 c.AddSecurityRequirement(new OpenApiSecurityRequirement
 {
 { securitySchema, new[] { "Bearer" } }
 });
 //👆 new code
 });
 }
// ...existing code...
```

You added a few additional configuration options to your API's Swagger instance. In particular, you defined a security schema and added it to the generated documentation as a security requirement.

Now, restart your ASP.NET Core Web API and take a look at the web page shown at the address [https://localhost:5001/swagger](https://localhost:5001/swagger):

![Protected Web APIs in Swagger UI](https://images.ctfassets.net/23aumh6u8s0i/1rNBChKdbCr9fKdpbbYcKR/014f6ace0411febc726959cd88ed8e6a/protected-swagger-ui-webapi.png)

You see the new *Authorize* button and the lock icon on each action. You can configure Swagger to get a more accurate UI, but this topic is out of the scope of this article. Please check out [the official documentation for more details](https://github.com/domaindrivendev/Swashbuckle.AspNetCore#add-security-definitions-and-requirements).

At this point, let's get the access token from Auth0. The simplest way is to access [the API section of your Auth0 Dashboard](https://manage.auth0.com/#/apis) again, select the API that you created before and select the *Test* tab. In this section, you can get a temporary token to test your Web API by clicking the *Copy Token* icon as shown in the following picture:

![Copying temporary token from the Auth0 Dashboard](https://images.ctfassets.net/23aumh6u8s0i/1FENUfKNw5FrmexhvdWwv5/bb1c283a019dc0fd7322e357efd1bdb2/copy-token.png)

Now, head back to your browser and click the *Authorize* button. A window dialog opens, as shown in the following picture:

![Configure access token for Swagger UI](https://images.ctfassets.net/23aumh6u8s0i/18f9kh3tBXiOMbxjSA7j1k/c0ab1d1475b75ef51a50a1009ea3c5c1/access-token-swagger-ui.png)

Paste the token you copied from the Auth0 Dashboard into the text box and click *Authorize*.

With this step, you have configured the interactive documentation to add the Authorization header to each HTTP request. That header's value will be the access token in the form of a bearer token.

If you try to add a new glossary term through the POST action, you should get a successful `201 Created` HTTP status code as before securing the API. The following picture shows an example of such a response:

![A successful response from the protected Web API](https://images.ctfassets.net/23aumh6u8s0i/2iY4mvFFAZGrDcpXKZiFPU/b0f0b3d576e9d0fc19e7fc7574e089a3/success-response-webapi-post.png)

Now your Web API is ready to be securely consumed by clients.

## Recap

This article showed you how to protect your ASP.NET Core Web API to prevent unauthorized users from accessing specific endpoints. You learned how to register your Web API application with Auth0, how to enable your ASP.NET application to support authorization, and how to use the autogenerated interactive documentation to test the endpoints.

You can download the full source code of the application from [GitHub](https://github.com/auth0-blog/glossary-web-api-aspnet/tree/add-authorization).

"aspnet"