Keycloak Client Configuration & Advanced Authentication Flows SC Guide

ඉතින් කොහොමද යාළුවනේ? මේ දවස් වල Software Development පැත්තෙන් ගොඩක් අය කතා කරන, ගොඩක් වැදගත් මාතෘකාවක් තමයි Authentication සහ Authorization කියන්නේ. අද කාලේ අපි හදන applications වල security එක කියන දේ ඉතාම අත්‍යවශ්‍ය දෙයක් වෙලා. මේකට අපිට ලොකු උදව්වක් දෙන Open Source Identity and Access Management (IAM) විසඳුමක් තමයි Keycloak කියන්නේ.

Keycloak කියන්නේ නිකම්ම user login එකක් manage කරන system එකක් නෙවෙයි. ඒකෙන් අපිට Single Sign-On (SSO), Social Logins, Identity Brokering වගේ ගොඩක් දේවල් කරන්න පුළුවන්. ඒත් මේ හැමදේකම මූලිකම පදනම තමයි Client Configuration එකයි Authentication Flows ටිකයි හරියට තේරුම් ගැනීම. අද මේ article එකෙන් අපි Keycloak clients කියන්නේ මොනවද, ඒවගේ වර්ග මොනවද, ඒවට අදාළ වන advanced authentication flows වන Authorization Code Flow එකයි, Client Credentials Flow එකයි සහ Keycloak session management, SSO කියන concepts ගැන ගැඹුරින් කතා කරමු. මේවා හරියට තේරුම් ගත්තොත් ඔයාලගේ applications වල security එක වැඩි කරගන්න එක ලොකු දෙයක් නෙවෙයි!

මේ ගමනට සූදානම් ද? එහෙනම් පටන් ගමු!

Keycloak Clients වර්ග කරමු: Public ද? Confidential ද?

මුලින්ම බලමු මේ "Client" කියන්නේ මොකක්ද කියලා. Keycloak context එකේදී client කෙනෙක් කියන්නේ user කෙනෙක් වෙනුවෙන් හෝ තමන් වෙනුවෙන් Keycloak එකෙන් authentication හෝ authorization service එකක් ඉල්ලන entity එකක්. සරලව කිව්වොත්, Keycloak එකට connect වෙන ඕනෑම application එකක්, service එකක්, නැත්නම් device එකක් තමයි client කෙනෙක් වෙන්නේ. උදාහරණයක් විදිහට, ඔයාගේ web application එක, mobile app එක, backend service එකක් වගේ දේවල් client කෙනෙක් වෙන්න පුළුවන්.

මේ clients ලා ප්‍රධාන වශයෙන් වර්ග දෙකකට බෙදෙනවා: Public Clients සහ Confidential Clients. මේ දෙක අතර තියෙන වෙනස හරියට තේරුම් ගැනීම ඔයාලගේ application එකේ security එකට අත්‍යවශ්‍යයි.

Public Clients (ප්‍රසිද්ධ Clients)

• මොකක්ද මේ? Public clients කියන්නේ client secret එකක් ආරක්ෂිතව තියාගන්න බැරි clients ලා. ඒ කියන්නේ, මේ clients ලා deploy කරලා තියෙන්නේ client secret එකක් එලියේ තියෙන තැනක, user කෙනෙකුට access කරන්න පුළුවන් තැනක.
• උදාහරණ: Single Page Applications (SPAs) (React, Angular, Vue.js වගේ), Mobile Applications (Android, iOS), Desktop Applications. මේවායේ code එක browser එකේ නැත්නම් user ගේ device එකේ run වෙන නිසා client secret එකක් code එක ඇතුළේ දැම්මොත්, ඕනෑම කෙනෙකුට ඒක බලන්න පුළුවන්.
• ආරක්ෂාව: client secret එකක් නැති නිසා, මේවායේ ආරක්ෂාවට Keycloak විසින් Proof Key for Code Exchange (PKCE) කියන extension එක යොදාගන්නවා. PKCE එකෙන් කරන්නේ Authorization Code Flow එක තවදුරටත් ආරක්ෂා කරන එක. මේක client එකයි Keycloak එකයි අතර තියෙන code exchange එකට අමතර verification layer එකක් එකතු කරනවා. ඒක ගැන Authorization Code Flow section එකේදී තව දුරටත් කතා කරමු.

