Secure Spring Rest API using OpenId Connect And KeyCloak - Part 1

Overview

This tutorial discusses how we can secure our REST APIs using the OpenId Connect protocol. We'll be using KeyCloak as our Identity Provider. Keycloak is an open source Identity and Access Management solution aimed at modern applications and services. Keycloak supports both OpenId Connect as well as SAML 2.0 for authentication and authorization.

The focus of this tutorial will be using KeyCloak's OpenId module. Part 1 of this tutorial focuses on setting up KeyCloak to secure our StudentService API

Install Keycloak using Docker

We'll begin by installing Keycloak. But before doing that, lets first install Docker.

Docker makes its easy to install application servers, database servers etc with the help of a single file named Dockerfile or docker-compose.yml. Cleanup is super easy since you just have to ask Docker to uninstall the software. Docker is much much more than just a tool for managing your software inventory.But, for the purpose of this tutorial, we'll use it to install Keycloak for us.

You can download and install Docker from here. To learn more about Docker and Keycloak, check out the references section of this tutorial

With Docker now installed, we can get now get started with installing KeyCloak. This step as simple as 1-2-3:

1. Download the docker-compose.yml

2. Open up a terminal window or command prompt window.

3. Run the below command to install and run Keycloak

If the command fails, please confirm that you are running the docker-compose command in the same folder than contains the downloaded docker-compose.yml file

Use the below user and password to connect to KeyCloak on your local machine. You should be able to access Keycloak's admin UI at http://localhost:9080/auth/

user: admin

password: Pa55w0rd

Configure KeyCloak to secure the StudentService API

We'll now start the process of securing our REST API with KeyCloak. We'll assume that our service is running locally at port 8080. Part 2 of this tutorial will explain how to download the source code for the service from GitHub and run it locally. But for now, we'll assume that we can access the service at http://localhost:8080

Lets first create a new realm and name it MicroServices. KeyCloak ships with a default realm of Master. The Master realm is used for administrative activities and should not be used for securing services. This is a best practice that is followed by many KeyCloak administrators

We can now use KeyCloak to secure our StudentService. For KeyCloak to provide security to the StudentService, we need to provide KeyCloak with some details of our service. We do this by registering StudentService as a client in KeyCloak.

Register StudentService as a KeyCloak OAuth 2.0 client

Select Clients from the left navigation menu and then click on the Create button. Please confirm that you are in the MicroServices realm as shown below

Use the below values to configure your service

1. Client ID : StudentService

2. Enabled : Selected

3. Client Protocol : openid-connect

4. Access Type: confidential

5. Standard Flow Enabled: Selected

6. Direct Access Grants Enabled: Selected

7. Root URL: http://localhost:8080

8. Valid Redirect URIs: http://localhost:8080/*

9. Admin URL: http://localhost:8080

10. Web Origins: http://localhost:8080

Add Roles to the StudentService Client

We'll now add an admin role and a user role to StudentService. Anyone with admin role should be able to create,modify and delete students using StudentService API. Users with the role of user will be able to see all the students created by our service, but they should not be to create, modify or delete data. We'll name these two roles as admin and user

We should now have two roles listed. If you cannot see the roles, click on View all roles

The next step is to create a Client Scope. A Client Scope is an OAuth/OpenId equivalent of a role. This is the scope that we'll be referencing in our Java code to check that users accessing our protected operations have the correct authorization to do so.

Create a ClientScope

Click on the Client Scope from the left hand navigation menu and create a new Client Scope. We'll call this client scope StudentService-write. Choose openid-connect as the Protocol. Click Save

Add the StudentService roles to the ClientScope

We can now add the admin role from the StudentService to this client scope. Select Scope and in the Client Roles drop down, Choose StudentService. Choose the admin role and then click on Add Selected. Your Screen should now look like how it does below:

Lets do a quick recap. We walked through the below steps to get started with securing our StudentService with Keycloak:

1. We installed Docker to help with the installation of KeyCloak

2. We installed KeyCloak with the help of Docker

3. We created a new Realm called MicroServices

4. We added a new Client called StudentServices

5. We added two roles: admin and user to the StudentServices client

6. We then created a ClientScope named StudentService-write

7. We then added the admin and user roles to the StudentService-write client scope

Finally! We are done with the KeyCloak configuration. Or are we? We may have to come back to do one last thing. But for now, we'll call it a day. The next post will explore how the StudentService's Java source code will use KeyCloak to accept or reject calls made to the API. Stay tuned!

References

1. Spring Security OAuth2 support

2. OAuth 2.0 Client Credentials Grant

3. Docker Tutorial

4. Keycloak Tutorial