Product Development and Consulting in Digital Security, Data Science and Enterprise Architecture:

Keycloak Error Handling: Solution to Redirecting Users to Default Error Page

Post date May 30, 2025

Author: gopalsharma2001

226 | 0 | 0

Description:

When integrating federated identity providers with Keycloak, ensuring a smooth user authentication experience is crucial. One common issue that can disrupt this experience is improper error handling, leading to users being redirected to a default page instead of completing the federated authentication process. This blog post delves into this specific Keycloak error handling mechanism and explores potential solutions.

Keycloak is an open-source identity and access management solution that simplifies the process of securing applications and services. Its powerful features include single-sign-on (SSO), social login, and user federation. Keycloak's federated authentication allows users to log in using external identity providers (IdPs) like Google, Facebook, or other SAML/OIDC systems. When an error occurs during this process (e.g., IdP unavailable, user cancels login, authentication failure), Keycloak needs a strategy to handle it. The default behavior is often to redirect to a standard error page. Although, there's a parameter called 'redirect_uri' that can be used in authorization requests. But for some errors (e.g., invalid redirect_uri, unrecognized client_id, a FreeMarker template error, or custom errors in custom authenticators), Keycloak ignores this and uses its own error page. And Keycloak has a reason to adopt this behavior. When using custom authenticators with custom errors, Keycloak is unable to determine the specific type of error encountered. If the redirect_uri is invalid, redirecting the user to it poses a security risk because Keycloak cannot verify the URL against the client's whitelisted configuration. Keycloak has addressed this issue by customizing the error page. If the client_id is valid, it displays a link below the error message that directs the user to the client's home URL. If the client_id is invalid, the standard error page is shown. This behavior of Keycloak appears to be consistent with the OAuth 2.0 spec.

The Problem: Redirecting to a Default Error Page

In some configurations or scenarios, Keycloak might redirect users to a generic default error page when an issue occurs during federated authentication, causing the users to stick to an error page and not know what to do. This is not ideal because:

• Poor User Experience: Users get stuck and don't know what to do.
• Lost Opportunities: Users might have other authentication options (e.g., local Keycloak login) that they can't access.
• Support Overhead: Increases support requests as users are confused.

Solutions and Best Practices

To handle federated authentication errors in Keycloak more effectively, you should implement these strategies:

1. Customize Error Handling: 

• Authentication Flows: Keycloak's authentication flows are highly customizable. You can create custom flows or modify existing ones to handle errors more gracefully. This involves:

• Error Handling in Flows:

Within the authentication flow, you can add steps to check for specific error conditions and redirect the user to appropriate pages or actions. It requires a combination of Keycloak's administrative console configuration and potentially custom Java authenticators for more complex logic.

Keycloak's authentication process is defined by "flows" (e.g., "Browser Flow," "Registration Flow"). These flows are composed of "executions," which are individual steps or authenticators. Each execution can have different outcomes (e.g., SUCCESS, FAILURE, ATTEMPTED). By manipulating these outcomes and introducing conditional logic, you can control the user's journey, including redirects on error.

                Step-by-Step Configuration in Keycloak Admin Console

This is the most common approach for basic to moderately complex error handling.

1. Duplicate the standard flow (e.g. “Browser”) or the authentication flow in use.
2. Identify the point of failure, aka “execution”, in the flow that is likely to fail during federated authentication (e.g., Identity Provider Redirector, IdP Discovery, or a specific IdP authenticator).
3. Add a conditional branch or a sub-flow below the point of failure. Configure requirement attribute of the branch to REQUIRED. Inside the branch define what happens on error.
4. Configure the “conditions” for the executions inside the conditional branch.

                Implementing with a Custom Java Authenticator (for Advanced Scenarios)

For truly dynamic or complex error handling (e.g., parsing specific IdP error codes, dynamic redirects based on user roles, or a FreeMarker template error), you'll need a custom Java authenticator. This can perform custom logic, set appropriate error messages, and redirect the user to appropriate pages based on conditions. Please refer Keycloak Authentication SPI for more details on how to implement custom authenticator.

1. Create a custom authenticator by implementing the org.keycloak.authentication.Authenticator and org.keycloak.authentication.AuthenticatorFactory class.

 

import org.keycloak.Config;
import org.keycloak.authentication.AuthenticationFlowContext;
import org.keycloak.authentication.Authenticator;
import org.keycloak.authentication.AuthenticatorFactory;
import org.keycloak.models.*;
import org.keycloak.provider.ProviderConfigProperty;

import java.util.List;

public class CustomAuthenticator implements Authenticator, AuthenticatorFactory {
    @Override
    public void authenticate(AuthenticationFlowContext authenticationFlowContext) {

    }

    @Override
    public void action(AuthenticationFlowContext authenticationFlowContext) {

    }

    @Override
    public boolean requiresUser() {
        return false;
    }

    @Override
    public boolean configuredFor(KeycloakSession keycloakSession, RealmModel realmModel, UserModel userModel) {
        return false;
    }

    @Override
    public void setRequiredActions(KeycloakSession keycloakSession, RealmModel realmModel, UserModel userModel) {

    }

    @Override
    public Authenticator create(KeycloakSession keycloakSession) {
        return null;
    }

    @Override
    public void init(Config.Scope scope) {

    }

    @Override
    public void postInit(KeycloakSessionFactory keycloakSessionFactory) {

    }

    @Override
    public void close() {

    }

    @Override
    public String getId() {
        return "";
    }

    @Override
    public String getDisplayType() {
        return "";
    }

