0
# Session Management
1

2
Comprehensive session mapping and management capabilities for correlating SSO sessions with application sessions, including user session management and request storage. These interfaces enable Keycloak adapters to maintain consistent session state across different application server environments.
3

4
## Capabilities
5

6
### SessionIdMapper Interface
7

8
Core interface for mapping between user session IDs, principals, and HTTP session IDs in Keycloak adapters. This enables correlation between Keycloak's SSO sessions and application-specific HTTP sessions.
9

10
```java { .api }
11
import java.util.Set;
12

13
/**
14
 * Interface for mapping between user session IDs, principals, and HTTP session IDs
15
 */
16
public interface SessionIdMapper {
17
    /**
18
     * Checks if the mapper contains a mapping for the given HTTP session ID
19
     * @param id HTTP session ID
20
     * @return true if mapping exists, false otherwise
21
     */
22
    boolean hasSession(String id);
23
    
24
    /**
25
     * Clears all mappings from this mapper
26
     */
27
    void clear();
28
    
29
    /**
30
     * Gets all HTTP session IDs associated with the given principal
31
     * @param principal User principal
32
     * @return Set of HTTP session IDs for the principal
33
     */
34
    Set<String> getUserSessions(String principal);
35
    
36
    /**
37
     * Gets the HTTP session ID from the given user session ID
38
     * @param sso User session ID (SSO session)
39
     * @return HTTP session ID, or null if not found
40
     */
41
    String getSessionFromSSO(String sso);
42
    
43
    /**
44
     * Establishes mapping between user session ID, principal and HTTP session ID
45
     * @param sso User session ID (SSO session)
46
     * @param principal User principal
47
     * @param session HTTP session ID
48
     */
49
    void map(String sso, String principal, String session);
50
    
51
    /**
52
     * Removes all mappings for the given HTTP session ID
53
     * @param session HTTP session ID to remove
54
     */
55
    void removeSession(String session);
56
}
57
```
58

59
### InMemorySessionIdMapper Class
60

61
Thread-safe in-memory implementation of SessionIdMapper using concurrent hash maps for high-performance session mapping in multi-threaded environments.
62

63
```java { .api }
64
import java.util.concurrent.ConcurrentHashMap;
65
import java.util.Collections;
66
import java.util.HashSet;
67
import org.jboss.logging.Logger;
68

69
/**
70
 * In-memory implementation of SessionIdMapper that maps external principal and SSO ID
71
 * to internal local HTTP session ID using concurrent hash maps for thread safety
72
 */
73
public class InMemorySessionIdMapper implements SessionIdMapper {
74
    private static final Logger LOG = Logger.getLogger(InMemorySessionIdMapper.class.getName());
75
    
76
    /** Maps SSO session ID to HTTP session ID */
77
    ConcurrentHashMap<String, String> ssoToSession = new ConcurrentHashMap<>();
78
    
79
    /** Maps HTTP session ID to SSO session ID */
80
    ConcurrentHashMap<String, String> sessionToSso = new ConcurrentHashMap<>();
81
    
82
    /** Maps principal to set of HTTP session IDs */
83
    ConcurrentHashMap<String, Set<String>> principalToSession = new ConcurrentHashMap<>();
84
    
85
    /** Maps HTTP session ID to principal */
86
    ConcurrentHashMap<String, String> sessionToPrincipal = new ConcurrentHashMap<>();
87
    
88
    /**
89
     * Checks if session exists in mapper
90
     * @param id HTTP session ID
91
     * @return true if session mapping exists
92
     */
93
    public boolean hasSession(String id);
94
    
95
    /**
96
     * Clears all mappings
97
     */
98
    public void clear();
99
    
100
    /**
101
     * Gets user sessions for principal
102
     * @param principal User principal
103
     * @return Set of HTTP session IDs
104
     */
105
    public Set<String> getUserSessions(String principal);
106
    
107
    /**
108
     * Gets HTTP session from SSO session ID
109
     * @param sso SSO session ID
110
     * @return HTTP session ID
111
     */
112
    public String getSessionFromSSO(String sso);
113
    
114
    /**
115
     * Creates mapping between SSO, principal, and HTTP session
116
     * @param sso SSO session ID
117
     * @param principal User principal
118
     * @param session HTTP session ID
119
     */
120
    public void map(String sso, String principal, String session);
121
    
122
    /**
123
     * Removes session mapping
124
     * @param session HTTP session ID to remove
125
     */
126
    public void removeSession(String session);
127
}
128
```
129

