By Thisara Priyamal in Spring Boot — 15 Jul 2025

Spring Boot සමග Keycloak: පහසුවෙන් Single Sign-On SC Guide

හායි කොල්ලනේ කෙල්ලනේ, කොහොමද ඉතින්? අද අපි කතා කරන්න යන්නේ ඔයාලගේ applications වල user management කියන ලොකු ගැටලුවට, ඊටත් වඩා Single Sign-On (SSO) කියන පට්ටම solution එකට. මම දන්නවා, ඔයාලටත් ගොඩක් වෙලාවට users ලා manage කරන එක, ඒගොල්ලන්ගේ passwords, roles එහෙම handle කරන එක headache එකක් වෙන්න ඇති. Application එකක් හදනකොට මුලින්ම එන ගැටලුවක් තමයි authentication සහ authorization. මේක හරියට manage කරගන්න බැරි වුනොත් application එකේ security එකත් අඩු වෙනවා, user experience එකත් අවුල් වෙනවා. හැබැයි මේ හැමදේටම පට්ටම solution එකක් තමයි Keycloak කියන්නේ! අද අපි මේ article එකෙන් Spring Boot එක්ක Keycloak integrate කරලා කොහොමද SSO implement කරන්නේ කියලා බලමු. මේක ඔයාලට ඔයාලගේ projects වලට ගොඩක්ම වැදගත් වෙයි. එහෙනම්, අපි පටන් ගමු!

Keycloak කියන්නේ මොකක්ද?

හරි, මුලින්ම අපි බලමු මේ Keycloak කියන්නේ මොකක්ද කියලා. සරලවම කිව්වොත්, Keycloak කියන්නේ Identity and Access Management (IAM) solution එකක්. මේක open-source. ඒ කියන්නේ අපිට සල්ලි නොදී පාවිච්චි කරන්න පුළුවන්. Keycloak එකේ ප්රධාන අරමුණ තමයි ඔයාලගේ application එකේ users ලා manage කරන එක, authentication කරන එක, authorization දෙන එක, ඊටත් වඩා, Single Sign-On (SSO) වගේ advanced features සපයන එක. මේකේ තියෙන පට්ටම විශේෂත්වය තමයි එය OAuth 2.0, OpenID Connect, SAML 2.0 වගේ standard protocols වලට support කරන එක. මේ නිසා අපිට ඕනෑම application එකක් එක්ක Keycloak integrate කරන්න පුළුවන්.

Keycloak එකෙන් ඔයාලට ලැබෙන වාසි මොනවද?

Single Sign-On (SSO): මේ ගැන අපි පස්සේ තව දුරටත් කතා කරනවා. සරලවම කිව්වොත්, එක සැරයක් login වුනාම ඒ user ට ඔයාලගේ ecosystem එකේ තියෙන හැම application එකකටම access කරන්න පුළුවන්. හිතල බලන්න, Facebook, Google වගේ services වලට එකම account එකකින් login වෙනවා වගේ.
User Federation: ඔයාලට Active Directory, LDAP වගේ external user stores එක්ක Keycloak integrate කරන්න පුළුවන්. ඒ කියන්නේ ඔයාලගේ existing user base එක Keycloak එකට migrate කරන්න ඕන වෙන්නේ නෑ.
Social Login: Google, Facebook, GitHub වගේ social media accounts වලින් login වෙන්න පහසුකම් සලසනවා.
Two-Factor Authentication (2FA): Security එක තවත් වැඩි කරන්න 2FA support කරනවා.
Admin Console: Users, realms, clients, roles, sessions manage කරන්න පුළුවන් පහසු web-based admin console එකක් තියෙනවා.

අද කාලේ distributed microservices architectures එක්ක වැඩ කරනකොට මේ වගේ IAM solution එකක් නැතුව බෑ. Keycloak එකෙන් මේ හැමදේම පහසුවෙන් කරගන්න පුළුවන්.

Spring Boot එකට Keycloak ගලපමු!

