0
# HTTP Request/Response Abstraction
1

2
Platform-agnostic HTTP handling providing request and response facades, cookie management, and certificate chain access. This abstraction layer enables Keycloak adapters to work uniformly across different Java web frameworks and application servers.
3

4
## Capabilities
5

6
### HttpFacade Interface
7

8
Main HTTP abstraction interface providing access to request and response facades along with certificate chain information for SSL/TLS connections.
9

10
```java { .api }
11
import javax.security.cert.X509Certificate;
12

13
/**
14
 * Platform-agnostic HTTP abstraction for Keycloak adapters
15
 */
16
public interface HttpFacade {
17
    /**
18
     * Gets the HTTP request facade
19
     * @return Request facade for accessing request data
20
     */
21
    Request getRequest();
22
    
23
    /**
24
     * Gets the HTTP response facade  
25
     * @return Response facade for writing response data
26
     */
27
    Response getResponse();
28
    
29
    /**
30
     * Gets the X.509 certificate chain for SSL/TLS connections
31
     * @return Array of X509Certificate objects, or null if not available
32
     */
33
    X509Certificate[] getCertificateChain();
34
}
35
```
36

37
### Request Interface
38

39
HTTP request abstraction providing access to request data, parameters, headers, and cookies.
40

41
```java { .api }
42
import java.io.InputStream;
43
import java.util.List;
44

45
/**
46
 * HTTP request abstraction
47
 */
48
public interface HttpFacade.Request {
49
    /**
50
     * Gets the HTTP method (GET, POST, etc.)
51
     * @return HTTP method string
52
     */
53
    String getMethod();
54
    
55
    /**
56
     * Gets the full request URI including query parameters
57
     * @return Complete request URI
58
     */
59
    String getURI();
60
    
61
    /**
62
     * Gets the request relative path without query parameters
63
     * @return Relative path portion of the request
64
     */
65
    String getRelativePath();
66
    
67
    /**
68
     * Checks if the request is using HTTPS
69
     * @return true if HTTPS is used, false otherwise
70
     */
71
    boolean isSecure();
72
    
73
    /**
74
     * Gets the first query or form parameter value
75
     * @param param Parameter name
76
     * @return First parameter value, or null if not found
77
     */
78
    String getFirstParam(String param);
79
    
80
    /**
81
     * Gets a query parameter value
82
     * @param param Parameter name  
83
     * @return Query parameter value, or null if not found
84
     */
85
    String getQueryParamValue(String param);
86
    
87
    /**
88
     * Gets a cookie by name
89
     * @param cookieName Cookie name
90
     * @return Cookie object, or null if not found
91
     */
92
    Cookie getCookie(String cookieName);
93
    
94
    /**
95
     * Gets a header value
96
     * @param name Header name
97
     * @return Header value, or null if not found
98
     */
99
    String getHeader(String name);
100
    
101
    /**
102
     * Gets all header values for a given name
103
     * @param name Header name
104
     * @return List of all header values for the name
105
     */
106
    List<String> getHeaders(String name);
107
    
108
    /**
109
     * Gets the request input stream
110
     * @return InputStream for reading request body
111
     */
112
    InputStream getInputStream();
113
    
114
    /**
115
     * Gets the request input stream with buffering option
116
     * @param buffered Whether to buffer the input stream
117
     * @return InputStream for reading request body
118
     */
119
    InputStream getInputStream(boolean buffered);
120
    
121
    /**
122
     * Gets the remote client address
123
     * @return Remote address string
124
     */
125
    String getRemoteAddr();
126
    
127
    /**
128
     * Sets an authentication error for retrieval by the application
129
     * @param error Authentication error instance
130
     */
131
    void setError(AuthenticationError error);
132
    
133
    /**
134
     * Sets a logout error for retrieval by the application
135
     * @param error Logout error instance
136
     */
137
    void setError(LogoutError error);
138
}
139
```
140

141
### Response Interface
142

143
HTTP response abstraction for writing response data, setting headers, cookies, and status codes.
144

