Secure Your Spring Boot App with Keycloak: Step‑by‑Step OIDC Integration

In the previous article we created a Keycloak realm felord.cn and a user felord. This article shows how to protect a Spring Boot application using the Keycloak Spring Boot adapter.

Client

Register a client in the realm, similar to appid/secret in other platforms. The following diagram illustrates the relationship between the master realm, custom realms, users, and clients.

After creating the client spring-boot-client in realm felord.cn, the client list shows the new entry.

You can log in to the created user at http://localhost:8011/auth/realms/felord.cn/account/ .

Role

Keycloak uses role‑based access control. Create a role base_user and assign it to the user felord.

Assign the role to the user:

Get and Refresh JWT

Obtain a JWT token with a password grant:

POST /auth/realms/felord.cn/protocol/openid-connect/token HTTP/1.1
Host: localhost:8011
Content-Type: application/x-www-form-urlencoded

client_id=springboot-client&username=felord&password=123456&grant_type=password

The response contains access_token, refresh_token and other fields.

{
    "access_token": "eyJhbGciOi...",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOi...",
    "token_type": "Bearer",
    "not-before-policy": 0,
    "session_state": "2fc7e289-c86f-4f6f-b4d3-1183a9518acc",
    "scope": "profile email"
}

Refresh the token by sending the refresh_token with grant_type=refresh_token:

POST /auth/realms/felord.cn/protocol/openid-connect/token HTTP/1.1
Host: localhost:8011
Content-Type: application/x-www-form-urlencoded

client_id=springboot-client&grant_type=refresh_token&refresh_token=eyJhbGciOi...

Both requests use application/x-www-form-urlencoded as the Content‑Type.

Spring Boot Client

Add the Keycloak starter dependency (version 14.0.0) to your pom.xml:

<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-spring-boot-starter</artifactId>
    <version>14.0.0</version>
</dependency>

Create a simple controller:

@RestController
@RequestMapping("/foo")
public class FooController {
    @GetMapping("/bar")
    public String bar() {
        return "felord.cn";
    }
}

Configure Keycloak in application.yml to protect the /foo/bar endpoint for users with the base_user role:

keycloak:
  realm: felord.cn
  auth-server-url: http://localhost:8011/auth
  resource: springboot-client
  public-client: true
  security-constraints:
    - auth-roles:
        - base_user
      security-collections:
        - patterns:
            - '/foo/bar'

Run the Spring Boot application and access http://localhost:8080/foo/bar. You will be redirected to the Keycloak login page:

http://localhost:8011/auth/realms/felord.cn/protocol/openid-connect/auth?response_type=code&client_id=springboot-client&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Ffoo%2Fbar&state=...&login=true&scope=openid

After successful authentication, the protected endpoint returns the expected response.

Summary

This tutorial demonstrates a minimal OIDC authentication setup that secures a Spring Boot API using Keycloak. The next article will dive deeper into the OIDC protocol.