හරි, දැන් අපි බලමු කොහොමද අපේ Spring Boot application එකට Keycloak integrate කරන්නේ කියලා. මේක කරන්න කලින් අපිට Keycloak server එකක් අවශ්‍යයි. ඔයාලට Keycloak server එක Docker container එකක් විදියට හෝ standalone server එකක් විදියට install කරගන්න පුළුවන්. මම නිර්දේශ කරන්නේ Docker පාවිච්චි කරන එක, මොකද ඒක ගොඩක්ම පහසුයි.

Keycloak Server එක Setup කරගනිමු:

Docker Desktop install කරලා තියෙනවා නම්, command prompt/terminal එක open කරලා මේ command එක run කරන්න:

docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:23.0.0 start-dev

මේකෙන් Keycloak server එක 8080 port එකේදී run වෙන්න පටන් ගන්නවා. Admin console එකට යන්න පුළුවන් http://localhost:8080/admin/ address එකෙන්. Username: admin, Password: admin.

Keycloak Realm සහ Client එකක් Setup කරමු:

Keycloak admin console එකට login වෙලා, වම් පැත්තේ උඩ තියෙන Master dropdown එකෙන් "Create realm" ක්ලික් කරන්න.
Realm නමක් දෙන්න. උදාහරණයක් විදියට SpringBootRealm කියලා. Create කරන්න.
දැන් වම් පැත්තේ "Clients" වලට ගිහින් "Create client" ක්ලික් කරන්න.
Client ID එකක් දෙන්න. උදාහරණයක් විදියට spring-boot-app. Next ක්ලික් කරන්න.
"Client authentication" Enable කරන්න. "Standard flow" සහ "Direct access grants" Enable කරන්න.
"Root URL" එකට http://localhost:8081 (ඔයාගේ Spring Boot app එක run වෙන port එක) වගේ දෙන්න.
"Valid redirect URIs" වලට http://localhost:8081/* (ඔයාගේ app එකේ redirect URI) වගේ දෙන්න. Save කරන්න.
"Credentials" tab එකට ගිහින් Client Secret එක copy කරගන්න. මේක අපිට Spring Boot app එකේදී අවශ්‍ය වෙනවා.

User කෙනෙක් හදමු:

වම් පැත්තේ "Users" වලට ගිහින් "Create new user" ක්ලික් කරන්න.
Username එකක් දෙන්න. උදාහරණයක් විදියට testuser. Save කරන්න.
"Credentials" tab එකට ගිහින් password එකක් set කරන්න. "Temporary" කියන එක Disable කරන්න.

Spring Boot Project එක Setup කරමු:

අපි දැන් Spring Initializr (https://start.spring.io/) එකෙන් Spring Boot project එකක් හදාගමු. මේ dependencies ටික add කරන්න:

Spring Web
Spring Security
Thymeleaf (optional, if you want a web UI)
Keycloak Spring Boot Adapter (මේක තමයි ප්රධාන එක!)

Maven project එකක් නම්, pom.xml එකට මේ dependencies add කරන්න:

<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-spring-boot-starter</artifactId>
    <version>23.0.0</version> <!-- Keycloak version එකට අදාළව මෙය වෙනස් වෙන්න පුළුවන් -->
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

application.properties Configuration:

අපේ Spring Boot application එකට Keycloak එක්ක connect වෙන්න අවශ්‍ය විස්තර src/main/resources/application.properties ෆයිල් එකට add කරන්න.

keycloak.auth-server-url=http://localhost:8080
keycloak.realm=SpringBootRealm
keycloak.resource=spring-boot-app
keycloak.credentials.secret=YOUR_CLIENT_SECRET_FROM_KEYCLOAK
keycloak.ssl-required=external
keycloak.use-resource-role-mappings=true

# Spring Boot Server Port
server.port=8081

YOUR_CLIENT_SECRET_FROM_KEYCLOAK කියන තැන ඔයා Keycloak client එක හදනකොට copy කරගත්ත Client Secret එක දාන්න.

Spring Security Configuration:

දැන් අපි Spring Security config කරන්න ඕනේ Keycloak එක්ක වැඩ කරන්න. මේ වගේ class එකක් හදමු:

import org.keycloak.adapters.springsecurity.KeycloakConfiguration;
import org.keycloak.adapters.springsecurity.config.KeycloakWebSecurityConfigurerAdapter;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
import org.springframework.security.config.annotation.method.configuration.EnableGlobalMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.core.session.SessionRegistryImpl;
import org.springframework.security.web.authentication.session.RegisterSessionAuthenticationStrategy;
import org.springframework.security.web.authentication.session.SessionAuthenticationStrategy;

@KeycloakConfiguration
@EnableGlobalMethodSecurity(prePostEnabled = true) // Enable method level security
public class SecurityConfig extends KeycloakWebSecurityConfigurerAdapter {

    @Autowired
    public void configureGlobal(AuthenticationManagerBuilder auth) throws Exception {
        auth.authenticationProvider(keycloakAuthenticationProvider());
    }

    @Bean
    @Override
    protected SessionAuthenticationStrategy sessionAuthenticationStrategy() {
        return new RegisterSessionAuthenticationStrategy(new SessionRegistryImpl());
    }

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        super.configure(http);
        http.authorizeRequests()
            .antMatchers("/public").permitAll() // Publicly accessible endpoint
            .antMatchers("/protected").hasRole("user") // Protected endpoint for 'user' role
            .anyRequest().authenticated(); // All other requests require authentication
    }
}

