--- title: "AdditionalAuthorizationParameters in ASP.NET Core 9" description: "How AdditionalAuthorizationParameters in ASP.NET Core 9 adds custom parameters to OpenID Connect authorization requests, without workarounds and also with PAR." url: https://nestenius.se/net/additionalauthorizationparameters-in-asp-net-core-9/ date: 2024-12-30 author: "Tore Nestenius" category: ".NET" tags: ["openid-connect", "aspnet-core", "oauth"] site: https://nestenius.se/ --- # AdditionalAuthorizationParameters in ASP.NET Core 9 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](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.authentication.openidconnect.openidconnectoptions.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: ```http 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](https://nestenius.se/net/demystifying-openid-connects-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: ```csharp .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: ```http 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... ¶meter1=value1 ¶meter2=value2 ¶meter3=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, this process is significantly simplified. The new **AdditionalAuthorizationParameters** property, added to [OpenIdConnectOptions](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.authentication.openidconnect.openidconnectoptions), allows developers to configure additional parameters with minimal effort: ```csharp public class OpenIdConnectOptions : RemoteAuthenticationOptions { // ... /// /// Gets the additional parameters that will be included in the authorization request. /// /// /// 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. /// public IDictionary AdditionalAuthorizationParameters { get; } = new Dictionary(); // ... } ``` This lets you achieve the same goal with cleaner, more readable code: ```csharp .AddMyOpenIdConnect(options => { // ... options.AdditionalAuthorizationParameters.Add("parameter1", "value1"); options.AdditionalAuthorizationParameters.Add("parameter2", "value2"); options.AdditionalAuthorizationParameters.Add("parameter3", "value3"); }); ``` This is a much-needed improvement when configuring OpenID Connect, making the code more maintainable. ## 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: ```http 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... ¶meter1=value1 ¶meter2=value2 ¶meter3=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](https://nestenius.se/net/pushed-authorization-requests-par-in-asp-net-core-9/) for the full picture. ## AdditionalAuthorizationParameters vs. AuthenticationProperties [AdditionalAuthorizationParameters](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.authentication.oauth.oauthoptions.additionalauthorizationparameters) lets you append custom parameters to the *initial* OpenID Connect authorization request. [AuthenticationProperties](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.authentication.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 `AdditionalAuthorizationParameters` is a small but focused addition to ASP.NET Core 9 that fills a real gap in the OpenID Connect options model. If you need to pass custom parameters to the authorization endpoint, this is now the clean, built-in way to do it. - Simplifies customizing the initial authorization request. - Only applies to the OpenID Connect authentication handler. - Compatible with Pushed Authorization Requests (PAR). ## Resources - [API Proposal](https://github.com/dotnet/aspnetcore/issues/51250): The original GitHub issue related to this feature — Add `AdditionalAuthorizationParameters` to `OAuthOptions`/`OpenIdConnectOptions`.