[API Proposal]: Add AdditionalAuthorizationParameters to OAuthOptions/OpenIdConnectOptions

[joegoldman2]

Background and Motivation

Today, there's no easy way to add additional parameters to the OAuth/OIDC authorization request.

With OAuth, we have to override OAuthHandler<TOptions>.BuildChallengeUrl as often done in AspNet.Security.OAuth.Providers:

• Apple
• Discord
• Dropbox
• Line
• Reddit
• Twitch
• Zalo

With OIDC, we can use OpenIdConnectEvents.OnRedirectToIdentityProvider like:

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthentication().AddOpenIdConnect(options =>
{
   options.Events.OnRedirectToIdentityProvider = context =>
   {
       context.ProtocolMessage.SetParameter("audience", "api.atlassian.com");
       return Task.CompletedTask;
   };
});

More context: #39243 and #39503

Proposed API

We can introduce a simpler and more generic solution for adding additional parameters:

namespace Microsoft.AspNetCore.Authentication.OAuth;

public class OAuthOptions : RemoteAuthenticationOptions
{
+    public IDictionary<string, string> AdditionalAuthorizationParameters { get; } = new Dictionary<string, string>();
}

namespace Microsoft.AspNetCore.Authentication.OpenIdConnect;

public class OpenIdConnectOptions : RemoteAuthenticationOptions
{
+    public IDictionary<string, string> AdditionalAuthorizationParameters { get; } = new Dictionary<string, string>();
}

Usage Examples

services.AddAuthentication().AddOAuth("Jira", options =>
{
    options.AdditionalAuthorizationParameters.Add("audience", "api.atlassian.com");
});

Risks

Nothing I can think about now.

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

Thanks for contacting us.

We're moving this issue to the .NET 9 Planning milestone for future evaluation / consideration. We would like to keep this around to collect more feedback, which can help us with prioritizing this work. We will re-evaluate this issue, during our next planning meeting(s).
If we later determine, that the issue has no community involvement, or it's very rare and low-impact issue, we will close it - so that the team can focus on more important and high impact issues.
To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[halter73]

Note: API below is for historical reference, but final API shape is in a subsequent comment.

API Review Notes:

• Could we move AdditionalAuthorizationParameters down to the RemoteAuthenticationOptions base type for consistency?
  • This might imply support for handlers that don't really support it.
  • Not much code abstracts over RemoteAuthenticationOptions. Most people deal with the derived types directly.
• What about the AdditionalAuthorizationParameters name?
  • What about AdditionalChallengeQueryParameters?
  • What about AdditionalAuthorizationQueryParameters? Let's do this
• What do we think about exposing an IDictionary in options?
  • We do an ISet<string> for HttpLoggingOptions, and Extensions uses IDictionary in some places
  • We could try merging QueryString structs, but that seems inconvenient and non-standard.

API Approved!

namespace Microsoft.AspNetCore.Authentication.OAuth;

public class OAuthOptions : RemoteAuthenticationOptions
{
+    public IDictionary<string, string> AdditionalAuthorizationQueryParameters { get; }
}

namespace Microsoft.AspNetCore.Authentication.OpenIdConnect;

public class OpenIdConnectOptions : RemoteAuthenticationOptions
{
+    public IDictionary<string, string> AdditionalAuthorizationQueryParameters { get; }
}

[halter73]

@amcasey It turns out that even though these parameters are normally query string parameters, they can be form posts too if you set Options.AuthenticationMethod == OpenIdConnectRedirectBehavior.FormPost. Given that I now support the API as originally proposed without "Query" in the name, but I'll just remove the api-approved label for now, so we can wait until the normal Monday API review meeting to see if everyone else is onboard.

I still think the doc comments should point out that these parameters are typically part of the redirect query string.

You could even encode request parameters as JWTs, but I don't think our stack supports that.