මේකේදී අපි KeycloakWebSecurityConfigurerAdapter extend කරලා, configureGlobal method එකෙන් Keycloak authentication provider එක register කරනවා. sessionAuthenticationStrategy method එකෙන් Keycloak session management enable කරනවා. configure(HttpSecurity http) method එකෙන් අපේ URL paths protect කරනවා. මෙතනදී අපි /public කියන එකට හැමෝටම access දෙන්නත්, /protected කියන එකට user role එක තියෙන අයට විතරක් access දෙන්නත් හදලා තියෙනවා.

Simple Controller එකක් හදමු:

import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.security.Principal;

@RestController
public class MyController {

    @GetMapping("/public")
    public String publicEndpoint() {
        return "This is a public endpoint.";
    }

    @GetMapping("/protected")
    @PreAuthorize("hasRole('user')")
    public String protectedEndpoint(Principal principal) {
        return "Hello, " + principal.getName() + "! You have accessed a protected endpoint.";
    }

    @GetMapping("/admin")
    @PreAuthorize("hasRole('admin')") // Example for admin role
    public String adminEndpoint() {
        return "Hello Admin! You have accessed the admin endpoint.";
    }
}

දැන් ඔයාගේ Spring Boot application එක run කරන්න. http://localhost:8081/public එකට ගියාම කිසි ප්‍රශ්නයක් නැතුව access වෙයි. හැබැයි http://localhost:8081/protected එකට ගියාම ඔයාව Keycloak login page එකට redirect කරයි! Login වුනාට පස්සේ ආයෙත් ඔයාගේ application එකට redirect කරලා protected content එක පෙන්නයි. වැඩේ ගොඩ!

Single Sign-On (SSO) කියන්නේ මොකක්ද?

හරි, අපි මේකේදී ගොඩක්ම කතා කරපු වචනයක් තමයි Single Sign-On (SSO) කියන්නේ. මේක මොකක්ද කියලා හොඳට තේරුම් ගන්න එක ගොඩක් වැදගත්. සරලවම කිව්වොත්, SSO කියන්නේ, user කෙනෙක් එක සැරයක් login වුනාම, එයාට ඒ login එකෙන් ඔයාලගේ organization එකේ හෝ ecosystem එකේ තියෙන වෙනත් applications කිහිපයකටම ආයෙත් login නොවී access කරන්න පුළුවන් වෙන එක. ඒ කියන්නේ, user ට එකම username/password set එකක් මතක තියාගත්තම ඇති. හැම application එකකටම වෙන වෙනම username/password මතක තියාගෙන ඉන්න ඕන වෙන්නේ නෑ.

මීට කලින් අපි Facebook, Google වගේ services වලට login වෙනකොට, වෙනත් applications වලට connect වෙන්න පුළුවන් වෙනවා නේද? උදාහරණයක් විදියට, Spotify වලට Google account එකෙන් login වෙන්න පුළුවන්. ඒකත් SSO concept එකක්. Spotify එක ඔයාට Google එක්ක authenticate වෙන්න ඉඩ දෙනවා. Keycloak වගේ Identity Provider (IdP) එකක් මේ වගේ service එකක් විදියට වැඩ කරනවා.

