diff --git a/docs/en/Community-Articles/2025-02-04-OpenIddict-Custom-Logic/POST.md b/docs/en/Community-Articles/2025-02-04-OpenIddict-Custom-Logic/POST.md new file mode 100644 index 0000000000..f5602650ae --- /dev/null +++ b/docs/en/Community-Articles/2025-02-04-OpenIddict-Custom-Logic/POST.md @@ -0,0 +1,114 @@ +# Customizing Authentication Flow with OpenIddict Events in ABP Framework + +[ABP's OpenIddict Module](https://abp.io/docs/latest/modules/openiddict) provides an integration with the [OpenIddict](https://github.com/openiddict/openiddict-core) library, which provides advanced authentication features like **single sign-on**, **single log-out**, and **API access control**. + +OpenIddict provides an event-driven model ([event models](https://documentation.openiddict.com/introduction#events-model)) that allows developers to customize authentication and authorization processes. This event model enables handling actions such as user **sign-in**, **sign-out**, **token validation**, and **request handling** dynamically. + +In this article, we will explore OpenIddict event models, their key use cases, and how to implement them effectively. + +## Understanding OpenIddict Event Model + +OpenIddict events are primarily used within the OpenIddict server component. These events provide hooks into the OpenID Connect flow, allowing developers to modify behavior at different stages of authentication & authorization processes. + +They are triggered during critical moments such as: + +* User authentication (sign-in) +* Session termination (sign-out) +* Token validation and generation +* Request processing +* Error handling + +OpenIddict provides multiple server events, under the `OpenIddictServerEvents` static class to make them easier to find (also provides additonal validation events under the `OpenIddictValidationEvents` static class). + +Here are some of the pre-defined `OpenIddictServerEvents`: + +![](openiddict-server-events.png) + +Each event represents a specific checkpoint in the **request processing pipeline**, such as validating an OpenID Connect request, extracting request parameters, processing the request, or generating a response. As an application developer, you simply need to create event handlers that subscribe to these predefined events to implement your custom logic at the desired pipeline stage. + +## Example: How to add custom logic when a user signs out? + +Let's walkthrough a practical example of implementing custom sign-out logic using OpenIddict events. + +### Step 1: Create a Custom Event Handler + +First, create a handler that implements `IOpenIddictServerHandler`: + +```csharp +using System.Threading.Tasks; +using OpenIddict.Server; + +namespace MySolution; + +public class SignOutEventHandler : IOpenIddictServerHandler +{ + public static OpenIddictServerHandlerDescriptor Descriptor { get; } + = OpenIddictServerHandlerDescriptor.CreateBuilder() + .UseSingletonHandler() + .SetOrder(100_000) + .SetType(OpenIddictServerHandlerType.Custom) + .Build(); + + public ValueTask HandleAsync(OpenIddictServerEvents.ProcessSignOutContext context) + { + // Implement your custom sign-out logic here + + // Examples: + // - Clear custom session data + // - Perform audit logging + // - Notify other services + // - Clean up user-specific resources + + return ValueTask.CompletedTask; + } +} +``` + +The handler configuration includes several important components: + +* `Descriptor` - Defines how the handler should be registered and executed +* `SetOrder` - Determines the execution order when multiple handlers exist +* `SetType` - Specifies this as a custom handler implementation +* `UseSingletonHandler` - Sets lifetime of the class as _Singleton_ + +### Step 2: Register the Event Handler + +Register your custom handler in your application's module configuration: + +```csharp +//... + +public class MySolutionAuthServerModule : AbpModule +{ + public override void PreConfigureServices(ServiceConfigurationContext context) + { + PreConfigure(serverBuilder => + { + serverBuilder.AddEventHandler(SignOutEventHandler.Descriptor); + }); + } + + //... +} +``` + +That's it! After these steps, your `SignOutEventHandler.HandleAsync()` method should be triggered after each signout request. You can also use other pre-defined server events for other stages of the authentication & authorization processes such as; + +* `OpenIddictServerEvents.ProcessSignInContext` -> after each sign-in, +* `OpenIddictServerEvents.ProcessErrorContext` -> when an error occurs in the authentication, +* `OpenIddictServerEvents.ProcessChallengeContext` -> called when processing a challenge operation, +* and other 40+ server events... + +Each event provides access to the relevant context, allowing you to access and modify the authentication flow's behavior. + +## Conclusion + +ABP Framework integrates OpenIddict as its authentication and authorization module. OpenIddict provides an event-driven model that allows developers to customize authentication and authorization processes within their ABP applications. It's pre-installed & pre-configured in the ABP's startup templates. + +OpenIddict provides a powerful and flexible way to customize authentication flows. By leveraging these events, developers can implement complex authentication scenarios while maintaining clean, maintainable code. + +## References + +* [OpenIddict Documentation](https://documentation.openiddict.com/introduction#events-model) +* [ABP OpenIddict Module Documentation](https://abp.io/docs/latest/modules/openiddict) +* [Advanced OpenIddict Scenarios](https://kevinchalet.com/2018/07/02/implementing-advanced-scenarios-using-the-new-openiddict-rc3-events-model/) \ No newline at end of file diff --git a/docs/en/Community-Articles/2025-02-04-OpenIddict-Custom-Logic/cover-image.png b/docs/en/Community-Articles/2025-02-04-OpenIddict-Custom-Logic/cover-image.png new file mode 100644 index 0000000000..11d9ff05ea Binary files /dev/null and b/docs/en/Community-Articles/2025-02-04-OpenIddict-Custom-Logic/cover-image.png differ diff --git a/docs/en/Community-Articles/2025-02-04-OpenIddict-Custom-Logic/openiddict-server-events.png b/docs/en/Community-Articles/2025-02-04-OpenIddict-Custom-Logic/openiddict-server-events.png new file mode 100644 index 0000000000..3514304f15 Binary files /dev/null and b/docs/en/Community-Articles/2025-02-04-OpenIddict-Custom-Logic/openiddict-server-events.png differ