Using Keycloak.x with CLI applications
Using oAuth in command line applications might be challenging. Oftentimes, it is very tempting just to pass user’s credentials in the application parameters. This however violates an important rule — a user should authenticate only using the Authorization Server’s web page. In addition to that, users tend to leave their passwords in the shell’s history, which is yet another argument not to do it.
In this blog post, I’ll show you a way to obtain an Access Token (along with other ones) from an Authorization Server using the Authorization Code Flow.
Before diving into writing a CLI application, we need to spin the Authorization Server up. In this case, we’ll use Keycloak.x, which is a Quarkus based distribution of Keycloak (you may read more about this in one of the Keycloak Blog Posts).
First, download and unpack Keycloak.x — you can grab it from here. Now, boot it up in developer mode. Please remember — this mode shall not be used in production:
Next, navigate into http://localhost:8080 and open the Admin Console up:
Finally, create a new Client that we’ll be using for this sample. The configuration is the following:
There are two things worth mentioning in the example the above:
- The redirect URL is set to the callback we’ll be using
- This is a public Client, which means it doesn’t use any Client Credentials to authenticate itself
The CLI application will use the Authorization Code Flow from oAuth 2.1 specification:
The application will start an embedded HTTP server on port 8081 (as you probably remember, Keycloak.x is hosted on 8080) using /sso-callback path. Once the application boots up, it creates an Authorization Request and once user authenticates using the Authorization Server web page, it redirects the browser back to http://localhost:8081/sso-callback. Then, the embedded HTTP server parses the Authorization Code passed in by the Authorization Server and exchanges it for a set of tokens.
The first step in our implementation is to construct an Authorization Request and open up a user’s browser pointing to it. The following code snippet shows this concept:
Next, we need to open the user’s browser up and point it to the constructed URL. This small function does this:
At the same time, we boot the embedded server up. In this case, we’ll use the http package. The code below has been greatly simplified to illustrate the main concept. It is highly advisable to use a dedicated project to handle the code exchange:
The URL for exchanging Code for Token is constructed in the following form:
As you can see, most of the parameters are passed in the HTTP POST method body.
To sum it up — the oAuth 2.1 Authorization Code flow is one of the most convenient options for obtaining tokens from an Authorization Server when creating a CLI application. The CLI application can easily redirect the default user’s browser to the Authorization Server login page and then exchange obtained code for tokens.
A production grade setup should involve using TLS and proper Keycloak setup and hardening. The simplistic example used in the code illustrates the general idea and should be replaced with a proper oAuth library.
The source code used in this example might be found here: https://github.com/slaskawi/keycloak-cli-client-example