145
```java { .api }
146
import java.io.OutputStream;
147

148
/**
149
 * HTTP response abstraction
150
 */
151
public interface HttpFacade.Response {
152
    /**
153
     * Sets the HTTP response status code
154
     * @param status HTTP status code (200, 404, 500, etc.)
155
     */
156
    void setStatus(int status);
157
    
158
    /**
159
     * Adds a header to the response (allows multiple values)
160
     * @param name Header name
161
     * @param value Header value
162
     */
163
    void addHeader(String name, String value);
164
    
165
    /**
166
     * Sets a header in the response (replaces existing)
167
     * @param name Header name
168
     * @param value Header value
169
     */
170
    void setHeader(String name, String value);
171
    
172
    /**
173
     * Resets/clears a cookie by setting it with empty value and past expiration
174
     * @param name Cookie name
175
     * @param path Cookie path
176
     */
177
    void resetCookie(String name, String path);
178
    
179
    /**
180
     * Sets a cookie with all available options
181
     * @param name Cookie name
182
     * @param value Cookie value
183
     * @param path Cookie path
184
     * @param domain Cookie domain
185
     * @param maxAge Cookie max age in seconds
186
     * @param secure Whether cookie should only be sent over HTTPS
187
     * @param httpOnly Whether cookie should be HTTP-only (not accessible via JavaScript)
188
     */
189
    void setCookie(String name, String value, String path, String domain, 
190
                   int maxAge, boolean secure, boolean httpOnly);
191
    
192
    /**
193
     * Gets the response output stream for writing response body
194
     * @return OutputStream for writing response data
195
     */
196
    OutputStream getOutputStream();
197
    
198
    /**
199
     * Sends an HTTP error response with status code
200
     * @param code HTTP error code
201
     */
202
    void sendError(int code);
203
    
204
    /**
205
     * Sends an HTTP error response with status code and message
206
     * @param code HTTP error code
207
     * @param message Error message
208
     */
209
    void sendError(int code, String message);
210
    
211
    /**
212
     * Ends the response if processing is finished
213
     */
214
    void end();
215
}
216
```
217

218
### Cookie Class
219

220
HTTP cookie representation with standard cookie attributes.
221

222
```java { .api }
223
/**
224
 * HTTP cookie representation
225
 */
226
public static class HttpFacade.Cookie {
227
    /** Cookie name */
228
    protected String name;
229
    
230
    /** Cookie value */
231
    protected String value;
232
    
233
    /** Cookie version */
234
    protected int version;
235
    
236
    /** Cookie domain */
237
    protected String domain;
238
    
239
    /** Cookie path */
240
    protected String path;
241
    
242
    /**
243
     * Cookie constructor
244
     * @param name Cookie name
245
     * @param value Cookie value
246
     * @param version Cookie version
247
     * @param domain Cookie domain
248
     * @param path Cookie path
249
     */
250
    public Cookie(String name, String value, int version, String domain, String path);
251
    
252
    /**
253
     * Gets the cookie name
254
     * @return Cookie name
255
     */
256
    public String getName();
257
    
258
    /**
259
     * Gets the cookie value
260
     * @return Cookie value
261
     */
262
    public String getValue();
263
    
264
    /**
265
     * Gets the cookie version
266
     * @return Cookie version
267
     */
268
    public int getVersion();
269
    
270
    /**
271
     * Gets the cookie domain
272
     * @return Cookie domain
273
     */
274
    public String getDomain();
275
    
276
    /**
277
     * Gets the cookie path
278
     * @return Cookie path
279
     */
280
    public String getPath();
281
}
282
```
283

284
## Usage Examples
285

286
### Basic HTTP Facade Implementation
287

288
```java
289
import org.keycloak.adapters.spi.HttpFacade;
290
import javax.servlet.http.HttpServletRequest;
291
import javax.servlet.http.HttpServletResponse;
292

293
public class ServletHttpFacade implements HttpFacade {
294
    private final HttpServletRequest request;
295
    private final HttpServletResponse response;
296
    
297
    public ServletHttpFacade(HttpServletRequest request, HttpServletResponse response) {
298
        this.request = request;
299
        this.response = response;
300
    }
301
    
302
    @Override
303
    public Request getRequest() {
304
        return new ServletRequest(request);
305
    }
306
    
307
    @Override
308
    public Response getResponse() {
309
        return new ServletResponse(response);
310
    }
311
    
312
    @Override
313
    public X509Certificate[] getCertificateChain() {
314
        return (X509Certificate[]) request.getAttribute("javax.servlet.request.X509Certificate");
315
    }
316
}
317
```
318

319
### Request Parameter Access
320

321
```java
322
HttpFacade.Request request = httpFacade.getRequest();
323

324
// Check request method and security
325
if ("POST".equals(request.getMethod()) && request.isSecure()) {
326
    // Access parameters and headers
327
    String authCode = request.getFirstParam("code");
328
    String authHeader = request.getHeader("Authorization");
329
    
330
    // Access cookies
331
    HttpFacade.Cookie sessionCookie = request.getCookie("JSESSIONID");
332
    if (sessionCookie != null) {
333
        String sessionId = sessionCookie.getValue();
334
    }
335
}
336
```
337

338
### Response Management
339

340
```java
341
HttpFacade.Response response = httpFacade.getResponse();
342

343
// Set response status and headers
344
response.setStatus(200);
345
response.setHeader("Content-Type", "application/json");
346
response.addHeader("Cache-Control", "no-cache");
347

348
// Set cookies
349
response.setCookie("auth-token", "abc123", "/", ".example.com", 3600, true, true);
350

351
// Write response body
352
try (OutputStream out = response.getOutputStream()) {
353
    out.write("{\"status\":\"success\"}".getBytes());
354
}
355
response.end();
356
```