keycloak-rest-authenticator

REST AUTHENTICATOR for Keycloak

It happens that you want to use keycloak and customize it but

• you do not want to use java and its heavy development framework
• you want to use light microservices to implement authenticator business logic
• you are happy to use typescript as a development language

REST Authenticator is simplifying keycloak aithenticators for you

Get started

1. run a keycloak with script function enabled (but not necessarily the upload_script)
2. clone the repository
3. run npm i
4. configure a .env file from the .env.example to setup the variables
5. run npm run docs to generates the typedoc
6. run npm run dev to execute in development mode
7. Browse to http://localhost:port to see the doc of the library

A jar file is created with the description of the declared authenticators.

Creating an authenticator

1. create a class that implements interface KeycloakRestAuthenticator, let's call it MyAuthenticator
2. using expressjs, bind the authenticator to a path: app.use(RestAuthenticator.declare("/myauth", new MyAuthenticator()))

Deploying the authenticator

1. instantiate the KeycloakPackager: const packager = new KeycloakPackager({options});
2. register the authenticator: packager.addRestAuthenticator("/myauth"); or pass the packager as the last parameter of RestAuthenticator.declare()
3. deploy the jar file: packager.make();

Adding the authenticator to keycloak

1. first check that the authenticator is deployed in keycloak by going to the /auth/admin/master/console/#/server-info/providers page
2. check that in the authenticators section you find the `script-/myauth/authenticator-rest.js``
3. go to the Authentication Flow of a realm and duplicate a flow to be able to edit (https://www.keycloak.org/docs/latest/server_admin/#_authentication-flows)
4. When adding an "execution", in the list of providers, look for http://yourhost:port/myauth that represent the authenticator you have mapped above.
5. There is no configuration possible. If you need configuration, either do it in the microservice itself, or in the client or realm attributes (via custom means)

Understanding the flow

When an authentication will happen in keycloak the flow defined in the Authentication flow structure will execute step by steps.
When your authenticator is reached (if not disabled) keycloak will submit an http post request to your endpoint

1. POST /myauth and the body is a large json object following the structure of the AuthenticationRequest type that contains the context of the request. In particular, the request.mode is first set to authenticate. The KeycloakRestAuthenticator.processNew implementation is called.
2. Your service depending on the functionality should respond with a AuthenticationResponse json structure with either
   • a form to display to the user - this is called a challenge in keycloak terminology - and uses the freemarker templates that you can customize
   • an error code to tell the authentication stop has failed
   • none of the above to tell keycloak the authentication step succeded
3. The response may also contains attributes to set to the user, to the user's session, to the authentication flow
4. If you have responded above with a form, then you expect that when the user submit the form you receive the form data. Keycloak does exactly that and your service is called with a similar post request as above to the same endpoint.
5. POST /myauth and the body is the same json object following the structure of the AuthenticationRequest. The request.mode is now set to action. The request.authSession.authNote contains all the info set during the previous response. The request.httpRequest.formParams contains the fields of the form presented to the user. The KeycloakRestAuthenticator.processInteraction implementation is called
6. Your service, depending of the functionalities should respond with a AuthenticationResponse json structure like above.
7. If the execution above takes a long time (maybe you have sent a push message to the user mobile and waiting for an acknowledgment) and in parallel the user refresh the form, or click on another button, the service is called again with a similar post to the endpoint but since the previous call has not returned, the KeycloakRestAuthenticator.processinterruption implementation is called.