SSO එකෙන් ලැබෙන ප්රධාන වාසි මොනවද?

User Convenience: users ලට හැම application එකකටම වෙන වෙනම login වෙන්න ඕන නෑ. එක සැරයක් login වුනාම ඇති. මේක users ලට ලොකු පහසුවක්.
Reduced Password Fatigue: ගොඩක් passwords මතක තියාගන්න ඕන නැති නිසා password fatigue කියන එක අඩු වෙනවා. මේ නිසා users ලා දුර්වල passwords පාවිච්චි කරන එකත් අඩු වෙන්න පුළුවන්.
Improved Security: centralized authentication system එකක් තියෙන නිසා security එක වැඩි වෙනවා. Password management එක centralized වෙන නිසා hacker කෙනෙක්ට හැම application එකටම එකින් එක attack කරන්න අමාරු වෙනවා.
Centralized User Management: IT admins ලට users ලා manage කරන එක ගොඩක් පහසු වෙනවා. Users add කරන එක, remove කරන එක, permissions දෙන එක centralized system එකකින් කරන්න පුළුවන්.
Reduced Help Desk Costs: users ලා passwords අමතක කරලා reset කරන්න help desk එකට කතා කරන එක අඩු වෙනවා. මේ නිසා help desk එකට යන වියදම් අඩු වෙනවා.

මේ වගේ වාසි ගොඩක් SSO එකෙන් ලැබෙනවා. Keycloak එකෙන් මේ SSO functionality එක ඉතාමත් පහසුවෙන් implement කරන්න පුළුවන්. අපේ Spring Boot application එකේදී අපි කරේ මේ Keycloak IdP එකට අපේ app එක trust කරන්න සලස්සන එකයි.

ප්‍රායෝගික උදාහරණයක්: Spring Boot SSO Demo

