Secure your app with Keycloak and Docker

Reading Time: 6 minutes

Hey folks ! In last blog we discussed about keycloak service and its features . So I am assuming you already know about keycloak. In this blog we will discuss how we can run keycloak locally using docker and secure an application in just three steps. Let’s begin.

Let’s briefly discuss about Keycloak first

Keycloak

Keycloak is an open source Identity and Access Management solution aimed at modern applications and services. It makes it easy to secure applications and services with little to no code, which means that you just need to configure functionalities, don’t need to write code. Therefore it will save development time.

Docker

Docker is a software platform designed to make it easier to create, deploy, and run applications by using containers. It allows developers to package up an application with all the parts it needs in a container, and then ship it out as one package.

Step 1: Obtaining and running Keycloak docker container

Using docker allows us to get and run containers to execute a wide range of software packages, so a very popular software like KeyCloak, is not an exception.

Visit Docker Hub to find and download docker images including a countless list of software packages

Open a terminal and run the command below in order to check your docker installation.

$ docker version
Server: Docker Engine - Community
 Engine:
  Version:          20.10.2
  API version:      1.41 (minimum version 1.12)
  Go version:       go1.13.15
  Git commit:       8891c58
  Built:            Mon Dec 28 16:15:28 2020
  OS/Arch:          linux/amd64
  Experimental:     false
 containerd:
  Version:          1.4.3
  GitCommit:        269548fa27e0089a8b8278fc4fc781d7f65a939b
 runc:
  Version:          1.0.0-rc92
  GitCommit:        ff819c7e9184c13b7c2607fe6c30ae19403a7aff
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

If you get a message like the one displayed above, it means your docker installation is ok. Then you can proceed to obtain Keycloak as docker image by typing the following:

$ docker pull jboss/keycloak:12.0.4

The previous command will download the version 12.0.4 of Keycloak within an image available in the Docker store, so now you can run it into your local machine:

$ docker run --name myKeyCloak -p 8089:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin -d jboss/keycloak:12.0.4

If everything went well you could see the running container by typing the following command:

$ docker ps -a
CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                 NAMES
b5ea3759f75b   jboss/keycloak          "/opt/jboss/tools/do…"   9 seconds ago   Up 9 seconds   8443/tcp, 0.0.0.0:8089->8080/tcp   myKeyCloak

Then you can access to the Keycloak instance by opening a browser tan and typing the following url http://localhost:8089

Keycloak Homepage

Step 2: Configure realms & Users on Keycloak

Once the Keycloak containeris up and running and we have access to the platform, the next step is configuring the platform to manage the authentication and authorization requirements for our app. In order to do so, you need to click on Administration Console and log in with the credentials provided when running the container (in our case user & password admin). After successfully login, we will be redirected to the main dashboard where the default Master realm is displayed.

Realm

Realm is a concept in Keycloak that refers to an object in charge of defining a security policy domain applied to users along with their credentials, roles and groups. A user in Keycloak belongs to only one realm and the user who logs in to Keycloak will log into that user’s realm.

Default master realm page

Create an application realm

• Go to your Keycloak installation admin page using your administrator account credentials (http://localhost:8089/auth/admin/)
• Go to Master drop down menu (top-left area) and click on “Add realm” button as displayed in the following picture:

Add realm button

• Provide a name for the realm you will use to manage your application security (keep in mind that the realm name is case sensitive). In our case, we are going to use the name my-demo-app.

Add realm form

• After clicking on Create button, the new realm will be created and the main page of the just created realm (my-demo-app) is displayed.

My demo app main page

Create a user for the application

After creating a realm, we need to create a user within the just created my-demo-app realm.

• Go to the just created My-demo-app realm main page.
• Click on the Users button on the left side menu to see an empty list of users. This is fine, because we have just created the realm and by default it is empty.
• Next, click on the button “Add user” placed on the top-right area of the page as indicated in the following picture.

user-section

• Fill in the form with the information about the user. Set the Email Verified to On, so this verification is not needed for the current user. Also, as indicated as follows, you can configure several actions to be performed by the user prior to have the account validated. Once finished, click on Save button to create the user.

Add user

• The last thing to do, prior to be able to log in with the user, is going to credentials. fill in the the password & password Confirmation field and select OFF next to Temporary field (so we are not forced to update the password on the first login). Then click on Set Password button.

Credential section

Finally we are ready to test if our just created user is valid to successfully log in. So, sign out as administrator and type the following url in your browser: http://localhost:8089/auth/realms/my-demo-app/account/ (this is the url enabled by Keycloak to manage the access to the realm associated with my-demo-app). Click on sign in (top right corner)and use the credentials for the just created user account. If everything goes well, you should see the following screen with the first and the last name of the user on the top right corner. From this page the user is able to manage the account.

user logged in main section

Step 3: Secure your app

Everything is ready with your Keycloak server to allow your apps to log in against it, so let’s proceed with it by creating a client to process the app requests.

Create a client adapter for your app

Open the Admin Console of your Keycloak installation (http://localhost:8089/auth/admin) and log in with your admin credentials. Click on Clients on the left side menu and click on Create button located on top of the clients table. Then fill in the form as indicated in the picture below and click on Save button.

Client credential form

The client ID specifies the identification string used for tokens and URI’s. This must be unique for your Keycloak installation and must reference to a specific application.

Keycloak provides a sample application you can use to try-out your server without having to code a dummy app by yourself. This application is accessible on the following url (https://www.keycloak.org/app/), and that url is the one we have typed in the Root URL field.

Try out time!

Open a browser tab and type the sample app url (https://www.keycloak.org/app/). Then fill in the form with the Url where our Keycloak instance is running (http://localhost:8089/auth) and the realm and the client configured on our Keycloak. If you have followed the tutorial, your configuration should look like as follows:

configuration

After checking that everything is right, click on Save button and you will see a Sign In button. Click on it and you will be redirected to the Keycloak log in page. Use the user credentials (username: my-demo-app-user and the password created on step 2) and you will be redirected back to the app with your user account information, that’s all!

successful login with keycloak

Conclusions & Future work

In this blog we have demonstrated how easy can be to create your own custom Identity and Access Management solution using Keycloak and Docker. Working with a properly configured Keycloak server,you can can get rid of all this boilerplate code to manage authentication & authorization on your custom applications.

References