Confidential Clients (රහසිගත Clients)

• මොකක්ද මේ? Confidential clients කියන්නේ client secret එකක් ආරක්ෂිතව තියාගන්න පුළුවන් clients ලා. මේවා server-side applications වෙන නිසා client secret එක server එක ඇතුලේ ආරක්ෂිතව තියන්න පුළුවන්.
• උදාහරණ: Traditional Web Applications (server-rendered apps like Java Spring Boot, Node.js Express), Backend Services, Microservices. මේවායේ code එක server එකේ run වෙන නිසා client secret එක එලියට පේන්නේ නැහැ.
• ආරක්ෂාව: මේ clients ලා authentication request එක යවනකොට client secret එකත් එක්කම යවනවා. Keycloak එක ඒ secret එක verify කරලා තමයි access token එක දෙන්නේ. මේකෙන් Keycloak එකට හරියටම client කවුද කියලා තහවුරු කරගන්න පුළුවන්.

දැන් ඔයාලට Public Clients සහ Confidential Clients අතර වෙනස පැහැදිලියි නේද? ඔයාලගේ application එකේ ස්වභාවය අනුව නිවැරදි client type එක තෝරාගැනීම ගොඩක් වැදගත්.

Security එකට අත දෙමු: Authorization Code Flow

හරි, දැන් අපි කතා කරමු Keycloak එකේදී authentication සඳහා බහුලවම භාවිතා වන සහ ඉතාම ආරක්ෂිත Flow එකක් ගැන: Authorization Code Flow එක. මේක විශේෂයෙන්ම Public Clients (web applications, mobile apps) සඳහා නිර්දේශ කෙරෙනවා. මේකෙදි කෙලින්ම Access Token එක user ගේ browser එකට යවනවා වෙනුවට, Authorization Code එකක් යවලා, ඒකෙන් server-side (හෝ client-side ආරක්ෂිතව) Access Token එකක් obtain කරන එක තමයි වෙන්නේ. මේකෙන් security එක ගොඩක් වැඩි වෙනවා.

අපි මේ flow එක පියවරෙන් පියවරට තේරුම් ගමු:

1. User Request (පරිශීලක ඉල්ලීම): user කෙනෙක් ඔයාගේ application එකට (client) පිවිසෙන්න උත්සාහ කරනවා.
2. Redirect to Keycloak (Keycloak වෙත යොමු කිරීම): application එක user ව Keycloak login page එකට redirect කරනවා. මේ redirect එකේදී client ID එක, redirect URI එක, request කරන scopes (e.g., openid, profile, email) සහ PKCE parameters (code challenge, code challenge method - Public Clients වලට) වගේ දේවල් යවනවා.
3. User Authentication (පරිශීලක සත්‍යාපනය): user Keycloak login page එකේදී එයාගේ username සහ password දාලා login වෙනවා. Keycloak එක user ව authenticate කරනවා.
4. Authorization Code Grant (Authorization Code එක නිකුත් කිරීම): සාර්ථකව login වුන පස්සේ, Keycloak එක Authorization Code එකක් generate කරලා, ඒක user ගේ browser එක හරහා application එකේ redirect URI එකට යවනවා. මේ code එක ඉතා කෙටි වෙලාවකට (usually few seconds) වලංගුයි.
5. Code Exchange for Tokens (Code එක Tokens සඳහා හුවමාරු කිරීම): application එක (client) මේ ලැබුණු Authorization Code එක Keycloak token endpoint එකට POST request එකක් විදිහට යවනවා. මේ request එකේදී client ID එක, redirect URI එක, Authorization Code එක සහ PKCE code verifier එකත් (Public Clients වලට) අනිවාර්යයෙන්ම යවනවා. Confidential Clients නම් මේ වෙලාවේ client secret එකත් යවනවා.
6. Token Issuance (Token නිකුත් කිරීම): Keycloak එක ලැබුණු code එක සහ අනෙකුත් details verify කරලා (විශේෂයෙන්ම PKCE parameters match වෙනවද කියලා), Valid නම් Access Token, ID Token සහ Refresh Token එකක් client එකට නිකුත් කරනවා.
7. Access Resource (Resource වෙත පිවිසීම): application එක ලැබුණු Access Token එක භාවිතා කරලා ආරක්ෂිත resources (e.g., APIs) access කරනවා. Access Token එක JWT (JSON Web Token) එකක් නිසා, resource server එකට පුළුවන් token එකේ තියෙන user information (claims) verify කරලා access දෙන්න.

