Problem Statement

Currently, Keycloak returns refresh tokens in the response body, which exposes them to JavaScript and makes them vulnerable to XSS attacks. Many modern web applications require storing refresh tokens in HTTP-Only cookies for enhanced security.

Proposed Solution

Add a client-level or realm-level configuration option to store refresh tokens in HTTP-Only cookies instead of the response body.

Configuration Options

Option 1: Client Setting

Clients → [Client Name] → Settings → Advanced
☑ Store Refresh Token in HTTP-Only Cookie

Option 2: Realm Setting

Realm Settings → Tokens
☑ Use HTTP-Only Cookies for Refresh Tokens (Global)

Expected Behavior

When enabled:

1. Token endpoint response body:

   {
     "access_token": "...",
     "token_type": "Bearer",
     "expires_in": 300
     // refresh_token removed from body
   }

2. Token endpoint response headers:

   Set-Cookie: KEYCLOAK_REFRESH_TOKEN=...; HttpOnly; Secure; SameSite=Strict; Path=/realms/{realm}/protocol/openid-connect

3. Refresh token grant automatically reads from cookie

Security Benefits

• ✅ Protection against XSS attacks
• ✅ Reduced attack surface (JavaScript cannot access refresh tokens)
• ✅ Compliance with OWASP best practices
• ✅ Better alignment with modern web security standards

Use Cases

1. Single Page Applications (SPAs) with high security requirements
2. Web applications that cannot safely store tokens in localStorage