Quickly Secure Your SpringBoot Apps with Keycloak: Docker Setup & OAuth2 Integration

Introduction

Keycloak is an open‑source authentication and authorization platform with over 9.4k stars on GitHub, offering features such as user registration, social login, SSO, 2FA, and LDAP integration.

Installation

Deploy Keycloak with Docker using two simple commands.

docker pull jboss/keycloak:14.0.0

docker run -p 8080:8080 --name keycloak \
  -e KEYCLOAK_USER=admin \
  -e KEYCLOAK_PASSWORD=admin \
  -d jboss/keycloak:14.0.0

After the container starts, access the admin console at http://192.168.7.142:8080.

Console Usage

Log in with the default admin:admin credentials. Switch the UI language to Chinese via Themes->Default Locale → zh-CN. Create a realm named macrozheng, then add a user macro with a password under the Credentials tab. The user and admin login URLs differ; you can find the user login URL under the Clients page.

OAuth2 Integration

Keycloak supports standard OAuth2 flows. The two common grant types are:

Authorization Code Flow

Client redirects the user to the authentication server.

User logs in and grants permission.

Server returns an authorization code.

Client exchanges the code for an access token.

Server issues the access token (optionally with a refresh token).

Password Grant Flow

Client collects username and password from the user.

Client sends them to the authentication server.

Server returns an access token (optionally with a refresh token).

Password Mode Experience

Create a client mall-tiny-keycloak, add a role mall-tiny, and assign the role to the user macro. Then request a token via Postman at

http://192.168.7.142:8080/auth/realms/macrozheng/protocol/openid-connect/token

.

SpringBoot Integration

Configure the SpringBoot application (running on localhost:8088) with a Keycloak client that has a valid redirect URI. Add the Keycloak starter dependency:

<!--集成Keycloak-->
<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-spring-boot-starter</artifactId>
    <version>14.0.0</version>
</dependency>

Then configure application.yml:

# Keycloak configuration
keycloak:
  # Set the realm of the client
  realm: macrozheng
  # Keycloak server URL
  auth-server-url: http://192.168.7.142:8080/auth
  # Client ID
  resource: mall-tiny-keycloak
  # Public client (no secret required)
  public-client: true
  # Role‑to‑URL mapping
  security-constraints:
    - auth-roles:
        - mall-tiny
      security-collections:
        - patterns:
            - '/brand/*'
            - '/swagger-ui/*'

Access the Swagger UI at http://localhost:8088/swagger-ui/; you will be redirected to Keycloak for login. After successful authentication, the protected APIs and Swagger page become accessible.

Conclusion

Keycloak provides a visual, ready‑to‑use security framework that eliminates the need to develop authentication services from scratch and integrates seamlessly with SpringBoot, making it an excellent choice for modern application security.