    @Override
    public String getReferenceCategory() {
        return "";
    }

    @Override
    public boolean isConfigurable() {
        return false;
    }

    @Override
    public AuthenticationExecutionModel.Requirement[] getRequirementChoices() {
        return new AuthenticationExecutionModel.Requirement[]{AuthenticationExecutionModel.Requirement.REQUIRED,
                AuthenticationExecutionModel.Requirement.ALTERNATIVE,
                AuthenticationExecutionModel.Requirement.DISABLED};
    }

    @Override
    public boolean isUserSetupAllowed() {
        return false;
    }

    @Override
    public String getHelpText() {
        return "";
    }

    @Override
    public List<ProviderConfigProperty> getConfigProperties() {
        return List.of();
    }
}

2. Override methods like authenticate, action, requiredActions, or any other required methods for your specific need.
3. Inside the authenticate or action method, access the AuthenticationFlowContext to get information about the current authentication session, RealmModel, ClientModel, and any errors. For example, context.getAuthenticationSession().getAuthNote() often will return specific error messages.
4.  Based on the error, you can:
   1. context.challenge(response): Render a custom FreeMarker template with your error message.
   2. context.attempted(): Indicate the attempt failed but the flow should continue.
   3. context.failure(AuthenticationFlowError.PROVIDER_ERROR): Mark a general failure.
   4. context.success(): Continue the flow.
   5. context.cancelLogin(): Abort the login process.
   6. Redirect: context.fork() or context.redirectUri(uri).challenge() can be used for redirects, but often it's simpler to set specific outcomes that the flow handles.

 

@Override
    public void authenticate(AuthenticationFlowContext authenticationFlowContext) {
        try {
            // Proceed with federated auth
            // load custom template
            LoginFormsProvider form = authenticationFlowContext.form();
            Response challenge = form.createForm("custom-form.ftl");
            // handle template error
            if (areResponsesEqual(challenge, Response.serverError().build())) {
                handleError(authenticationFlowContext, "TEMPLATE_PROCESSING_ERROR", "Failed to process template");
                return;
            }
            authenticationFlowContext.challenge(challenge);
        } catch (Exception e) {
            // Redirect to client-specific error page
            handleError(authenticationFlowContext, "error", "auth_failed");
        }

    }

    private void handleError(AuthenticationFlowContext context, String error, String errorMessage) {
        Map<String, String> queryParams = new HashMap<>();
        queryParams.put("error", error);
        queryParams.put("error_description", errorMessage);
        String redirectURL = context.getAuthenticationSession().getRedirectUri(); // specific redirectURL can be used for specific needs.
        String updatedRedirectURL = getUpdatedRedirectURL(queryParams, redirectURL);
        context.getEvent().error(errorMessage);
        if (updatedRedirectURL != null && !updatedRedirectURL.isEmpty()) {
            Response errorResponse = null;
            try {
                errorResponse = Response.status(302)
                        .location(new URI(redirectURL))
                        .build();
            } catch (URISyntaxException e) {
                throw new RuntimeException(e);
            }
            context.failure(AuthenticationFlowError.GENERIC_AUTHENTICATION_ERROR, errorResponse);
        }
    }

    private String getUpdatedRedirectURL(Map<String, String> queryParams, String redirectUrl) {
        URI uri;
        String redirectURL;
        try {
            StringBuilder builder = new StringBuilder();
            uri = new URI(redirectUrl);
            String query = uri.getQuery();
            if (query != null)
                builder.append(query);

            for (Map.Entry<String, String> entry : queryParams.entrySet()) {
                String keyValueParam = entry.getKey() + "=" + entry.getValue();
                if (!builder.toString().isEmpty())
                    builder.append("&");

                builder.append(keyValueParam);
            }
            redirectURL = new URI(uri.getScheme(), uri.getAuthority(), uri.getPath(), builder.toString(), uri.getFragment()).toString();
        } catch (URISyntaxException ex) {
            throw new RuntimeException(ex);
        }
        return redirectURL;
    }

    public boolean areResponsesEqual(Response r1, Response r2) {
        if (r1 == r2) {
            return true;
        }
        if (r1 == null || r2 == null) {
            return false;
        }
        if (r1.getStatus() != r2.getStatus()) {
            return false;
        }
        Object entity1 = r1.getEntity();
        Object entity2 = r2.getEntity();
        return (entity1 == null && entity2 == null) || (entity1 != null && entity1.equals(entity2));
    }

 

5. Register the custom authenticator by deploying the JAR to Keycloak's providers/ directory and adding it to your authentication flow via Admin Console.

• Custom Error Pages: You can create custom error pages that provide more informative messages and options to the user (e.g., "Login with local account," "Try a different provider," "Contact support").

• Event Listeners: Keycloak emits events during the authentication process. You could use event listeners to handle errors, but it's generally more straightforward to use Authentication Flows for most error-handling scenarios. You can create custom event listeners to intercept errors and perform actions such as:
  • Logging: Log detailed error information for debugging.
  • Redirecting: Dynamically redirect the user based on the error type.
  • Displaying Messages: Show user-friendly error messages.

2. Logging and Monitoring:

• Detailed Logging: Implement comprehensive logging to capture all authentication-related events, including errors. This will help you diagnose problems and improve your error handling.
• Monitoring: Monitor authentication error rates to detect issues early and proactively address them.

Summary

Don't let Keycloak's default error page trap your users. By implementing robust error handling, customizing authentication flows, and providing clear guidance, you can create a much smoother and more user-friendly authentication experience.