Securing Spring Boot Admin & actuator endpoints with Keycloak

Spring Boot Admin is a popular tool for monitoring and managing Spring Boot -based applications. In this blog post you’ll learn how to secure Spring Boot Admin itself and protect the actuator endpoints of monitored applications with Keycloak .

Overview

In our demo environment we’re going to have three components:

• Keycloak Auth Server
• Spring Boot Admin
• Spring Boot App with actuator endpoints

The Keycloak Auth server is available via http://localhost:8080/auth
The Spring Boot Admin app is available via http://localhost:30001/admin
The monitored Spring Boot App is available via http://localhost:30002

Keycloak configuration

In Keycloak we’ll define a dedicated realm with the name bootadmin.

Then we’ll create two clients: app-admin, which represents the Spring Boot Admin application, and app-todo, which denotes the Spring Boot app respectively.
Well start with the definition of the monitored Spring Boot app that exposes actuator endpoints.

Client for Spring Boot app with actuator endpoints in Keycloak

Our example application is a simple to do management app with the client ID app-todo.

The app-todo client is configured as follows:

Client-Protocol: OpenID Connect
Access-Type: confidential
Standard-Flow Enabled: on
Direct-Access grants: off

Root URL: http://localhost:30002
Valid redirect URIs: /*
Base URL: /
Admin URL: /
Web Origins: +

In the credentials tab, you need to write down the Secret, as we’ll need this later for our Spring Boot app configuration.

Roles

We need to define the following roles for our app-todo client:

• user – denotes the normal to do app users.
• actuator – this role is used to access the actuator endpoints.

Scope

For the sake of simplicity, we set Fill Scope Allowed: on, however I’d recommend to be explicit about what roles a client might see to keep the tokens small. This also helps avoid exposing unnecessary information to a client application.

Client for Spring Boot Admin in Keycloak

The app-admin client is configured as follows:

Client-Protocol: OpenID Connect
Access-Type: confidential
Standard-Flow Enabled: on
Direct-Access grants: off
Service-Accounts Enabled: on

Root URL: http://localhost:30001
Valid redirect URIs: /*
Base URL: /admin
Admin URL: /
Web Origins: +

As before, in the credentials tab write down the Secret as we’ll need this later for our Spring Boot configuration.

Roles

We need to define the following roles for our app-admin client:

• admin – denotes the users who can access Spring Boot Admin
• actuator – internal Role for the service account user. This role is used to access the actuator endpoints of monitored applications.

Note that this actuator role is a composite role which includes the actuator roles of the monitored client apps.

Scope

As before we set Fill Scope Allowed: on.

Service accounts

We grant the actuator role of the app-admin to the service account user. Since the app-admin:actuator composite role includes the app-todo:actuator role, we also have access to its actuator endpoints. One can easily apply this pattern to securely monitor new applications.

With that set, the only thing that’s left to do on the Keycloak side is to create a user who can access the Spring Boot Admin UI.

For this we create a user with the username tester and password test. We also assign the admin role for the app-admin client.

The complete example, with more details about the Keycloak configuration, can be found in the spring-boot-admin-keycloak-example repository on Github.

After our Keycloak environment is configured, we can move on to the Spring Boot apps.
We begin with the Todo-Service app that we modelled as app-todo client.

Todo-Service

We’ll start with the Maven configuration for the to do service module, which looks like this:

The Todo-Service is pretty simplistic and only shows the Spring Boot Admin Client configuration as well as the required actuator and Keycloak setup.
Our main class is the TodoServiceApplication which contains an embedded TodoController for the sake of brevity – Josh Long style FWT.

The Keycloak configuration for the Todo-Service is denoted by the class KeycloakConfig:

The application configuration for the Todo-Service is contained in application.yml

spring:
  main:
    allow-bean-definition-overriding: true

server:
  port: 30002

keycloak:
  realm: bootadmin
  auth-server-url: http://localhost:8080/auth
  resource: app-todo
  credentials:
     secret: 2cc653a3-24cc-4241-896d-813a726f9b33
  ssl-required: external
  principal-attribute: preferred_username
  autodetect-bearer-only: true
  use-resource-role-mappings: true
  token-minimum-time-to-live: 30

management:
  endpoints:
    web:
      exposure:
        include: '*'

Our Todo-Service application is now ready for service. We’ll now move on to the last path, the Admin-Service.

Admin-Service

The Admin-Service is denoted by the app-admin Keycloak client and hosts the Spring Boot Admin infrastructure. It uses a Keycloak service account to access the actuator endpoints of monitored applications. The app also exposes the Spring Boot Admin UI which is protected by Keycloak as well.
Only users with the role admin for the app-admin client will be able to login to the admin UI.

The Maven module configuration of Admin-Service looks like this:

The main class of the Admin-Service is straightforward:

The Keycloak configuration is more advanced though:

Note that we defined a dedicated Keycloak bean, which is used by the HttpHeadersProvider keycloakBearerAuthHeaderProvider bean to transparently retrieve (and renew) an OAuth2 Access-Token for the app-admin service account. All requests towards actuator endpoints of monitored applications will use this token.

In order to support a proper logout functionality, we’ll have to set up a dedicated /admin/logout endpoint.

The spring configuration file application.yml for the Admin-Service looks like this:

server:
  port: 30001

spring:
  main:
    allow-bean-definition-overriding: true
  boot:
    admin:
      context-path: /admin
  cloud:
    discovery:
      client:
        simple:
          instances:
            app-todo:
              - uri: http://localhost:30002

keycloak:
  realm: bootadmin
  auth-server-url: http://localhost:8080/auth
  resource: app-admin
  credentials:
     secret: 97edad04-49ca-4770-8e4a-3bc97c1714ce
  ssl-required: external
  principal-attribute: preferred_username
  use-resource-role-mappings: true
  token-minimum-time-to-live: 30

Et voilà, we now have a setup that is fully secured via Keycloak 🙂