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

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

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

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

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 add authentication to your ASP.NET Core MVC Application by using Auth0.

Add Authentication to Your ASP.NET Core MVC Application

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. <br>
For the last few years, Pablo has helped numerous Microsoft teams develop tools and frameworks for building service-oriented and web applications with .NET. <br>
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

Understand the Backend For Frontend authentication pattern and how it can be implemented in ASP.NET with Auth0.

Backend For Frontend Authentication Pattern with Auth0 and ASP.NET Core

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 how nanoservices differ from microservices and how to build them with ASP.NET and Azure Functions.

Implementing Nanoservices in ASP.NET Core

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


Authorization for ASP.NET Core Web APIs

The new Auth0 ASP.NET Core Authentication SDK makes adding authentication and authorization to your web applications a breeze.

Auth0 brings you the new [ASP.NET Core Authentication SDK](https://github.com/auth0/auth0-aspnetcore-authentication), which improves your development experience and better integrates with Auth0 features! Let's take a tour through the main features of the SDK to see how easy it becomes to integrate your ASP.NET applications with Auth0.

## The SDK Overview

So far, you were used to relying on the standard `Microsoft.AspNetCore.Authentication.OpenIdConnect` package to integrate your ASP.NET application with Auth0. That library does its job very well. However, when you move away from implementing the simple login and logout, your code starts becoming verbose until it gets messy.

You can mitigate this issue by [implementing your authentication with C# extension methods](https://auth0.com/blog/using-csharp-extension-methods-for-auth0-authentication/). But why do it yourself when the experts at Auth0 can provide you with a ready-to-use SDK?

The  [ASP.NET Core Authentication SDK](https://github.com/auth0/auth0-aspnetcore-authentication) allows you to write less code to integrate Auth0 authentication and authorization into your ASP.NET applications. It simplifies configuration, supports additional query parameters and refresh tokens, natively supports [Auth0 Organizations](https://auth0.com/docs/organizations) and user invitations. It is actually a wrapper around the `Microsoft.AspNetCore.Authentication.OpenIdConnect` library, but it brings you a standard and easy way to integrate Auth0 into your applications.

You can use the SDK for all your ASP.NET applications that require authentication, such as ASP.NET MVC apps, Razor web apps, and Blazor server apps.

## Install the ASP.NET Core Authentication SDK

You can install the Auth0 ASP.NET Core SDK by using the NuGet Package Manager UI in Visual Studio, as shown below:

![Installing the Auth0 ASP.NET SDK with NuGet Package Manager UI](https://images.ctfassets.net/23aumh6u8s0i/52AB2b6XDotBDpBlPPR1F7/f4b71a1b33c3cecb56b46d96b2e27788/installing-auth0-aspnet-core-authentication-sdk.png)

You can also install it by running the following command in the Package Manager Console:

```powershell
Install-Package Auth0.AspNetCore.Authentication
```

Or you can use the following command in a terminal window:

```bash
dotnet add package Auth0.AspNetCore.Authentication
```

Independently of your preferred approach, you will get the `Auth0.AspNetCore.Authentication` dependency in your ASP.NET project.

## The Basic Login Use Case

Let's start to take a look at the way the new SDK improves your developer experience. Of course, you need an Auth0 account to integrate your ASP.NET application with Auth0. If you haven't, you can <a href="https://auth0.com/signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">sign up for a free one</a> right now. Follow [the Auth0 ASP.NET Core Authentication SDK quickstart to register your application and get your application keys](https://auth0.com/docs/quickstart/webapp/aspnet-core#configure-auth0). 

The following is the typical code you write to enable authentication in your ASP.NET application when using `Microsoft.AspNetCore.Authentication.OpenIdConnect`:

```csharp
public void ConfigureServices(IServiceCollection services)
{
  services.AddAuthentication(options => {
    options.DefaultAuthenticateScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultSignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = CookieAuthenticationDefaults.AuthenticationScheme;
  })
  .AddCookie()
  .AddOpenIdConnect("Auth0", options => {
    options.Authority = $"https://{Configuration["Auth0:Domain"]}";
    options.ClientId = Configuration["Auth0:ClientId"];
    options.CallbackPath = new PathString("/callback");
    options.TokenValidationParameters = new TokenValidationParameters
    {
      NameClaimType = "name"
    };
    options.Events = new OpenIdConnectEvents
    {
      OnRedirectToIdentityProviderForSignOut = (context) =>
      {
        var logoutUri = $"https://{Configuration["Auth0:Domain"]}/v2/logout?client_id={Configuration["Auth0:ClientId"]}";

        var postLogoutUri = context.Properties.RedirectUri;
        if (!string.IsNullOrEmpty(postLogoutUri))
        {
          if (postLogoutUri.StartsWith("/"))
          {
            // transform to absolute
            var request = context.Request;
            postLogoutUri = request.Scheme + "://" + request.Host + request.PathBase + postLogoutUri;
          }
          logoutUri += $"&returnTo={ Uri.EscapeDataString(postLogoutUri)}";
        }

        context.Response.Redirect(logoutUri);
        context.HandleResponse();

        return Task.CompletedTask;
      }
    };
  });
}
```

I will not go through that code to explain every single step. You just need to know it implements the login and logout features in your applications by relying on the [Auth0 Universal Login](https://auth0.com/docs/login/universal-login) page.

By using the Auth0 ASP.NET Core Authentication SDK, your code shortens as follows:

```csharp
public void ConfigureServices(IServiceCollection services)
{
  services.AddAuth0WebAppAuthentication(options =>
  {
    options.Domain = Configuration["Auth0:Domain"];
    options.ClientId = Configuration["Auth0:ClientId"];
  });
}
```

Impressive, isn't it? 😲

The SDK takes care of all the configuration stuff you previously needed to do manually. And that's just the beginning! 🎉

## Get an Access Token

What if you want to call an API from your ASP.NET application? In this case, you need to [request an access token for a specific audience](https://auth0.com/docs/security/tokens/access-tokens/get-access-tokens#control-access-token-audience) to Auth0.

Doing it without the SDK would require a code similar to the following:

```csharp
public void ConfigureServices(IServiceCollection services)
{
  services.AddAuthentication(options => {
    options.DefaultAuthenticateScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultSignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = CookieAuthenticationDefaults.AuthenticationScheme;
  })
  .AddCookie()
  .AddOpenIdConnect("Auth0", options => {
    options.Authority = $"https://{Configuration["Auth0:Domain"]}";
    options.ClientId = Configuration["Auth0:ClientId"];
    //👇new code
    options.ClientSecret = Configuration["Auth0:ClientSecret"];
    options.SaveTokens = true;
    options.ResponseType = OpenIdConnectResponseType.Code;
    //👆new code
    options.CallbackPath = new PathString("/callback");
    options.TokenValidationParameters = new TokenValidationParameters
    {
      NameClaimType = "name"
    };
    options.Events = new OpenIdConnectEvents
    {
      OnRedirectToIdentityProviderForSignOut = (context) =>
      {
        var logoutUri = $"https://{Configuration["Auth0:Domain"]}/v2/logout?client_id={Configuration["Auth0:ClientId"]}";

        var postLogoutUri = context.Properties.RedirectUri;
        if (!string.IsNullOrEmpty(postLogoutUri))
        {
          if (postLogoutUri.StartsWith("/"))
          {
            // transform to absolute
            var request = context.Request;
            postLogoutUri = request.Scheme + "://" + request.Host + request.PathBase + postLogoutUri;
          }
          logoutUri += $"&returnTo={ Uri.EscapeDataString(postLogoutUri)}";
        }

        context.Response.Redirect(logoutUri);
        context.HandleResponse();

        return Task.CompletedTask;
      }
      //👇new code
      OnRedirectToIdentityProvider = context =>
      {
        context.ProtocolMessage.SetParameter("audience", Configuration["Auth0:Audience"]);
        return Task.FromResult(0);
      }
      //👆new code
    };
  });
}
```

Basically, you need to add a few more lines to the previous code in order to change the OAuth flow, provide the client secret, enable token saving, and attach the audience value to the authorization request.

The equivalent code to achieve the same result using the SDK is as follows:

```csharp
public void ConfigureServices(IServiceCollection services)
{
  services.AddAuth0WebAppAuthentication(options =>
  {
    options.Domain = Configuration["Auth0:Domain"];
    options.ClientId = Configuration["Auth0:ClientId"];
    options.ClientSecret = Configuration["Auth0:ClientSecret"];
  })
  .WithAccessToken(options =>
  {
    options.Audience = Configuration["Auth0:Audience"];
  }); 
}
```

Aren't you excited about this? 💥 Your code will be more concise, clean, and clear!

## Refresh Tokens As Magic

And in case you need a [refresh token](https://auth0.com/docs/security/tokens/refresh-tokens)? 🤔 Nothing could be simpler. Just set a flag:

```csharp
public void ConfigureServices(IServiceCollection services)
{
  services.AddAuth0WebAppAuthentication(options =>
  {
    options.Domain = Configuration["Auth0:Domain"];
    options.ClientId = Configuration["Auth0:ClientId"];
    options.ClientSecret = Configuration["Auth0:ClientSecret"];
  })
  .WithAccessToken(options =>
  {
    options.Audience = Configuration["Auth0:Audience"];
    options.UseRefreshTokens = true;   //👈 new code
  });
}
```

Compare it with the code you need to add to the SDK-less code:

```csharp
public void ConfigureServices(IServiceCollection services)
{
  services.AddAuthentication(options => {
  //...the code to configure authentication...
  })
  .AddCookie(options => {
    options.Events.OnValidatePrincipal = (context) => {
    var options = context.HttpContext.RequestServices.GetRequiredService<Auth0Options>();

    string accessToken;
    if (context.Properties.Items.TryGetValue(".Token.access_token", out accessToken))
    {
      if (options.UseRefreshTokens)
      {
        string refreshToken;
        if (context.Properties.Items.TryGetValue(".Token.refresh_token", out refreshToken))
        {
          var now = DateTimeOffset.Now;
          var expiresAt = DateTimeOffset.Parse(context.Properties.Items[".Token.expires_at"]);
          var leeway = 60;
          var difference = DateTimeOffset.Compare(expiresAt, now.AddSeconds(leeway));
          var isExpired = difference <= 0;

          if (isExpired && !string.IsNullOrWhiteSpace(refreshToken))
          {
            var result = await RefreshTokens(options, refreshToken, auth0Options.Backchannel);

            if (result != null)
            {
              context.Properties.UpdateTokenValue("access_token", result.AccessToken);
              context.Properties.UpdateTokenValue("refresh_token", result.RefreshToken);
              context.Properties.UpdateTokenValue("id_token", result.IdToken);
              context.Properties.UpdateTokenValue("expires_at", DateTimeOffset.Now.AddSeconds(result.ExpiresIn).ToString("o"));
            }
            else
            {
              context.Properties.UpdateTokenValue("refresh_token", null);
            }

            context.ShouldRenew = true;
          }
        } 
      }
    }
  })
  .AddOpenIdConnect("Auth0", options => {
    //...the code to configure OpenID Connect...
  });
}
```

You should take care of all the details about determining the token expiration and requesting a new access token. The Auth0 ASP.NET Core Authentication SDK does this on your behalf. Do you agree it's magic? ✨

## Auth0 Organizations Support

Not only the ASP.NET Core Authentication SDK lets you deal with standard OpenID Connect and OAuth duties, but it also simplifies your life in using specific Auth0 features such as [Auth0 Organizations](https://auth0.com/docs/organizations). By using Organizations, you can represent logical groups of users such as teams, partners, business customers, and so on. They can have specific policies, branding, and other customizations. So, to enable a user to log in to an organization, you need to specify it in your ASP.NET application. The following is an example of how you can accomplish this by using the SDK:

```csharp
public void ConfigureServices(IServiceCollection services)
{
  services.AddAuth0WebAppAuthentication(options =>
  {
    options.Domain = Configuration["Auth0:Domain"];
    options.ClientId = Configuration["Auth0:ClientId"];
    options.Organization = Configuration["Auth0:Organization"];
  });
}
```

Pretty straightforward, right? 🙌 Of course, you can do more with Organizations. Please, take a look at [the ASP.NET Core Authentication SDK documentation](https://github.com/auth0/auth0-aspnetcore-authentication#organization) to learn more.

## Customization

At this point, you may think that having an SDK forces you to use its methods to work with OpenID Connect and OAuth. So you no longer have the freedom of adding extra parameters to the authorization request, for example. Or you may think you can't anymore apply your custom token validation or freely manage OpenID Connect events.

I have good news: you don't need to worry about this. The ASP.NET Core Authentication SDK leaves you the freedom to customize many things.

For example, you can add custom parameters to the authorization request. Look at the following example:

```csharp
public void ConfigureServices(IServiceCollection services)
{
  services.AddAuth0WebAppAuthentication(options =>
  {
    options.Domain = Configuration["Auth0:Domain"];
    options.ClientId = Configuration["Auth0:ClientId"];
    options.LoginParameters = new Dictionary<string, string>() { 
      { "screen_hint", "signup" } 
    };
  }); 
}
```

Here you configured your ASP.NET application to attach the `screen_hint` parameter with the `signup` value  to the authorization request. In this specific case, the user will see the signup window instead of the default login screen.

But you can also apply your custom validation, as in the following case:

```csharp
public void ConfigureServices(IServiceCollection services)
{
  services.AddAuth0WebAppAuthentication(options =>
  {
    options.Domain = Configuration["Auth0:Domain"];
    options.ClientId = Configuration["Auth0:ClientId"];
    options.OpenIdConnectEvents = new OpenIdConnectEvents
    {
      OnTokenValidated = (context) =>
      {
        var birthDateClaim = context.SecurityToken.Claims.SingleOrDefault(claim => claim.Type == "birthdate")?.Value;

        if (string.IsNullOrWhiteSpace(birthDateClaim))
        {
          context.Fail("The 'birthdate' claim must be present in the ID token.");
        }
            
        return Task.CompletedTask;
      }
    };
  })
}
```

As you can see, the ASP.NET Core Authentication SDK exposes the `OpenIdConnectEvents` option to let you handle the standard events triggered by the `Microsoft.AspNetCore.Authentication.OpenIdConnect` library. This way, you can combine the SDK simplicity with the standard library behavior to get the maximum flexibility.

## Summary

Now you should have a clearer idea about the benefits you have by using the ASP.NET Core Authentication SDK to integrate Auth0 into your ASP.NET applications: less code, more readability, flexibility, and best practices inside. So, give a try to the SDK and integrate your [ASP.NET applications with Auth0 by following the QuickStart](https://auth0.com/docs/quickstart/webapp/aspnet-core). Check out [the SDK documentation](https://auth0.github.io/auth0-aspnetcore-authentication/) to learn more.

You can also [contribute to it](https://github.com/auth0/auth0-aspnetcore-authentication#contributing): it's open-source!

Exploring the Auth0 ASP.NET Core Authentication SDK

A practical tutorial showing how to setup and develop a modern Web application based on ASP.NET Core 2.0 and React.

Developing Web Apps with ASP.NET Core 2.0 and React - Part 3

Developing Web Apps with ASP.NET Core 2.0 and React - Part 2



**TL;DR:** In this series of posts, starting with this one, you will build a Web application based on ASP.NET Core 2.0 and React. To solve the identity management feature, you will integrate this stack with [Auth0](https://auth0.com/). In this first part of the series, you are going to use ASP.NET Core 2.0 to develop the APIs of your application. [The final code can be found in this GitHub repository](https://github.com/andychiare/netcore2-auth0).

<include src="TweetQuote" quoteText="Learn how easy it is to create a modern web application with ASP.NET Core 2.0 and React"/>

---

## Setting Up the ASP.NET Core Application

The application that you are going to implement will allow users to browse an online bookstore. Following [the API-First Development approach](https://dzone.com/articles/an-api-first-development-approach-1), you will start building your application by creating the ASP.NET Core 2.0 Web API. To do that, you have two alternatives: first, you can create your application from Visual Studio; second, you can create your application from the command line.

### Creating the Project with Visual Studio

If you are using Visual Studio, you can create the project by choosing *ASP.NET Core Web App* project template, as shown in the following picture:

![Creating an ASP.NET Core Web App with Visual Studio](https://images.ctfassets.net/23aumh6u8s0i/3VdEYdUZjg1dZ8CjKW7FFy/e6dacc131f59c2ab0459cb72a6addb6a/creating-project)

> If you don't have Visual Studio, [you can download it for free here](https://www.visualstudio.com/free-developer-offers/).

After selecting the *ASP.NET Core Web App* project template, you need to specify the type of ASP.NET application you want to build. In your case, you will select the *Web API* application type, as in the following picture:

![Creating ASP.NET Core 2 Web API](https://images.ctfassets.net/23aumh6u8s0i/fSpJBnx1JsWrguTiNfcyh/c5ccb832f295f9cd27184e7b8c0ff926/choosing-web-api)

Make sure you **do not** select any type of authentication, since you will integrate your application with [Auth0](https://auth0.com/).

### Creating the Project from the Command Line

If you prefer to use the command line, you can create your application by typing the following command:

```shell
dotnet new webapi -n API-Auth0
```

This will create an ASP.NET Web API directory, with your project inside, named `API-Auth0` in the current directory.

Whether you use Visual Studio or the command line, you will get the same result. That is, after following these steps, you will get a basic ASP.NET Core 2 Web API application.

### Creating the Books Controller on ASP.NET Core 2.0

Now that you have your project created, you can start refactoring it to provide the desired functionality. The first thing you will do is to remove the `ValuesController.cs` file under the `Controllers` directory. You won't need this controller in your application.

After removing it, you can create the `BooksController.cs` file, in this same directory, with the following code:

```csharp
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;

namespace APIAuth0.Controllers
{
    [Route("api/[controller]")]
    public class BooksController : Controller
    {
        [HttpGet]
        public IEnumerable<Book> Get()
        {
            var currentUser = HttpContext.User;
            var resultBookList = new Book[] {
                new Book { Author = "Ray Bradbury", Title = "Fahrenheit 451", AgeRestriction = false },
                new Book { Author = "Gabriel García Márquez", Title = "One Hundred years of Solitude", AgeRestriction = false },
                new Book { Author = "George Orwell", Title = "1984", AgeRestriction = false },
                new Book { Author = "Anais Nin", Title = "Delta of Venus", AgeRestriction = true }
            };

            return resultBookList;
        }

        public class Book
        {
            public string Author { get; set; }
            public string Title { get; set; }
            public bool AgeRestriction { get; set; }
        }
    }
}
```

Here, you have defined a Web API returning a list of books. For simplicity, you are storing the list of books in an array. In a real-world case, however, this list should be stored in a persistent database. The Web API's URL will be `/api/books` and any HTTP client can get the list of books by issuing a simple HTTP GET request:

```bash
# run the application in the background
dotnet run &

# issue a get request
curl -D - http://localhost:5000/api/books
```

Of course, you don't want that any client could access your bookstore without some proper authentication process. You want that only authorized clients could get the list of books managed by your application. That's where [Auth0](https://auth0.com/) can help you: it provides a set of identity solutions that integrate security into your application.

## Integrating ASP.NET Core 2.0 with Auth0

As the first step, you will need an Auth0 account. If don't have one yet, you can sign up for a <a href="https://auth0.com/signup" data-amp-replace="CLIENT_ID" data-amp-addparams="anonId=CLIENT_ID(cid-scope-cookie-fallback-name)">free account here</a>.

During the registration process, you will need to provide the *tenant domain name*, the service hosting region, and a few other details about your company and yourself. The domain name is quite important since it will determine the root part of the API endpoints exposed by [Auth0](https://auth0.com/) to your authorized clients. Once you provide a domain name, you cannot change it anymore. However, you can create as many tenants as needed. Once the registration phase is completed, [you can access your Auth0 dashboard](https://manage.auth0.com/).

### Creating an Auth0 API

As you are creating a backend API that enables users to browse an online bookstore, you will need to create an [Auth0 API](https://auth0.com/docs/apis) to represent your backend. To do that, head to [the APIs section of the Auth0 dashboard](https://manage.auth0.com/#/apis) and click on the *Create API* button. After that, the dashboard will ask you for three things:

- the *Name* of your API, you can set it to *Online Bookstore*;
- an *Identifier* for your API, you can set it to `https://onlinebookstore.mycompany.com`;
- and the *Signing Algorithm*, you can choose *RS256* in this field;

![Securing an online bookstore with Auth0](https://images.ctfassets.net/23aumh6u8s0i/3VAKT9b1bo3bmn6AH17tqu/279ae8cc498c576196d6d575d9ea6a33/creating-an-auth0-api)

When you complete this form, you can hit the *Create* button.

### Creating an Auth0 Application

Your goal is to control your API access by authorizing only trusted clients. To do that, you will also need an application configuration on Auth0. Usually, you would need to create a new application to represent your front-end app. The type of the front-end app would help you decide the type of the Auth0 Application to create. However, as in this first part you will not create the front-end yet, you can use the application that was automatically created for your Auth0 API.

If you chose *Online Bookstore* as the name of your API, then [you will see an application called *Online Bookstore (Test Application)* in the Application section of the Auth0 dashboard](https://manage.auth0.com/#/applications). Click on this application and head over to the *Settings* tab. In this tab, you will see three properties that you will need:

- the *Domain* of your Auth0 tenant;
- the *Client ID* key;
- and the *Client Secret* key;

You will use these values soon enough.

### Configuring Auth0 on ASP.NET Core Apps

After creating the Auth0 API, you will have to modify your application in order to hand the identity management over to [Auth0](https://auth0.com/). As a first step, you will need to add an Auth0 section in the `appsettings.json` configuration file, as shown below:

```json
{
  "Logging": {
    "IncludeScopes": false,
    "Debug": {
      "LogLevel": {
        "Default": "Warning"
      }
    },
    "Console": {
      "LogLevel": {
        "Default": "Warning"
      }
    }
  },
  "Auth0": {
    "Authority": "<YOUR_AUTH0_DOMAIN>",
    "Audience": "<YOUR_AUTH0_AUDIENCE>"
  }
}
```

You will have to replace both `<YOUR_AUTH0_DOMAIN>` and `<YOUR_AUTH0_AUDIENCE>` with the values that you have defined in the previous sections. For example, if you defined your tenant domain to `https://dotnet2-react.auth0.com` that's what you will use in the place of the `<YOUR_AUTH0_DOMAIN>` placeholder. In the place of the `<YOUR_AUTH0_AUDIENCE>` placeholder, you will use the value that you defined for the *Identifier* of your Auth0 API (e.g. `https://onlinebookstore.mycompany.com`).

Then, you will have to change the `ConfigureServices()` method in the `Startup.cs` file, as follows:

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

// ... other using statements
// ... namespace definition
// ... class definition
// ... etc

public void ConfigureServices(IServiceCollection services) {
	services.AddAuthentication(options =>
	{
		options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
		options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
	}).AddJwtBearer(options =>
	{
		options.Authority = Configuration["Auth0:Authority"];
		options.Audience = Configuration["Auth0:Audience"];
	});

	services.AddMvc();
}

// ... etc
```

As you can see, you have added the authentication service by specifying the [JWT](https://jwt.io/) bearer scheme and providing the authority and audience values taken from the `appsetting.json` configuration file.

After that, you will need to add an invocation to `app.UseAuthentication()` in the body of `Configure()` method, as follows:

```csharp
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
	if (env.IsDevelopment())
	{
		app.UseDeveloperExceptionPage();
	}

	app.UseAuthentication();

	app.UseMvc();
}
```

After enabling authentication support, you can block public access to your API by adding the `Authorize` attribute to the endpoint in the `BooksController.cs` file:

```csharp
[HttpGet, Authorize]
public IEnumerable<Book> Get()
{
	var currentUser = HttpContext.User;
	var resultBookList = new Book[] {
		new Book { Author = "Ray Bradbury", Title = "Fahrenheit 451", AgeRestriction = false },
		new Book { Author = "Gabriel García Márquez", Title = "One Hundred years of Solitude", AgeRestriction = false },
		new Book { Author = "George Orwell", Title = "1984", AgeRestriction = false },
		new Book { Author = "Anais Nin", Title = "Delta of Venus", AgeRestriction = true }
	};

	return resultBookList;
}
```

Now, if you try to access the `/api/books` endpoint, you will get a 401 HTTP status code (which means that you are not authorized). You can verify it by using any HTTP client, such as a browser, [curl](https://curl.haxx.se/), or [Postman](https://www.getpostman.com/).

```bash
# run the application in the background
dotnet run &

# issue a get request
curl -D - http://localhost:5000/api/books
```

The last command will generate a response like the following one:

```bash
# HTTP/1.1 401 Unauthorized
# Date: Wed, 24 Jan 2018 16:28:09 GMT
# Server: Kestrel
# Content-Length: 0
# WWW-Authenticate: Bearer
```

### Getting an Access Token

Now that you have secured your endpoints with Auth0, you will learn how to authenticate a machine to machine application to be able to get the list of books again. You can use any HTTP client, but in this section, you will see how to achieve that by using `curl`.

The first step is to get an authorization token from Auth0. You can do that by issuing a POST request to [the `/oauth/token` endpoint](https://auth0.com/docs/api/authentication#authorization-code) of your Auth0 domain, as follows:

```bash
AUTH0_CLIENT_ID=<YOUR_AUTH0_CLIENT_ID>
AUTH0_CLIENT_SECRET=<YOUR_AUTH0_CLIENT_SECRET>
AUTH0_AUDIENCE=<YOUR_AUTH0_AUDIENCE>
AUTH0_DOMAIN=<YOUR_AUTH0_DOMAIN>

curl -X POST -H 'content-type: application/json' -d '{
    "client_id": "'$AUTH0_CLIENT_ID'",
    "client_secret": "'$AUTH0_CLIENT_SECRET'",
    "audience": "'$AUTH0_AUDIENCE'",
    "grant_type":"client_credentials"
}' https://$AUTH0_DOMAIN/oauth/token
```

Note that you will have to replace `<YOUR_AUTH0_CLIENT_ID>`, `<YOUR_AUTH0_CLIENT_SECRET>`, `<YOUR_AUTH0_AUDIENCE>`, and `<YOUR_AUTH0_DOMAIN>` in the commands above with the values corresponding to the Auth0 API and Application that you have created before.

The response to this request will be something similar to the following:

```json
{
    "access_token": "eyJ0eXAiO...pJmNFPA",
    "expires_in": 86400,
    "token_type": "Bearer"
}
```

Now, you can use the `access_token` you have received from [Auth0](https://auth0.com/) to request the list of books, as follows:

```bash
ACCESS_TOKEN=eyJ0eXAiO...pJmNFPA

curl -H 'Authorization: Bearer '$ACCESS_TOKEN -D - http://localhost:5000/api/books
```

This request will generate the following response:

```bash
# HTTP/1.1 200 OK
# Date: Wed, 24 Jan 2018 17:35:26 GMT
# Content-Type: application/json; charset=utf-8
# Server: Kestrel
# Transfer-Encoding: chunked

# [{"author":"Ray Bradbury","title":"Fahrenheit 451","ageRestriction":false},{"author":"Gabriel García Márquez","title":"One Hundred years of Solitude","ageRestriction":false},{"author":"George Orwell","title":"1984","ageRestriction":false},{"author":"Anais Nin","title":"Delta of Venus","ageRestriction":true}]
```

<include src="TweetQuote" quoteText="Adding identity management to an ASP.NET Core 2.0 is really easy with Auth0."/>

### Creating Integration Tests as a Machine to Machine Applications

The test performed with `curl` in the previous section should only verify that the Auth0 configuration data and that the API implemented by our application work well together. This is a test performed on the fly that should not be persisted. In fact, the type of application that Auth0 automatically created was _Machine to Machine Application_. This type of application is intended for a server to server or unattended interaction. You **must never** store the *Client Secret* on the client side, since it will compromise the application security.

The implementation of the integration test may be a case where you can use the *Client Secret* since this information will not be exposed to the client but remains in the development environment.

Now, it's time to write an integration test that verifies that a request to obtain the book list without an access token fails:

```csharp
[Fact]
public async Task UnAuthorizedAccess()
{
    var response = await _client.GetAsync("/api/books");

    Assert.Equal(HttpStatusCode.Unauthorized, response.StatusCode);
}
```

This simple test verifies that such a request will receive a 401 Unauthorized HTTP status code. After that, you can verify that the configuration data you put in the `appsetting.json` file allows you to get a valid access token:

```csharp

[Fact]
public async Task TestGetToken()
{
    var auth0Client = new HttpClient();
    var bodyString = $@"{{""client_id"":""{_configuration["Auth0:ClientId"]}"", ""client_secret"":""{_configuration["Auth0:ClientSecret"]}"", ""audience"":""{_configuration["Auth0:Audience"]}"", ""grant_type"":""client_credentials""}}";
    var response = await auth0Client.PostAsync($"{_configuration["Auth0:Authority"]}oauth/token", new StringContent(bodyString, Encoding.UTF8, "application/json"));

    Assert.Equal(HttpStatusCode.OK, response.StatusCode);

    var responseString = await response.Content.ReadAsStringAsync();
    var responseJson = JObject.Parse(responseString);
    Assert.NotNull((string)responseJson["access_token"]);
    Assert.Equal("Bearer", (string)responseJson["token_type"]);
}

```

Here, you have replicated through the code the same request you made via `curl`. The `Assert` clauses just verify that a non-null token has been received and that the type of token is *Bearer*.

The last test ensures that a request with a valid access token will get the list of books returned by the API:

```csharp
[Fact]
public async Task GetBooks()
{
    var token = await GetToken();

    var requestMessage = new HttpRequestMessage(HttpMethod.Get, "/api/books");
    requestMessage.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
    var booksResponse = await _client.SendAsync(requestMessage);

    Assert.Equal(HttpStatusCode.OK, booksResponse.StatusCode);

    var bookResponseString = await booksResponse.Content.ReadAsStringAsync();
    var bookResponseJson = JArray.Parse(bookResponseString);
    Assert.Equal(4, bookResponseJson.Count);
}
```

This code uses a method called `GetToken()` that requests a valid token to [Auth0](https://auth0.com/) authentication endpoint:

```csharp

public async Task<string> GetToken()
{
    var auth0Client = new HttpClient();
    string token = "";
    var bodyString = $@"{{""client_id"":""{_configuration["Auth0:ClientId"]}"", ""client_secret"":""{_configuration["Auth0:ClientSecret"]}"", ""audience"":""{_configuration["Auth0:Audience"]}"", ""grant_type"":""client_credentials""}}";
    var response = await auth0Client.PostAsync($"{_configuration["Auth0:Authority"]}oauth/token", new StringContent(bodyString, Encoding.UTF8, "application/json"));

    if (response.IsSuccessStatusCode)
    {
        var responseString = await response.Content.ReadAsStringAsync();
        var responseJson = JObject.Parse(responseString);
        token = (string)responseJson["access_token"];

    }

    return token;
}

```

This test completes the validation of your ASP.NET Core 2.0 application with [Auth0](https://auth0.com/). If needed, you can download the full source code of the application from [GitHub](https://github.com/andychiare/netcore2-auth0).

## Summary

In this article, you have built an ASP.NET Core 2 Web API application and you have integrated it with Auth0 in order to expose the API only to trusted clients.

This is the first step in a series of articles that will show how to build a complete modern application. This application will be based on the ASP.NET Core API that you have just created and in a React Single Page Application. [In the next article](https://auth0.com/blog/developing-web-apps-with-asp-dot-net-core-2-dot-0-and-react-part-2/), you will build this Single Page Application to allow users to browse the bookstore. Stay tuned.


Developing Web Apps with ASP.NET Core 2.0 and React - Part 1

A practical tutorial showing how to use JSON Web Tokens in ASP.NET Core 2 applications.

Securing ASP.NET Core 2.0 Applications with JWTs

bruno-krebs

I am passionate about developing highly scalable, resilient applications. I love everything from the database, to microservices (Kubernetes, Docker, etc), to the frontend. I find amazing to think about how all pieces work together to provide a fast and pleasurable experience to end users, mainly because they have no clue how complex that "simple" app is.

R&D Content Architect

Bruno Krebs

Learn how to handle authentication on ASP.NET Core applications

ASP.NET Core Authentication Tutorial

7752008352217db815996ab04aec46e6?s=80 avatar

7752008352217db815996ab04aec46e6?s=80

Guest Author

Matias Quaranta

Harness the potential of Azure Search's scalable and powerful engine through ASP.NET Core.

Streamlining a search experience with ASP.NET Core and Azure Search

Let's delve into Azure DocumentDB with ASP.NET Core and learn common-case scenarios from a performance point of view.



---

**TL;DR:** This article continues the journey we [started](https://auth0.com/blog/auth0-with-azure-documentdb/) with Azure DocumentDB. In this installment, we will learn how to build common query patterns and services with ASP.NET Core. A full working application sample is available as a [GitHub repository](https://github.com/ealsur/auth0documentdb/).

---

## Integration between Auth0 and Azure DocumentDB
In our previous article: [Integration between Auth0 and Azure DocumentDB](https://auth0.com/blog/auth0-with-azure-documentdb/) we configured an **integration** between Auth0 and Azure DocumentDB as a Custom Database Provider to store our enrolled users in JSON format, as [documents](https://en.wikipedia.org/wiki/Document-oriented_database).

Conceptually, in Azure DocumentDB, a _database_ can be defined as a logical container of document collections; each _collection_ can hold not only documents but _stored procedures_, _triggers_, and _user-defined functions_. The collection is the [billable unit](https://azure.microsoft.com/pricing/details/documentdb/) and defines the [consistency level](https://azure.microsoft.com/en-us/documentation/articles/documentdb-consistency-levels/).

![DocumentDB element hierarchy](https://images.ctfassets.net/23aumh6u8s0i/2KdM7LvJlnHAZr3rwIlrkL/b4bcebe45661d50cc4685780a3a7eeff/hierarchy)

## Querying and storing data on Azure DocumentDB
Azure DocumentDB collections have [automatic attribute indexing](https://azure.microsoft.com/documentation/articles/documentdb-indexing/), which can also be [customized](https://azure.microsoft.com/documentation/articles/documentdb-indexing-policies/). This **schema-free** approach lets you store documents with different and dynamic structures that can evolve over time.

Since we are storing our users on DocumentDB, this means we can also **store other object types** in the same collection without their interfering with each other.

We will work with a practical pattern to achieve this multiple-type storage and build performance-wise querying examples; even though DocumentDB supports [Node.js](https://azure.microsoft.com/documentation/articles/documentdb-nodejs-get-started/), [Python](https://azure.microsoft.com/documentation/articles/documentdb-sdk-python/), [Java](https://azure.microsoft.com/documentation/articles/documentdb-sdk-java/), and [.Net](https://azure.microsoft.com/documentation/articles/documentdb-get-started/) SDKs, we'll be working on the latter. A [full sample on GitHub](https://github.com/ealsur/auth0documentdb/) is available running on ASP.NET Core.

### Dependencies
Using ASP.NET Core, we will use the _project.json_ to define dependencies. We will only need the [Azure DocumentDB Nuget package](https://www.nuget.org/packages/Microsoft.Azure.DocumentDB.Core/) on the latest version:

```javascript
{
    ...
    "Microsoft.Azure.DocumentDB.Core":"0.1.0-preview"
    ...
}
```

### Base Type Pattern
We start by creating a base abstract class with _Type_ and _Id_ attributes. All DocumentDB objects have an id attribute that can be auto generated (as a Guid) or set upon creation:

```cs
public abstract class Entity
{
    public Entity(string type)
    {
        this.Type = type;
    }
    /// <summary>
    /// Object unique identifier
    /// </summary>
    [Key]
    [JsonProperty("id")]
    public string Id { get; set; }
    /// <summary>
    /// Object type
    /// </summary>
    public string Type { get; private set; }
}
```

>You might notice the [JsonProperty](http://www.newtonsoft.com/json/help/html/t_newtonsoft_json_serialization_jsonproperty.htm) decorator. This is because the "id" attribute on DocumentDB is always lowercase; the decorator will make sure the property name matches, no matter what your JSON serialization configuration is.

Now, every object type you want to store on DocumentDB can **inherit** from this class and set its own attributes:

```cs
public class NotificationPreferences : Entity
{
    public NotificationPreferences():base("notificationpreferences")
    {
        Email = false;
        Push = false;
        SMS = false;
    }
    [JsonProperty("user")]
    public string User { get; set; }
    [JsonProperty("email")]
    public bool Email { get; set; }
    [JsonProperty("push")]
    public bool Push { get; set; }
    [JsonProperty("sms")]
    public bool SMS { get; set; }
}
```

```cs
public class ContactAddress : Entity
{
    public ContactAddress():base("address")
    {
        Primary = false;
    }
    [JsonProperty("user")]
    public string User { get; set; }
    [JsonProperty("address")]
    public string Address { get; set; }
    [JsonProperty("primary")]
    public bool Primary { get; set; }
}
```

### Performant Querying
Azure DocumentDB allows for insert, update, delete, and querying capabilities on different flavors, including LINQ and SQL syntax.

>If you already have your data in another format / source, you can use the Azure DocumentDB [Data Migration tool](https://azure.microsoft.com/documentation/articles/documentdb-import-data/) to migrate it to a collection.

The following operations are available as a [full provider](https://github.com/ealsur/auth0documentdb/blob/master/Services/DocumentDbProvider.cs) on the GitHub repository; we will highlight the snippets that will enable you to understand the basic operations.

To successfully connect to a DocumentDB collection we will need the **service url endpoint** and the **password/key** (when using the MongoDB protocol-enabled version it's called _Password_ and when using a normal DocumentDB instance it's called _Key_) obtained on the Azure Portal. They will enable us to access the service through a [DocumentClient](https://msdn.microsoft.com/library/azure/microsoft.azure.documents.client.documentclient.aspx).

Like we mentioned [earlier](https://azure.microsoft.com/documentation/articles/documentdb-resources/), documents are grouped in collections within a database, each collection is accessed by a [Resource URI syntax](https://msdn.microsoft.com/en-us/library/azure/dn919266.aspx). The SDK provides helper methods to build URIs:

```cs
private  Uri GetCollectionLink()
{
    return UriFactory.CreateDocumentCollectionUri(_settings.DatabaseName, _settings.CollectionName);
}
```

We always start by creating an instance of a DocumentClient and using it in every access operation. A common performance tip is to maintain a single DocumentClient for all our queries and operations:

```cs
public DocumentDbProvider(DocumentDbSettings settings)
{
    _settings = settings;
    _collectionUri = GetCollectionLink();
    _dbClient = new DocumentClient(_settings.DatabaseUri, _settings.DatabaseKey, new ConnectionPolicy(){
        MaxConnectionLimit = 100
    });
    _dbClient.OpenAsync().Wait();
}
```

>For other performance best practices, there is an [entire article](https://azure.microsoft.com/documentation/articles/documentdb-performance-tips/) on this topic.

We will now cover the **basic operations**.

#### Inserting documents
For a generic insertion that works for any object type we can use:

```cs
public async Task<string> AddItem<T>(T document)
{
    var result = await _dbClient.CreateDocumentAsync(_collectionUri, document);
    return result.Resource.Id;
}
```

This will internally use [Newtonsoft.Json](https://www.nuget.org/packages/newtonsoft.json/) to serialize your object to JSON and store it. If you set the id property it will be maintained; if you don't, it will create a new Guid string. This also means that you can exclude attributes from serialization with the [JsonIgnore](http://www.newtonsoft.com/json/help/html/serializationattributes.htm) attribute.

#### Updating documents
The same simple procedure works on updates:

```cs
public async Task<string> UpdateItem<T>(T document, string id)
{
    var result = await _dbClient.ReplaceDocumentAsync(GetDocumentLink(id), document);
    return result.Resource.Id;
}
```

With a helper that obtains a document URI:

```cs
private Uri GetDocumentLink(string id)
{
    return UriFactory.CreateDocumentUri(_settings.DatabaseName, _settings.CollectionName, id);
}
```

>Azure DocumentDB **does not support partial updates** at the time of this article's writing. If you try to do it, you will end up with a replaced document with fewer attributes than it had originally.

#### Deleting a document
Deleting a document is as simple as:

```cs
public async Task DeleteItem(string id)
{
    await _dbClient.DeleteDocumentAsync(GetDocumentLink(id));
}
```

It requires a Document URI, which can be created with our previous helper method.

#### Querying documents
Queries can be performed using [SQL syntax](https://azure.microsoft.com/documentation/articles/documentdb-sql-query/) or [LINQ to DocumentDB syntax](https://azure.microsoft.com/en-us/documentation/articles/documentdb-sql-query/#linq-to-documentdb-sql). Building a generic query method is as simple as:

```cs
public IQueryable<T> CreateQuery<T>(FeedOptions feedOptions)
{
    return _dbClient.CreateDocumentQuery<T>(_collectionUri, feedOptions);
}
```

Or for a SQL syntax query:

```cs
public IQueryable<T> CreateQuery<T>(string sqlExpression, FeedOptions feedOptions)
{
    return _dbClient.CreateDocumentQuery<T>(_collectionUri, sqlExpression, feedOptions);
}
```

You might notice a [FeedOptions](https://msdn.microsoft.com/en-us/library/microsoft.azure.documents.client.feedoptions.aspx) attribute. This lets you define things like the size of result sets or pagination. If we are creating a query that will return just one result, it’s a performant good practice to set the [MaxItemCount](https://msdn.microsoft.com/en-us/library/microsoft.azure.documents.client.feedoptions.maxitemcount.aspx) property to 1:

```cs
var feedOptions = new FeedOptions() { MaxItemCount = 1 };
```

[IQueryable](https://msdn.microsoft.com/en-us/library/azure/bb351562.aspx) can be chained, meaning that following our Type object pattern, we can create queries for different object types based on the same internal function:

```cs
_provider.CreateQuery<OneType>(feedOptions).Where(x => x.Type == "onetype");
_provider.CreateQuery<OtherType>(feedOptions).Where(x => x.Type == "othertype");
```

On the [related repository](https://github.com/ealsur/auth0documentdb/blob/master/Extensions/DocumentDbLinqExtensions.cs) there are a couple of **extensions** that might simplify your queries, like a **TakeOne**, which returns a single object (or null) from a IQuerable:

```cs
var feedOptions = new FeedOptions() { MaxItemCount = 1 };
return  _provider.CreateQuery<SomeClass>(feedOptions).Where(x => x.Type == "someclass" && x.OtherProperty == someValue).TakeOne();
```

Finally, pagination can be achieved through the [RequestContinuation](https://msdn.microsoft.com/en-us/library/microsoft.azure.documents.client.feedoptions.requestcontinuation.aspx#P:Microsoft.Azure.Documents.Client.FeedOptions.RequestContinuation) attribute on the [FeedOptions](https://msdn.microsoft.com/en-us/library/dn948725.aspx#P:Microsoft.Azure.Documents.Client.FeedResponse`1.ResponseContinuation). We obtain this value by querying first and then saving the ResponseContinuation attribute.

```cs
var documentQuery = myIQueryAble.AsDocumentQuery();
var queryResult = await documentQuery.ExecuteNextAsync<T>();
var responseContinuationToken = queryResult.ResponseContinuation;
```

The repository includes an extension to solve this scenario by a [PagedResults](https://github.com/ealsur/auth0documentdb/blob/master/Extensions/DocumentDbLinqExtensions.cs#L28) wrapper:

```cs
public async Task<PagedResults<MyClass>> GetContactAddresses(int size = 10, string continuationToken = "")
{
    var feedOptions = new FeedOptions() { MaxItemCount = size };
    if (!string.IsNullOrEmpty(continuationToken))
    {
        feedOptions.RequestContinuation = continuationToken;
    }
    return  await _provider.CreateQuery<MyClass>(feedOptions).Where(x => x.Type == "myClass").ToPagedResults();
}
```

Notice how we set the **page size** by the MaxItemCount attribute of the FeedOptions.

#### Dependency injection
When working on ASP.NET Core, one of the core features is Dependency Injection. Because of this, it’s vital that our DocumentDB provider is wrapped in a [service](https://github.com/ealsur/auth0documentdb/blob/master/Services/DocumentDbService.cs) that can be injected by an [interface](https://github.com/ealsur/auth0documentdb/blob/master/Services/IDocumentDbService.cs).


A simple way to do this is to create a service class that receives an **IConfiguration** (possibly coming from your [appsettings.json](https://github.com/ealsur/auth0documentdb/blob/master/appsettings.json) file) and creates an instance of our DocumentDbProvider:

```cs
private readonly DocumentDbProvider _provider;
public DocumentDbService(IConfiguration configuration)
{
    _provider = new DocumentDbProvider(new DocumentDbSettings(configuration));
}

```

By implementing an interface, we can maintain a single copy of our service through the **IServiceCollection** available on our [Startup.cs](https://github.com/ealsur/auth0documentdb/blob/master/Startup.cs#L31) file:

```cs
public void ConfigureServices(IServiceCollection services)
{
    services.AddAuthentication(
        options => options.SignInScheme = CookieAuthenticationDefaults.AuthenticationScheme);
    services.AddSingleton<IDocumentDbService>(x=>new DocumentDbService(Configuration.GetSection("DocumentDb")));
    services.Configure<Auth0Settings>(Configuration.GetSection("Auth0"));
    

    services.AddMvc();
    services.AddOptions();
}
```

This way, it’s easy to _inject_ it in an MVC Controller:

```cs
public class ProfileController : Controller
{
    private readonly IDocumentDbService _dbService;
    public ProfileController(IDocumentDbService dbService)
    {
        _dbService = dbService;
    }
}
```

#### Partitions and parallelism in Azure DocumentDB
Collections can **scale dynamically** with Azure DocumentDB’s [partition support](https://azure.microsoft.com/documentation/articles/documentdb-partition-data/#single-partition-and-partitioned-collections). Partitioned collections have a potentially higher throughput and require a Partition Key configuration. Single-partition collections cannot be changed to Partitioned collections, so **plan ahead**: if your application data might grow beyond 10GB or you need more than 10,000 Request Units per second, you might as well evaluate Partitioned collections.

![DocumentDB Partitioned collections](https://images.ctfassets.net/23aumh6u8s0i/5FiPfkTPBGWdpD54j8zlHF/f341e0687f7b7dccf8f8584f3e644f81/partitioned)

Furthermore, each of the operations we described earlier will require an additional Partition Key value as part of the [RequestOptions](https://msdn.microsoft.com/library/microsoft.azure.documents.client.requestoptions.aspx) class.

Partitions help optimize throughput by allowing us to take advantage of parallel queries on multiple collections by using .Net’s [Task Parallel Library](https://msdn.microsoft.com/library/dd460717.aspx).

>For a more detailed look at implementing Partition querying, take a look at the [official sample GitHub repository](https://github.com/Azure/azure-documentdb-dotnet/tree/master/samples/code-samples/Partitioning).

## Aside: Using Auth0 with Azure DocumentDB
Azure DocumentDB can be integrated as a [custom database provider](https://auth0.com/blog/auth0-with-azure-documentdb) by [using the MongoDB protocol](https://azure.microsoft.com/documentation/articles/documentdb-create-mongodb-account/). 

Create a custom database connection by going to the _Connections > Database_ in your [Auth0 management dashboard](https://manage.auth0.com/) and build your MongoDB _connection string_ by obtaining the credentials from your Azure DocumentDB account on the [Azure Portal](https://portal.azure.com):

`mongodb://<your_service_name>:<your_password>==@<your_service_name>.documents.azure.com:10250/auth0?ssl=true` 

You can then use it on your **Database Action Scripts** sections.

For a step by step guide, you can view [Planet-scale authentication with Auth0 and Azure DocumentDB](https://auth0.com/blog/auth0-with-azure-documentdb/)

## Conclusion
Azure DocumentDB is a fast and flexible cloud storage service that will work on almost any use case scenario and can work along with Auth0 in a highly streamlined fashion.
Remember that a **full sample**, including extensions and providers, is [available on GitHub](https://github.com/ealsur/auth0documentdb).  



Using Azure DocumentDB and ASP.NET Core for extreme NoSQL performance

Document your ASP.NET Core Web APIs with Swagger and auto-generate authenticated clients quickly and easily with Autorest.

ASP.NET Core APIs in the fast lane with Swagger and Autorest

6222081fd7dcea7dfb193788d138c457?s=60 avatar

6222081fd7dcea7dfb193788d138c457?s=60

Former Auth0 Employee

Jerrie Pelser

Learn how to use the new OAuth middleware in ASP.NET Core to authenticate a user.

"asp.net-core"