Edit

Default authentication scheme

  • Article

Starting in .NET 7, we introduced new behavior in the authentication area in ASP.NET Core.

Previously, users were required to set the default authentication scheme, which is used by authentication and authorization handlers, in the AddAuthentication call:

builder.Services.AddAuthentication("MyDefaultScheme");

Moving forward, when a single authentication scheme is registered, that scheme is treated as the default scheme. For example, "MyDefaultScheme" is treated as the default scheme in the following code.

builder.Services.AddAuthentication().AddOAuth("MyDefaultScheme");

This change might expose unintended behavior changes in applications, such as authentication options being validated earlier than expected.

Version introduced

ASP.NET Core 7.0

Previous behavior

Previously, when users did not provide a default scheme in the AddAuthentication call, no default scheme was set.

builder.Services.AddAuthentication().AddCookie();

This impacted the behavior of authentication handlers in the application layer.

New behavior

Starting in ASP.NET Core 7.0, if (and only if) a single scheme is registered in an application, that scheme is treated as the default. In the following code, the CookieDefaults.AuthenticationScheme is treated as the default scheme.

builder.Services.AddAuthentication().AddCookie();

However, in the next code snippet, no default is set because multiple schemes are registered.

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

Type of breaking change

This change affects binary compatibility.

Reason for change

This change was made to reduce boilerplate when configuring authentication and to set up sensible defaults.

The change only impacts applications that have a single scheme registered. For those scenarios, it's recommended to ensure that your application is prepared to handle the assumption that a single scheme is the default. For example, ensure that the options associated with that scheme are configured correctly.

Alternatively, you can disable the new behavior by setting the Microsoft.AspNetCore.Authentication.SuppressAutoDefaultScheme app context flag.

Affected APIs

Authentication APIs.