In ASP.NET Core 9, a new feature called AdditionalAuthorizationParameters allows you to customize OAuth and OpenID Connect (OIDC) flows more quickly. This new feature allows developers to add custom authentication parameters without needing to rely on the complex workarounds that existed before ASP.NET Core 9 was released. Sounds familiar? Then you’re going to like this!

In this blog, I will practically introduce you to this feature, how it works, and how it ties together with Pushed Authorization Requests and AuthenticationProperties. Let’s jump in.

Why do we need AdditionalAuthorizationParameters?

Before ASP.NET Core 9, adding custom parameters to OAuth or OpenID Connect (OIDC) authorization requests was a cumbersome challenge. Developers had to override methods like BuildChallengeUrl in custom OAuth handlers or insert parameters manually using event hooks such as OnRedirectToIdentityProvider. This approach was verbose and error-prone, often leading to inconsistent project implementations.

AdditionalAuthorizationParameters solves this by providing a more straightforward and maintainable approach by including custom parameters directly in the authorization request configuration.

What Does Adding Custom Parameters Mean?

Customizing the initial authorization request sent to an OIDC authorization server often involves adding extra parameters to control or enhance the authentication process. A typical authorization request might look like this:

GET https://identityservice.secure.nu/connect/authorize
    ?client_id=localhost-addoidc-client
    &redirect_uri=https%3A%2F%2Flocalhost%3A5001%2Fsignin-oidc
    &response_type=code
    &scope=openid%20profile%20email%20offline_access
    &code_challenge=dtaF1NHSE5-C6E9eDuf-kEZJ_j7n48BaSTmezd4Go7Y
    &code_challenge_method=S256
    &response_mode=form_post
    &nonce=638645227425598693.OGFkYjhmMWUtZ...
    &state=CfDJ8IgPXRNAZH1EkNA0dd3_JvsHlnov...
    &x-client-SKU=ID_NET9_0
    &x-client-ver=8.1.2.0 HTTP/1.1

Sometimes, you may need to add extra parameters to further customize the authentication flow — for example, adding an audience, a tenant ID, or setting a specific prompt behavior.

Curious about what state and nonce contain? See Demystifying OpenID Connect’s State and Nonce Parameters in ASP.NET Core for more details.

The Old Way: Complex Workarounds

Before .NET 9, adding custom parameters often forced developers to resort to convoluted methods, such as:

.AddOpenIdConnect(options =>
{
    // ...
    options.Events.OnRedirectToIdentityProvider = context =>
    {
        context.ProtocolMessage.SetParameter("parameter1", "value1");
        context.ProtocolMessage.SetParameter("parameter2", "value2");
        context.ProtocolMessage.SetParameter("parameter3", "value3");
        return Task.CompletedTask;
    };
});

This results in an authorization request like:

GET https://identityservice.secure.nu/connect/authorize
    ?client_id=localhost-addoidc-client
    &redirect_uri=https%3A%2F%2Flocalhost%3A5001%2Fsignin-oidc
    &response_type=code
    &scope=openid%20profile%20email%20offline_access
    &code_challenge=dtaF1NHSE5-C6E9eDuf-kEZJ_j7n48BaSTmezd4Go7Y
    &code_challenge_method=S256
    &response_mode=form_post
    &nonce=638645227425598693.OGFkYjhmMWUtZ...
    &parameter1=value1
    &parameter2=value2
    &parameter3=value3
    &state=CfDJ8IgPXRNAZH1EkNA0dd3_JvsHlnov...
    &x-client-SKU=ID_NET9_0
    &x-client-ver=8.1.2.0 HTTP/1.1

While this approach worked, it required extra boilerplate and was far from intuitive.

How Does AdditionalAuthorizationParameters Improve This?

In ASP.NET Core 9, the process is significantly simplified. The new AdditionalAuthorizationParameters property, added to OpenIdConnectOptions, allows developers to configure additional parameters with minimal effort:

public class OpenIdConnectOptions : RemoteAuthenticationOptions
{
    // ...
    /// <summary>
    /// Gets the additional parameters that will be included in the authorization request.
    /// </summary>
    /// <remarks>
    /// The additional parameters can be used to customize the authorization request,
    /// providing extra information or fulfilling specific requirements of the
    /// OpenIdConnect provider. These parameters are typically, but not always,
    /// appended to the query string.
    /// </remarks>
    public IDictionary<string, string> AdditionalAuthorizationParameters { get; }
        = new Dictionary<string, string>();
    // ...
}

This lets you achieve the same goal with cleaner, more readable code:

.AddMyOpenIdConnect(options =>
{
    // ...
    options.AdditionalAuthorizationParameters.Add("parameter1", "value1");
    options.AdditionalAuthorizationParameters.Add("parameter2", "value2");
    options.AdditionalAuthorizationParameters.Add("parameter3", "value3");
});

A much-needed improvement when configuring OpenID Connect — the code stays closer to configuration and further from ceremony.

What About Pushed Authorization Requests (PAR)?

The feature is also compatible with Pushed Authorization Requests (PAR). When using PAR, the request with AdditionalAuthorizationParameters might look like this:

POST https://identityservice.nu/connect/par HTTP/1.1
Host: identityservice.secure.nu
User-Agent: Microsoft ASP.NET Core OpenIdConnect handler
Content-Type: application/x-www-form-urlencoded

client_id=localhost-addoidc-client
&redirect_uri=https%3A%2F%2Flocalhost%3A5001%2Fsignin-oidc
&response_type=code
&scope=openid+profile+email+offline_access
&code_challenge=oIDRmjhH7UJXLaGXFNxbU5obKYXk8lMfj-OSsP73DmQ
&code_challenge_method=S256
&response_mode=form_post
&nonce=638645236162573853jIyMzc5...
&parameter1=value1
&parameter2=value2
&parameter3=value3
&state=CfDJ8IgPXRNAZH1EkNA0dd3_...
&client_secret=mysecret

The additional parameters are seamlessly included in the PAR request, keeping the feature compatible with modern authorization flows.

Curious about PAR? See Pushed Authorization Requests (PAR) in ASP.NET Core 9 for the full picture.

AdditionalAuthorizationParameters vs. AuthenticationProperties

AdditionalAuthorizationParameters lets you append custom parameters to the initial OpenID Connect authorization request.

AuthenticationProperties serves a different purpose — handling transient data stored alongside the authentication flow, such as redirection URLs or other metadata relevant to the sign-in process.

Summary

  • Simplifies customizing the initial authorization request.
  • Only applies to the OpenID Connect authentication handler.
  • Compatible with Pushed Authorization Requests (PAR).

Resources

  • API Proposal — Add AdditionalAuthorizationParameters to OAuthOptions/OpenIdConnectOptions.