# ASP.NET Core OpenID Connect Handler Events

> ASP.NET Core's OpenID Connect handler events, what they are, and why you might want to use them.

The ASP.NET Core [OpenID Connect handler](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.authentication.openidconnect.openidconnecthandler?view=aspnetcore-9.0) exposes events that a client can subscribe to intercept the OpenID Connect protocol flow. Understanding these events is important to understanding how to customize the OpenID Connect protocol flow from the client. Weâll cover each of the events, what they are, and why you might want to subscribe to them.

To use the `OpenIdConnectHandler` in your client applications, you will first need to install the `Microsoft.AspNetCore.Authentication.OpenIdConnect` NuGet package.

```bash
dotnet package add Microsoft.AspNetCore.Authentication.OpenIdConnect
```

Followed by adding the `OpenIdConnectHandler` to your application.

Program.cs

```csharp
builder.Services.AddAuthentication(options =>
    {
        options.DefaultScheme = "cookie";
        options.DefaultChallengeScheme = "oidc";
        options.DefaultSignOutScheme = "oidc";
    })
    .AddCookie("cookie", options =>
    {
        options.Cookie.Name = "__Host-bff";
        options.Cookie.SameSite = SameSiteMode.Strict;
    })
    .AddOpenIdConnect("oidc", options =>
    {
        options.Authority = "https://demo.duendesoftware.com";
        options.ClientId = "interactive.confidential";
        options.ClientSecret = "secret";
        options.ResponseType = "code";
        options.ResponseMode = "query";


        options.GetClaimsFromUserInfoEndpoint = true;
        options.SaveTokens = true;
        options.MapInboundClaims = false;


        options.Scope.Clear();
        options.Scope.Add("openid");
        options.Scope.Add("profile");
        options.Scope.Add("api");
        options.Scope.Add("offline_access");


        options.TokenValidationParameters.NameClaimType = "name";
        options.TokenValidationParameters.RoleClaimType = "role";


    });
```

From here you can use the `options.Events` property to subscribe to the events you want to use. Letâs look at each of the events in more detail.

## OpenID Connect Events