Authorization Code Flow එකේ වාසි:

• ඉහල ආරක්ෂාව: Access Token එක කෙලින්ම browser එකට යවන්නේ නැති නිසා Man-in-the-Middle attacks වලින් ආරක්ෂා වෙනවා.
• Refresh Tokens: Access Tokens වලට සාපේක්ෂව දිගු කාලයක් වලංගු Refresh Tokens ලබාදෙන නිසා user ට නැවත නැවත login වෙන්න අවශ්‍ය වෙන්නේ නැහැ.
• Scope Control: Application එකට අවශ්‍ය අවම scopes (permissions) ඉල්ලන්න පුළුවන්.

මෙන්න පොඩි pseudo-code snippet එකක්, client-side JavaScript (React/Angular) වලින් මේක initiate කරන විදිහ ගැන අදහසක් ගන්න:

// Example: Initiating Authorization Code Flow from a React app
const clientId = 'my-react-app';
const redirectUri = 'http://localhost:3000/callback';
const keycloakAuthUrl = 'http://localhost:8080/auth/realms/myrealm/protocol/openid-connect/auth';
const scope = 'openid profile email';

// For PKCE (Public Clients)
async function generatePkce() {
    const codeVerifier = base64URLEncode(crypto.getRandomValues(new Uint8Array(32)));
    const codeChallenge = base64URLEncode(await sha256(codeVerifier));
    return { codeVerifier, codeChallenge };
}

async function login() {
    const { codeVerifier, codeChallenge } = await generatePkce();
    localStorage.setItem('code_verifier', codeVerifier); // Store for later use

    const authUrl = `${keycloakAuthUrl}?response_type=code&client_id=${clientId}&redirect_uri=${encodeURIComponent(redirectUri)}&scope=${encodeURIComponent(scope)}&code_challenge=${codeChallenge}&code_challenge_method=S256`;
    window.location.href = authUrl;
}

// In your redirect URI callback component
async function handleCallback() {
    const urlParams = new URLSearchParams(window.location.search);
    const code = urlParams.get('code');
    const codeVerifier = localStorage.getItem('code_verifier');

    if (code && codeVerifier) {
        const tokenUrl = 'http://localhost:8080/auth/realms/myrealm/protocol/openid-connect/token';
        const response = await fetch(tokenUrl, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded'
            },
            body: new URLSearchParams({
                grant_type: 'authorization_code',
                client_id: clientId,
                redirect_uri: redirectUri,
                code: code,
                code_verifier: codeVerifier
            })
        });
        const tokens = await response.json();
        console.log('Access Token:', tokens.access_token);
        // Store tokens securely and use them
    }
}

මේක තරමක් සංකීර්ණ වගේ පෙනුනත්, Keycloak client libraries (e.g., keycloak-js for JavaScript) මේ සංකීර්ණත්වය අපෙන් ඈත් කරලා, සරල API එකක් හරහා මේ flow එක implement කරන්න පහසුකම් සලසනවා.

Machine-to-Machine Talks: Client Credentials Flow

හරි, දැන් අපි කතා කරමු user කෙනෙක් සම්බන්ධ නැති, machine-to-machine communication සඳහා භාවිතා වන ඉතා වැදගත් Flow එකක් ගැන: Client Credentials Flow. මේක සාමාන්‍යයෙන් භාවිතා වෙන්නේ backend services, microservices, daemons වගේ applications වලට වෙනත් services වලට access කරන්න අවශ්‍ය වුනාමයි. මෙතන user authentication එකක් නැහැ, client (application) විසින් තමන්වම authenticate කරගෙන access token එකක් ලබාගන්නවා.

