Automatically infer `OpenApiSecuritySchemes` from authentication configuration

At the moment, when users enable authentication in their ASP.NET apps, they typically have to manually the describe the OpenApiSecuritySchemes in their application and the top level and configure OpenApiSecurityRequirements for each route that requires authentication and authorization.

We should infer as much of these definitions as possible so users don’t need to configure auth twice, once for their application and another time for OpenAPI.

Provide metadata support for parts of the specification documented in https://swagger.io/docs/specification/authentication/.

[captainsafia]

Who knew auth could be so hard? 🤪

I started experimenting with some of this support in the new Microsoft.AspNetCore.OpenAPI package. The problem is generally easy to solve for cookie and JWT bearer-based authentication types, but OAuth authentication types are a lot trickier for us to derive automatic annotations for because:

• We don’t store any information about what type of grant flow an OAuth implementation uses
• We don’t make it easy for authentication scheme providers to describe what authentication type they are

We’ve had conversations about how to make the authentication system more self-describing for annotation purposes. There’s more design scenarios to reason about here but for .NET 7 we’re scoping it down to auto-generating annotations for JWT-bearer based types to align with the work we’ve done with dotnet user-jwts and the options-from-config changes.

[captainsafia]

I spent some time prototyping what this would look like and landed on a pretty solid strategy that uses PostConfigureOptions on a custom AuthenticationBuilder that would work well for this.

With that in mind, here’s some of the challenges:

• The PostConfigureOptions needs to be added to DI as part of the AddAuthentication call. In my demo, I added this behavior to a custom WebApplicationAuthenticationBuilder that was part of WebApplication. Similar to the model that we tried out in .NET 7 with builder.Authentication. It’s not totally necessary but not having it would mean that this behavior will be enabled for all authentication scenarios in .NET 8.
• The PostConfigureOptions would need to emit OpenApiSecuritySchemes given AuthenticationSchemeOptions but cannot take a dependency on the type since it is not in the shared framework. We could consider packaging it in the shared framework or build a set of intermediary definitions.
• The prototype relies on a global document service existing (see https://github.com/dotnet/aspnetcore/issues/44192) so that the security schemes under components can be populated.