[Section titled âOpenID Connect Eventsâ](#openid-connect-events)

All events either occur before a request is sent to the identity provider, or after a response is received from the identity provider. Understanding the direction of these events can help you determine when to subscribe to them. Letâs call events coming from the identity provider **incoming** and events going to the identity provider **outgoing** for an easier understanding.

| **Event Name**                           | **Usage**    |
| ---------------------------------------- | ------------ |
| `OnAuthenticationFailed`                 | **Incoming** |
| `OnAuthorizationCodeReceived`            | **Incoming** |
| `OnMessageReceived`                      | **Incoming** |
| `OnRedirectToIdentityProvider`           | **Outgoing** |
| `OnRedirectToIdentityProviderForSignOut` | **Outgoing** |
| `OnSignedOutCallbackRedirect`            | **Outgoing** |
| `OnRemoteSignOut`                        | **Incoming** |
| `OnTokenResponseReceived`                | **Incoming** |
| `OnTokenValidated`                       | **Incoming** |
| `OnUserInformationReceived`              | **Incoming** |
| `OnTicketReceived`                       | **Incoming** |
| `OnPushAuthorization` (**.NET 9+ only**) | **Outgoing** |

## Commonly Subscribed Events

[Section titled âCommonly Subscribed Eventsâ](#commonly-subscribed-events)

While there are many events available in the `OpenIdConnectEvents` class, only a few are commonly subscribed. We suggest you start with the most commonly subscribed events and then subscribe to the remaining events as needed.

For ASP.NET Core developers, the most commonly subscribed events are:

1. **`OnRedirectToIdentityProvider`**: Useful for customizing login requests (e.g., appending extra parameters).
2. **`OnRedirectToIdentityProviderForSignOut`**: Often required to customize the behavior of sign-out requests.
3. **`OnTokenValidated`**: Frequently used to customize the claims processing or validate custom claims included in the ID token.
4. **`OnUserInformationReceived`**: Sometimes used to process additional user data retrieved from the UserInfo endpoint (if enabled).

## Descriptions

[Section titled âDescriptionsâ](#descriptions)

### OnAuthenticationFailed

[Section titled âOnAuthenticationFailedâ](#onauthenticationfailed)

* **When called**: Triggered whenever an exception occurs during the authentication process. This event provides an opportunity to handle or log errors.
* **How often**: Only called when an authentication error happens.
* **Example use case**: Use this event to log detailed error messages or display a custom error page to the user instead of the default behavior.
* **Commonly subscribed**: No, unless you need specific error-handling logic.

### OnAuthorizationCodeReceived

[Section titled âOnAuthorizationCodeReceivedâ](#onauthorizationcodereceived)

* **When called**: Invoked after an authorization code is received and before it is redeemed for tokens.
* **How often**: Called once per successful authorization code flow request.
* **Example use case**: Validate the authorization code or add extra functionality (e.g., logging or monitoring) when the code is received.
* **Commonly subscribed**: Rarely, unless custom logic is required before token redemption.

### OnMessageReceived

[Section titled âOnMessageReceivedâ](#onmessagereceived)

* **When called**: Triggered when a protocol message (e.g., an authorization response, logout request) is first received.
* **How often**: Called once per incoming protocol message.
* **Example use case**: Inspect or modify protocol messages for debugging or to handle additional query parameters passed by the identity provider.
* **Commonly subscribed**: No, unless advanced customization is needed.

### OnRedirectToIdentityProvider

[Section titled âOnRedirectToIdentityProviderâ](#onredirecttoidentityprovider)

* **When called**: Invoked when redirecting the user to the identity provider for authentication. You can modify the outgoing authentication request.
* **How often**: Called once per user authentication attempt (e.g., a âloginâ).
* **Example use case**: Add custom query parameters to the request or modify the state parameter.
* **Commonly subscribed**: Yesâoften used to customize the authentication request.

### OnRedirectToIdentityProviderForSignOut

[Section titled âOnRedirectToIdentityProviderForSignOutâ](#onredirecttoidentityproviderforsignout)

* **When called**: Triggered before redirecting the user to the identity provider to start the sign-out process.
* **How often**: Called once per user sign-out request.
* **Example use case**: Modify the logout request, such as appending additional parameters.
* **Commonly subscribed**: Yes, if signing out requires customization.

### OnSignedOutCallbackRedirect

[Section titled âOnSignedOutCallbackRedirectâ](#onsignedoutcallbackredirect)

* **When called**: Invoked after a remote sign-out is completed and before redirecting the user to the `SignedOutRedirectUri`.
* **How often**: Called once per remote sign-out.
* **Example use case**: Log or perform business logic after the remote sign-out.
* **Commonly subscribed**: Rarely, unless additional behavior is needed.

### OnRemoteSignOut

[Section titled âOnRemoteSignOutâ](#onremotesignout)

* **When called**: Called when a remote sign-out request is received on the `RemoteSignOutPath` endpoint.
* **How often**: Called once per incoming remote sign-out request.
* **Example use case**: Perform cleanup tasks such as clearing local session data upon receiving a sign-out request from the identity provider.
* **Commonly subscribed**: Rarely, but important in distributed or multi-tenant systems.

### OnTokenResponseReceived

[Section titled âOnTokenResponseReceivedâ](#ontokenresponsereceived)

* **When called**: Triggered after an authorization code exchange is completed and the token endpoint returns tokens.
* **How often**: Called once per token request.
* **Example use case**: Log or debug the token response, or inspect additional data included in the token response.
* **Commonly subscribed**: No, unless debugging or inspection of tokens is required.

### OnTokenValidated

[Section titled âOnTokenValidatedâ](#ontokenvalidated)

* **When called**: Invoked after the ID token has been validated and an `AuthenticationTicket` has been created.
* **How often**: Called once per token validation process.
* **Example use case**: Add or modify claims in the `ClaimsPrincipal` or validate custom claims included in the token.
* **Commonly subscribed**: Yesâthis is one of the most commonly used events for customizing claims.

### OnUserInformationReceived

[Section titled âOnUserInformationReceivedâ](#onuserinformationreceived)

* **When called**: Triggered when retrieving user information from the UserInfo endpoint (if `GetClaimsFromUserInfoEndpoint = true`).
* **How often**: Called once per user information fetch (e.g., per login).
* **Example use case**: Extend or modify user claims based on the additional information retrieved from the UserInfo endpoint.
* **Commonly subscribed**: Sometimes, if extra claims processing is required.

### OnTicketReceived

[Section titled âOnTicketReceivedâ](#onticketreceived)

* **When called**: Invoked after the OpenID Connect authentication flow is complete and before the authentication ticket is returned.
* **How often**: Called once per successful authentication flow completion.
* **Example use case**: Modify the final authentication ticket, perform additional validation, or execute custom logic before completing the authentication process.
* **Commonly subscribed**: Sometimes, when final authentication customization is needed before completing the flow or for diagnostics and troubleshooting purposes.

### OnPushAuthorization

[Section titled âOnPushAuthorizationâ](#onpushauthorization)

* **When called**: Invoked before sending authorization parameters using the Pushed Authorization Request (PAR) mechanism.
* **How often**: Called once per outgoing PAR-based authorization request.
* **Example use case**: Modify or log pushed authorization parameters.
* **Commonly subscribed**: Rarely, as this is used mainly in advanced scenarios.
-----