diff --git a/aspnetcore/diagnostics/asp0028.md b/aspnetcore/diagnostics/asp0028.md new file mode 100644 index 000000000000..f570c7b9327e --- /dev/null +++ b/aspnetcore/diagnostics/asp0028.md @@ -0,0 +1,49 @@ +`IPv6Any` is preferred to `Any` because `Any` is slower than `IPv6Any`. In some cases, `Any` may not work at all. `Any` has performance problems due to the [underlying System types implementation](https://github.com/dotnet/runtime/issues/82404). + +`127.0.0.1` is the IPv4 loopback address. `::1` is the IPv6 loopback address. `Any` is the wildcard address for IPv4. `IPv6Any` is the wildcard address for IPv6. + +Currently, when using HTTP/1.x or HTTP/2.0: + +* `localhost` resolve to `[::1]`. +* `[::1]` isn't accepted by the server, which forces a retry using `127.0.0.1`, and the cycle continues. + +Using `Any` with the preceding conditions is reported with a diagnostic message: + +```csharp +.UseKestrel().ConfigureKestrel(options => +{ + options.Listen(IPAddress.Any, ...); +}) +``` + +## Rule description + +The recommended way to configure Kestrel to listen for incoming connections on all available `IPv6` network interfaces is with `IPv6Any`. + +## How to fix violations + +For the problematic code, replace `Any` with `IPv6Any`: + +```diff +.UseKestrel().ConfigureKestrel(options => +{ +- options.Listen(IPAddress.Any, ...); ++ options.Listen(IPAddress.IPv6Any, ...); +}) +``` + +Alternatively, use the `ListenAnyIP` method without specifying any argument: + +```diff +.UseKestrel().ConfigureKestrel(options => +{ +- options.Listen(IPAddress.Any, ...); ++ options.ListenAnyIP(...); +}) +``` + +## When to suppress warnings + +The `ASP0028` diagnostic has a Information level severity. Suppress warnings if your intention is to disable `IPv6` usage completely on the server, although this comes with the risk of the performance problems mentions in this article + +`IPv6` can be disabled either system-wide, or for .NET only via the [AppCtx switch or environment variable](https://devblogs.microsoft.com/dotnet/dotnet-6-networking-improvements/#an-option-to-globally-disable-ipv6) diff --git a/aspnetcore/toc.yml b/aspnetcore/toc.yml index 5c8c55da4d3d..640a30142a41 100644 --- a/aspnetcore/toc.yml +++ b/aspnetcore/toc.yml @@ -1496,6 +1496,8 @@ items: uid: security/authentication/index - name: Choose an identity solution uid: security/how-to-choose-identity + - name: Configure OpenID + uid: security/authentication/configure-oidc-web-authentication - name: ASP.NET Core Identity items: - name: Overview