Keycloak Required Action Redirect

This is a simple keycloak extension which implements the keycloak required action SPI. This extension allows you to redirect users to the specified URL after successful login.

What is it good for?

Keycloak does not provide built-in support for differentiating between a first-time login (registration) and a regular login when handling redirect URLs. By default, both scenarios follow the same authentication flow, making it difficult to direct new users to a specific onboarding page while allowing returning users to proceed normally. This keycloak extenstion solves described limitaton by assigning required action to all new registered users. After that you can follow two paths:

• Redirect user once on the first login, required action is marked as executed and all other logins will follow default redirect.
• Redirect user for each login, until you manually remove required action for the user either using keycloak API or keycloak admin interface.

How to install?

Download a release (*.jar file) that works with your Keycloak version from the list of releases. Follow the below instructions depending on your distribution and runtime environment.

Standalone (without container)

Copy the jar to the providers folder and execute the following command:

${kc.home.dir}/bin/kc.sh build

Container image (Docker)

For Docker-based setups mount or copy the jar to /opt/keycloak/providers.

If you are using RedHat SSO instead of Keycloak open source, mount or copy the jar to /opt/eap/providers/.

volumes:
      - ./keycloak-redirect-26.1.0.jar:/opt/keycloak/providers/keycloak-redirect-26.1.0.jar

How to configure?

spi-required-action-REDIRECT-URL=https://google.com

For details on SPI and provider configuration, please refer to Configuring providers guide.

To enable this extension:

• Go to your realm
• On the left navigation block click Authentication
• Select Required actions tab
• Find and enable Redirect action
• Set as default action

Every new user will have this required action assigned to them.

To assign this required action to specific user:

• Go to your realm
• On the left navigation block click Users
• Find and select a user
• On the Details tab of the selected user find Required user actions input
• Find and add Redirect action

How to build locally?

Run following commands\

docker build -t keycloak-redirect .

docker run --rm -v ./output:/app/output keycloak-redirect

You will find jar in the output folder

Thanks

A shout-out to Lawlink for being an incredible place to work and innovate. This extension was born out of the challenges and inspirations I encountered there. Visit lawlink.de for more about their work.