130
### SessionIdMapperUpdater Interface
131

132
Mechanism for updating SessionIdMapper entries with predefined strategies for direct and external update patterns.
133

134
```java { .api }
135
/**
136
 * Interface representing a mechanism for updating SessionIdMapper entries
137
 */
138
public interface SessionIdMapperUpdater {
139
    /**
140
     * Clears all mappings from the given SessionIdMapper
141
     * @param idMapper SessionIdMapper to clear
142
     */
143
    void clear(SessionIdMapper idMapper);
144
    
145
    /**
146
     * Creates mapping between user session ID, principal and HTTP session ID
147
     * @param idMapper SessionIdMapper to update
148
     * @param sso User session ID
149
     * @param principal User principal
150
     * @param session HTTP session ID
151
     */
152
    void map(SessionIdMapper idMapper, String sso, String principal, String session);
153
    
154
    /**
155
     * Removes mapping for the given HTTP session ID
156
     * @param idMapper SessionIdMapper to update
157
     * @param session HTTP session ID to remove
158
     */
159
    void removeSession(SessionIdMapper idMapper, String session);
160
    
161
    /**
162
     * Refreshes mapping from internal source
163
     * @param idMapper SessionIdMapper to refresh
164
     * @param httpSessionId HTTP session ID to refresh
165
     * @return true if refresh was successful
166
     */
167
    boolean refreshMapping(SessionIdMapper idMapper, String httpSessionId);
168
    
169
    /** Direct updater that updates SessionIdMapper entries directly */
170
    public static final SessionIdMapperUpdater DIRECT = new SessionIdMapperUpdater() {
171
        @Override public void clear(SessionIdMapper idMapper) {
172
            idMapper.clear();
173
        }
174
        @Override public void map(SessionIdMapper idMapper, String sso, String principal, String httpSessionId) {
175
            idMapper.map(sso, principal, httpSessionId);
176
        }
177
        @Override public void removeSession(SessionIdMapper idMapper, String httpSessionId) {
178
            idMapper.removeSession(httpSessionId);
179
        }
180
        @Override public boolean refreshMapping(SessionIdMapper idMapper, String httpSessionId) {
181
            return false;
182
        }
183
    };
184
    
185
    /** External updater that doesn't update SessionIdMapper entries (updated by external means) */
186
    public static final SessionIdMapperUpdater EXTERNAL = new SessionIdMapperUpdater() {
187
        @Override public void clear(SessionIdMapper idMapper) { }
188
        @Override public void map(SessionIdMapper idMapper, String sso, String principal, String httpSessionId) { }
189
        @Override public void removeSession(SessionIdMapper idMapper, String httpSessionId) { }
190
        @Override public boolean refreshMapping(SessionIdMapper idMapper, String httpSessionId) { return false; }
191
    };
192
}
193
```
194

195
### UserSessionManagement Interface
196

197
Interface for managing user sessions with capabilities to log out all sessions or specific HTTP sessions.
198

199
```java { .api }
200
import java.util.List;
201

202
/**
203
 * Interface for managing user sessions
204
 */
205
public interface UserSessionManagement {
206
    /**
207
     * Logs out all sessions for the current user
208
     */
209
    void logoutAll();
210
    
211
    /**
212
     * Logs out specific HTTP sessions by their IDs
213
     * @param ids List of HTTP session IDs to log out
214
     */
215
    void logoutHttpSessions(List<String> ids);
216
}
217
```
218

219
### AdapterSessionStore Interface
220

221
Interface for storing and restoring HTTP requests during authentication flows, enabling request preservation across authentication redirects.
222

223
```java { .api }
224
/**
225
 * Interface for storing and restoring HTTP requests during authentication flows
226
 */
227
public interface AdapterSessionStore {
228
    /**
229
     * Saves the current HTTP request for later restoration
230
     */
231
    void saveRequest();
232
    
233
    /**
234
     * Restores a previously saved HTTP request
235
     * @return true if request was successfully restored, false otherwise
236
     */
237
    boolean restoreRequest();
238
}
239
```
240

241
## Usage Examples
242

