[Breaking change]: Changes in default authentication scheme handling for ASP.NET Core

[captainsafia]

Description

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

Previously, users were always required to set the default authentication scheme that would be used by authentication and authorization handlers, like so:

builder.Services.AddAuthentication("MyDefaultScheme");

Moving forward, when (and only when) a single authentication scheme is registered, that scheme will be treated as the default scheme. For example, "foobar" will be treated as the default scheme in the code below.

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

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

Version

.NET 7 Preview 7

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

Moving forward, if (and only if) a single scheme is registered in an application, that scheme will be treated as the default. In the code below, the CookieDefaults.AuthenticationScheme will be treated as the default scheme.

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

However, in the code snippet below, no default will be set because multiple schemes are registered.

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

Type of breaking change

• Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load/execute or different run-time behavior.
• Source incompatible: Source code may encounter a breaking change in behavior when targeting the new runtime/component/SDK, such as compile errors or different run-time behavior.
• Behavioral change: Existing code and binaries may experience different run-time behavior.

Reason for change

To reduce boilerplate when configuring authentication and set up sensible defaults.

Recommended action

The change only impacts applications with 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, the options associated with that scheme should be configured correctly.

Alternatively, this behavior can be disabled by setting the Microsoft.AspNetCore.Authentication.SuppressAutoDefaultScheme app context flag.

Affected APIs

Authentication APIs.