In this post, I’ll share my experience creating a custom Keycloak plugin that adds functionality for email change events. This plugin solves a common integration challenge: how to trigger actions in your application when users change their email addresses through Keycloak.

The Problem: Keeping Systems in Sync After Email Changes

While Keycloak provides excellent user management capabilities out of the box, including email change functionality, it doesn’t natively support notifying external systems when these changes occur. This can be problematic when you need to sync user data across multiple services or perform specific actions after an email change is confirmed.

Building a Keycloak Plugin to Hook Into Email Change Events

To address this challenge, I developed a custom Keycloak extension (plugin) that enhances the built-in email update process. The plugin is implemented as a Keycloak Service Provider Interface (SPI).

Keycloak supports many possible interface extensions allowing addition of custom functionality. More interfaces we take advantage of for example are AbstractClaimMapper to receive identity_provider_uid (the unique identifier provided by identity providers) and org.keycloak.authentication.Authenticator to create a custom step for authentication flow.

The extension consists of two main components:

1. A REST endpoint (update-user-email) – This allows the backend to initiate an email change request. It verifies the request, generates an email verification token, and sends a confirmation email to the new address.
2. A token handler (NeonUpdateEmailActionTokenHandler) – This processes the token when the user clicks the confirmation link, verifies the email update, and ensures data consistency by updating external systems accordingly.

How It Works

1. User Requests an Email Change

When a user requests to change their email, our backend calls the update-user-email endpoint. This is implemented as part of a RealmResourceProvider:

This method:

• Ensures the user is authorized.
• Generates an email verification token.
• Sends a confirmation email to the new address with a verification link.

2. User Confirms the Change

• When the user clicks the verification link, the NeonUpdateEmailActionTokenHandler processes the request. This class is based on UpdateEmailActionTokenHandler.
• The function handleToken gets invoked on email verification link confirmation.
• As part of the email change functionality, we decided to unlink all existing social provider links the user has, as they are based on the email, and by changing the email, the associations with those providers could cause confusion by pointing to the wrong account, potentially causing authentication issues.

This handler:

• Validates the token and the new email.
• Updates the email in Keycloak.
• Verifies the email to prevent additional verification prompts.

3. External Systems are Updated

To maintain data consistency, we update our backend systems after the email change.

notifyExternalService takes care of updating our external service.

How to Set Up the Plugin in Your Keycloak Instance

To use the plugin, you’ll need to:

1. Add a text file that points to the added provider: META-INF/services/org.keycloak.services.resource.RealmResourceProviderFactory
2. Build and deploy the plugin jar to your Keycloak instance:

3. Use update-user-email API extension to on user request to change email.

Final Thoughts

By leveraging Keycloak’s extensibility, this solution provides a secure and efficient way to manage email updates while keeping external systems in sync. It ensures that users go through a verification process before their email is changed and that all relevant systems reflect the update without manual intervention.