අපි දැන් Spring Boot එක්ක Keycloak SSO එක තව ටිකක් විස්තරාත්මකව බලමු. ඔයාලට applications කිහිපයක් තියෙනවා කියලා හිතමු. App A (http://localhost:8081) සහ App B (http://localhost:8082). මේ දෙකම Spring Boot වලින් හදපු applications. මේ දෙකටම Keycloak SSO එක්ක integrate කරලා තියෙන්නේ.

Setup:

Keycloak server එක කලින් විදියටම 8080 port එකේ run වෙනවා.
Keycloak realm එක SpringBootRealm විදියට තියෙනවා.
Client දෙකක් හදමු: spring-boot-app-a (redirect URI: http://localhost:8081/*) සහ spring-boot-app-b (redirect URI: http://localhost:8082/*). මේ දෙකටම වෙන වෙනම client secret තියෙන්න ඕනේ.
User කෙනෙක් ඉන්නවා testuser කියලා user role එකත් එක්ක.

App A (application.properties):

keycloak.auth-server-url=http://localhost:8080
keycloak.realm=SpringBootRealm
keycloak.resource=spring-boot-app-a
keycloak.credentials.secret=YOUR_CLIENT_SECRET_A
keycloak.ssl-required=external
server.port=8081

App B (application.properties):

keycloak.auth-server-url=http://localhost:8080
keycloak.realm=SpringBootRealm
keycloak.resource=spring-boot-app-b
keycloak.credentials.secret=YOUR_CLIENT_SECRET_B
keycloak.ssl-required=external
server.port=8082

දැන් App A සහ App B දෙකම Spring Security Config (SecurityConfig.java) සහ Controller (MyController.java) එක කලින් විදියටම හදාගන්න. මේ apps දෙකම run කරන්න.

SSO Flow:

මුලින්ම http://localhost:8081/protected (App A) එකට යන්න. ඔයාව Keycloak login page එකට redirect කරයි.
Username: testuser, Password: <your_password> දීලා login වෙන්න.
දැන් ඔයාව App A එකට redirect කරයි. Protected content එක පෙන්නයි.
දැන් browser tab එක වහන්නේ නැතුව http://localhost:8082/protected (App B) එකට යන්න.
ගැම්මටම, ඔයාව ආයෙත් Keycloak login page එකට redirect කරන්නේ නෑ! මොකද? ඔයා Keycloak session එකේ දැනටමත් authenticated වෙලා ඉන්නේ! Keycloak එකෙන් automatic App B එකට authenticated session එකක් දෙනවා. ඔයාට කෙලින්ම App B එකේ protected content එක access කරන්න පුළුවන් වෙනවා.

ඕක තමයි Keycloak SSO එකේ පට්ටම වාසිය! User ට එක සැරයක් login වුනාම ඇති, එයාට ecosystem එකේ තියෙන අනිත් හැම application එකකටම login නොවී access කරන්න පුළුවන්. මේක Enterprise applications වලට නම් අතිශයින්ම වැදගත්. Keycloak එකේදී මේ authentication tokens, sessions, permissions වගේ දේවල් ඉතාම effective විදියට manage කරනවා.

ඔයාලට තව advanced දේවල් කරන්න පුළුවන්. උදාහරණයක් විදියට, Keycloak Roles ටික Spring Security Roles වලට map කරන එක, token parsing කරලා user attributes extract කරන එක, logout mechanism implement කරන එක වගේ දේවල්.

ප්‍රයෝගික Tips:

Role Mapping: Keycloak එකේදී Realm Roles, Client Roles කියලා roles වර්ග දෙකක් තියෙනවා. අපේ Spring Boot application එකට අවශ්‍ය වෙන්නේ Client Roles. ඒ නිසා Keycloak client එකට roles add කරලා user ට assign කරන්න. Spring Security එකෙන් ඒ roles auto recognize කරනවා.
Token Introspection: සමහර වෙලාවට authenticated user ගේ details (email, first name, last name, custom attributes) Spring Boot application එක ඇතුලට ගන්න අවශ්‍ය වෙනවා. මේකට Principal object එක use කරන්න පුළුවන්. KeycloakPrincipal or KeycloakAuthenticationToken එකෙන් ඔබට access token එකට access කරලා JWT (JSON Web Token) එක decrypt කරලා අවශ්‍ය details ගන්න පුළුවන්.
Logout: Spring Security logout URL එක call කරනකොට, Keycloak session එකත් invalid කරන්න ඕනේ. මේකට Keycloak adapter එකෙන් සපයන /sso/logout endpoint එක භාවිතා කරන්න පුළුවන්.
Production Deployment: Production වලදී Keycloak server එකට HTTPS enable කරන්න අනිවාර්යයි. localhost එකේදී keycloak.ssl-required=external දාපු එක production වලදී keycloak.ssl-required=all දාලා HTTPS setup කරන්න.

අන්තිම වචන

හරි, අද අපි Spring Boot එක්ක Keycloak integrate කරලා Single Sign-On (SSO) එක කොහොමද implement කරන්නේ කියලා ගොඩක් විස්තරාත්මකව කතා කළා. මුලින් Keycloak කියන්නේ මොකක්ද කියලා බැලුවා, ඊට පස්සේ step-by-step විදියට Spring Boot project එකකට integrate කරන විදිය බැලුවා, අන්තිමට SSO කියන්නේ මොකක්ද සහ ඒක කොහොමද Keycloak එක්ක වැඩ කරන්නේ කියලා ප්‍රායෝගික උදාහරණයක් එක්කම සාකච්ඡා කළා. මේක ඔයාලගේ projects වලට ගොඩක්ම වැදගත් වෙයි කියලා මම හිතනවා. Identity and Access Management කියන එක අද වෙනකොට software development වලදී නැතුවම බැරි දෙයක් වෙලා. Keycloak වගේ open-source tool එකක් භාවිතා කරන එකෙන් ඔයාලට මේ functionality එක පහසුවෙන් implement කරගන්න පුළුවන්.

ඔයාලට මේ article එක ගැන මොනවා හරි ගැටලු තියෙනවා නම්, හරි ඔයාලගේ අත්දැකීම් share කරන්න ඕනේ නම්, පහළින් comment එකක් දාන්න. අපි ඒ ගැන කතා කරමු. මේ concept එක තව දුරටත් explore කරන්න. තව දේවල් ඉගෙන ගන්න. එහෙනම්, ආයෙත් අලුත් article එකකින් හම්බවෙමු! ජය වේවා!