මේ flow එකේදී වෙන්නේ මොකක්ද කියලා බලමු:

1. Client Request (Client ඉල්ලීම): Backend service එකක් හෝ daemon එකක් ආරක්ෂිත API එකකට access කරන්න අවශ්‍ය වුනාම, එය කෙලින්ම Keycloak token endpoint එකට POST request එකක් යවනවා.
2. Credentials (අවශ්‍ය දත්ත): මේ request එකේදී client ID එක සහ client secret එක (Keycloak client එක Confidential Client එකක් විය යුතුයි) HTTP Basic Authentication header එකක් විදිහට හෝ form parameters විදිහට යවනවා. Grant type එක හැමවිටම client_credentials විය යුතුයි.
3. Token Issuance (Token නිකුත් කිරීම): Keycloak එක client ID එක සහ client secret එක verify කරලා (Valid නම්), access token එකක් (සමහරවිට refresh token එකකුත්) client එකට නිකුත් කරනවා.
4. Access Resource (Resource වෙත පිවිසීම): client එක මේ ලැබුණු access token එක authorization header එකක් විදිහට යවලා ආරක්ෂිත API එකට access කරනවා.

Client Credentials Flow එකේ වාසි:

• User නැති අවස්ථා සඳහා: User interaction එකක් නැති server-to-server communication වලට ඉතාම සුදුසුයි.
• සරලයි: Authorization Code Flow එකට සාපේක්ෂව සරලයි, redirect කිරීම්, code exchange කිරීම් වගේ දේවල් නැහැ.
• කාර්යක්ෂමයි: ඉක්මනින් tokens ලබාගන්න පුළුවන්.

මෙන්න curl command එකක්, client credentials flow එකෙන් access token එකක් ගන්න විදිහ පෙන්නන්න:

# Example: Getting an access token using Client Credentials Flow with curl
# Replace with your actual Keycloak URL, Realm, Client ID, and Client Secret

curl -X POST \
  "http://localhost:8080/auth/realms/myrealm/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=my-backend-service" \
  -d "client_secret=YOUR_CLIENT_SECRET"

සාර්ථක ප්‍රතිචාරයක් මෙන්න මේ වගේ වෙන්න පුළුවන්:

{
  "access_token": "eyJhbGciOiJ...",
  "expires_in": 300,
  "refresh_token": "eyJhbGciOiJ...",
  "token_type": "bearer",
  "not-before-policy": 0,
  "session_state": "...",
  "scope": "openid"
}

මේ token එක ලැබුනම, ඔයාලට ඒක භාවිතා කරලා ආරක්ෂිත APIs call කරන්න පුළුවන්. උදාහරණයක් විදිහට:

curl -X GET \
  "http://localhost:8081/api/protected-resource" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

දැන් ඔයාලට පැහැදිලියි නේද, මේ flows දෙකම වෙනස් scenarios වලදී කොහොමද භාවිතා වෙන්නේ කියලා?

Session Management සහ SSO මැජික්

Keycloak වල තියෙන තවත් සුපිරි features දෙකක් තමයි Session Management සහ Single Sign-On (SSO) කියන්නේ. මේ දෙක user experience එකයි, security එකයි දෙකම එකපාර වැඩි කරනවා.

Keycloak Session Management

Keycloak එකෙන් user login වෙද්දි, Keycloak server එකේ user session එකක් හදනවා. මේ session එක user ගේ authentication state එක manage කරනවා. මේකෙදි ප්‍රධාන concepts දෙකක් තියෙනවා:

• Idle Timeout: User කෙනෙක් කිසිම ක්‍රියාවක් නොකරන වෙලාවට session එක active වෙලා තියෙන උපරිම කාලය. මේකෙන් වෙන්නේ user කෙනෙක් දිගු වෙලාවක් inactive වුනොත් automatically logout වෙන එක. Security එකට මේක ගොඩක් වැදගත්.
• Max Life: Session එකක උපරිම ජීවන කාලය. මේ කාලය ඇතුළත user කොච්චර active වුනත් මේ කාලයෙන් පස්සේ user ව logout කරනවා. මේකත් security එකට අතිශයින්ම වැදගත්.

