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:
Download the docker-compose.yml
Open up a terminal window or command prompt window.
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
Client ID : StudentService
Enabled : Selected
Client Protocol : openid-connect
Access Type: confidential
Standard Flow Enabled: Selected
Direct Access Grants Enabled: Selected
Root URL: http://localhost:8080
Valid Redirect URIs: http://localhost:8080/*
Admin URL: http://localhost:8080
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:
We installed Docker to help with the installation of KeyCloak
We installed KeyCloak with the help of Docker
We created a new Realm called MicroServices
We added a new Client called StudentServices
We added two roles: admin and user to the StudentServices client
We then created a ClientScope named StudentService-write
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!