243
### Basic Session Mapping
244

245
```java
246
import org.keycloak.adapters.spi.*;
247

248
// Create session mapper
249
SessionIdMapper sessionMapper = new InMemorySessionIdMapper();
250

251
// Map SSO session to HTTP session
252
String ssoSessionId = "keycloak-sso-123";
253
String principal = "user@example.com";  
254
String httpSessionId = "JSESSION-456";
255

256
sessionMapper.map(ssoSessionId, principal, httpSessionId);
257

258
// Check if session exists
259
if (sessionMapper.hasSession(httpSessionId)) {
260
    // Get SSO session from HTTP session
261
    String ssoId = sessionMapper.getSessionFromSSO(ssoSessionId);
262
    
263
    // Get all HTTP sessions for a user
264
    Set<String> userSessions = sessionMapper.getUserSessions(principal);
265
}
266

267
// Clean up when session ends
268
sessionMapper.removeSession(httpSessionId);
269
```
270

271
### Session Updater Usage
272

273
```java
274
// Use direct updater strategy
275
SessionIdMapperUpdater updater = SessionIdMapperUpdater.DIRECT;
276
SessionIdMapper mapper = new InMemorySessionIdMapper();
277

278
// Create mapping via updater
279
updater.map(mapper, "sso-123", "user@example.com", "http-456");
280

281
// Refresh mapping if needed
282
boolean refreshed = updater.refreshMapping(mapper, "http-456");
283

284
// Clean up via updater
285
updater.removeSession(mapper, "http-456");
286
```
287

288
### User Session Management
289

290
```java
291
public class MyUserSessionManager implements UserSessionManagement {
292
    private final SessionIdMapper sessionMapper;
293
    
294
    public MyUserSessionManager(SessionIdMapper sessionMapper) {
295
        this.sessionMapper = sessionMapper;
296
    }
297
    
298
    @Override
299
    public void logoutAll() {
300
        // Log out all sessions for current user
301
        String currentPrincipal = getCurrentPrincipal();
302
        Set<String> userSessions = sessionMapper.getUserSessions(currentPrincipal);
303
        
304
        for (String sessionId : userSessions) {
305
            invalidateHttpSession(sessionId);
306
            sessionMapper.removeSession(sessionId);
307
        }
308
    }
309
    
310
    @Override
311
    public void logoutHttpSessions(List<String> ids) {
312
        // Log out specific sessions
313
        for (String sessionId : ids) {
314
            invalidateHttpSession(sessionId);
315
            sessionMapper.removeSession(sessionId);
316
        }
317
    }
318
    
319
    private void invalidateHttpSession(String sessionId) {
320
        // Platform-specific session invalidation
321
    }
322
    
323
    private String getCurrentPrincipal() {
324
        // Get current user principal
325
        return "user@example.com";
326
    }
327
}
328
```
329

330
### Request Storage During Authentication
331

332
```java
333
public class MyAdapterSessionStore implements AdapterSessionStore {
334
    private final HttpServletRequest request;
335
    private final HttpSession session;
336
    
337
    public MyAdapterSessionStore(HttpServletRequest request) {
338
        this.request = request;
339
        this.session = request.getSession();
340
    }
341
    
342
    @Override
343
    public void saveRequest() {
344
        // Save request URL and parameters for post-auth redirect
345
        session.setAttribute("saved.request.url", request.getRequestURL().toString());
346
        session.setAttribute("saved.request.method", request.getMethod());
347
        
348
        // Save request parameters
349
        Map<String, String[]> params = request.getParameterMap();
350
        session.setAttribute("saved.request.params", params);
351
    }
352
    
353
    @Override
354
    public boolean restoreRequest() {
355
        String savedUrl = (String) session.getAttribute("saved.request.url");
356
        if (savedUrl != null) {
357
            // Restore request state and redirect
358
            session.removeAttribute("saved.request.url");
359
            session.removeAttribute("saved.request.method");
360
            session.removeAttribute("saved.request.params");
361
            
362
            // Perform redirect to saved URL
363
            redirectToSavedUrl(savedUrl);
364
            return true;
365
        }
366
        return false;
367
    }
368
    
369
    private void redirectToSavedUrl(String url) {
370
        // Platform-specific redirect implementation
371
    }
372
}
373
```