මේ timeouts Keycloak Admin Console එකේ Realm Settings යටතේ Login tab එකෙන් configure කරන්න පුළුවන්. මේවා නිවැරදිව configure කිරීමෙන් security breaches අවම කරගන්න පුළුවන්.

Single Sign-On (SSO) මැජික්

SSO කියන්නේ "එක පාරක් login වෙලා, වෙනස් applications ගොඩකට access කරන්න පුළුවන්" කියන concept එක. Keycloak එක මේ SSO functionality එකට හොඳටම support කරනවා.

හිතන්න, ඔයාලට applications කිහිපයක් තියෙනවා කියලා: web portal එකක්, mobile app එකක්, admin dashboard එකක් වගේ. මේ හැම එකටම වෙන වෙනම login වෙන්නේ නැතුව, Keycloak එකට එක පාරක් login වුනාම ඒ හැම application එකටම access කරන්න පුළුවන් නම් කොච්චර පහසුද?

මේක වෙන්නේ මෙහෙමයි: user කෙනෙක් Keycloak එකට login වුනාම, Keycloak එක user ගේ browser එකේ session cookie එකක් set කරනවා. ඊට පස්සේ user වෙනත් application එකකට යන්න හැදුවොත්, ඒ application එකත් Keycloak හරහා authentication ඉල්ලනකොට, Keycloak එකට පුළුවන් ඒ session cookie එක detect කරලා, user ව නැවත login page එකට යොමු නොකර කෙලින්ම authentication code එක ලබාදෙන්න. මේකෙන් user ට ඉතාම සුමට අත්දැකීමක් ලැබෙනවා.

SSO වල වාසි:

• වැඩි දියුණු වූ User Experience: User ට නිතරම login වෙන්න අවශ්‍ය නැහැ.
• වැඩි දියුණු වූ Security: Passwords මත යැපීම අඩු වෙනවා, password fatigue එක අඩු වෙනවා.
• පහසු Administration: User accounts centralised තියෙන නිසා manage කරන්න පහසුයි.

Keycloak client configuration වලදී Realm Settings යටතේ Client Session Max/Idle Time, SSO Master Realm Session Max/Idle Time වගේ දේවල් හරියට configure කරන්න අමතක කරන්න එපා. මේවා ඔයාලගේ security policy එකට අනුව adjust කරන්න ඕන.

අවසානයට (Wrapping Up)

ඉතින් යාළුවනේ, මේ article එකෙන් අපි Keycloak clients ලා ගැනත්, Authorization Code Flow එකයි, Client Credentials Flow එකයි ගැනත්, Session Management සහ SSO වල වැදගත්කම ගැනත් ගැඹුරින් කතා කළා. මේ concepts ඔයාලගේ applications වල robust security architecture එකක් ගොඩනගන්න අත්‍යවශ්‍යයි. Keycloak කියන්නේ ගොඩක් powerful tool එකක්, ඒක හරියට භාවිතා කරන්න පුළුවන් නම්, security පැත්තෙන් ගොඩක් දේවල් automate කරලා, developer ලාට core business logic එකට අවධානය යොමු කරන්න පුළුවන් වෙනවා.

මේ කතා කරපු දේවල් ඔයාලට අලුත් දැනුමක් එකතු කලා කියලා හිතනවා. මතක තියාගන්න, security කියන්නේ එක පාරක් implement කරලා අතාරින දෙයක් නෙවෙයි, ඒක දිගින් දිගටම maintain කරන්න ඕන දෙයක්. මේ flows හරිහැටි තේරුම් අරන්, ඔයාලගේ applications වලට implement කරලා බලන්න.

මේ ගැන ඔයාලට තව මොනවා හරි දැනගන්න ඕන නම්, ප්‍රශ්න තියෙනවා නම්, නැත්නම් ඔයාලගේ අත්දැකීම් බෙදාගන්න කැමති නම්, පහලින් comment එකක් දාන්න. අපි ඊළඟ article එකෙන් හමුවෙමු! Happy Coding!