Customizing KeyCloak Actions: A Step-by-Step Guide for Beginners
Whether you're a seasoned software expert, a diligent business professional, or a newbie, remember this: customization will be your ally in enhancing digital security.
To create a custom required action in KeyCloak, you'll need to follow these steps:
Step - 1: Create a JAR file containing the required action code
The first step is to create a Java Archive (JAR) file containing the required action code. This code will define the behaviour of the required action, including what happens when a user completes it and what data is collected during the process.
Step - 2: We will need to implement two interfaces of KeyCloak.
1. RequiredActionFactory
2. RequiredActionProvider
The RequiredActionFactory interface is responsible for creating the Instance of the RequiredActionProvider.
@Override
public RequiredActionProvider create(KeycloakSession session) {
return new CustomRequiredActionProvider();
}
@Override
public String getId() {
return āCustom_Actionā;
}
@Override
public String getDisplayText() {
return "Secret Question";
}
We need to implement these methods from RequiredActionFactory in our CustomFactory.
The create method is used to return the instance of our RequiredActionProvider.
The getId method is used to set the id of our custom required action provider for keycloak to access it.
The getDisplayText method is used to show a familiar name in the admin console.
Step - 3:
After implementing RequiredActionFactory, we will implement RequiredActionProvider interface.
@Override
public void requiredActionChallenge(RequiredActionContext context) {
Response challenge = context.form().createForm("secret_question_config.ftl");
context.challenge(challenge);
}
The first method to implement is requiredActionChallenge method. This method is the initial call by the flow manager. It is responsible for rendering the HTML page required for initiating the required action.
In this method, the form method of RequiredActionContext class returns an instance of FreeMarkerLoginFormsProvider (implementing class of LoginFormsProvider). The createForm method of FreeMarkerLoginFormsProvider is used for rendering the HTML form.
createForm method takes a string as an argument which needs to be the name of the 'FTL' file.
The challenge method of RequiredActionContext class notifies the flow manager that a required action must be executed.
@Override
public void processAction(RequiredActionContext context) {
MultivaluedMap formData = context.getHttpRequest().getDecodedFormParameters();
//Business Logic
context.success();
}
Step - 4:
The next method to implement is processAction. This method is called to process the input from the HTML form. The action URL of the form will route to processAction method.
The form data is received from context.getHttpRequest().getDecodedFormParameters() method.
Step - 5:
After completing the business logic context.success() notifies the flow manager that the required action was successful.
You will package your classes within a single jar. This jar does not have to be separate from other provider classes but it must contain a file named org.keycloak.authentication.RequiredActionFactory and must be contained in the META-INF/services/ directory of your jar. This file must list the fully qualified class name of each RequiredActionFactory implementation you have in the jar.
For example:
org.keycloak.examples.authenticator.SecretQuestionRequiredActionFactory
This service (or file) is used by Keycloak to scan the providers it has to load into the system.
Step - 6: Deploy the JAR file to the KeyCloak server
Once you have the JAR file, you'll need to deploy it to the KeyCloak server. This can be done by copying the file directly to the server's deployment directory i.e., the providers/ directory.
Step - 7: Register the required action in KeyCloak
The final thing you have to do is go into the Admin Console. Click on the Authentication left menu. Click on the Required Actions tab. Click on the Register button and choose your new Required Action. Your new required action should now be displayed and enabled in the required actions list.