0
# Keycloak Adapter SPI
1

2
The Keycloak Adapter SPI (Service Provider Interface) is a Java library that defines the core interfaces and contracts for building Keycloak authentication adapters across different application server environments. It provides abstractions for HTTP request/response handling, session management, user authentication state, and error handling, enabling consistent authentication adapter implementations across various platforms like Jakarta EE, Spring, and other Java application servers.
3

4
## Package Information
5

6
- **Package Name**: keycloak-adapter-spi
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
      <groupId>org.keycloak</groupId>
13
      <artifactId>keycloak-adapter-spi</artifactId>
14
      <version>26.2.5</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import org.keycloak.adapters.spi.*;
22
```
23

24
For specific interfaces:
25

26
```java
27
import org.keycloak.adapters.spi.HttpFacade;
28
import org.keycloak.adapters.spi.AuthOutcome;
29
import org.keycloak.adapters.spi.AuthChallenge;
30
import org.keycloak.adapters.spi.KeycloakAccount;
31
import org.keycloak.adapters.spi.SessionIdMapper;
32
import org.keycloak.adapters.spi.InMemorySessionIdMapper;
33
import org.keycloak.adapters.spi.SessionIdMapperUpdater;
34
import org.keycloak.adapters.spi.UserSessionManagement;
35
import org.keycloak.adapters.spi.AdapterSessionStore;
36
import org.keycloak.adapters.spi.AuthenticationError;
37
import org.keycloak.adapters.spi.LogoutError;
38
```
39

40
## Basic Usage
41

42
```java
43
import org.keycloak.adapters.spi.*;
44
import javax.security.cert.X509Certificate;
45

46
// Implement HTTP facade for your platform
47
public class MyHttpFacade implements HttpFacade {
48
    @Override
49
    public Request getRequest() { /* implementation */ }
50
    
51
    @Override
52
    public Response getResponse() { /* implementation */ }
53
    
54
    @Override
55
    public X509Certificate[] getCertificateChain() { /* implementation */ }
56
}
57

58
// Use session mapping for multi-session management
59
SessionIdMapper sessionMapper = new InMemorySessionIdMapper();
60
sessionMapper.map("sso-session-123", "user@example.com", "http-session-456");
61

62
// Handle authentication outcomes
63
public void handleAuth(AuthOutcome outcome) {
64
    switch (outcome) {
65
        case AUTHENTICATED:
66
            // Process successful authentication
67
            break;
68
        case FAILED:
69
            // Handle authentication failure
70
            break;
71
        case NOT_ATTEMPTED:
72
            // No authentication attempted
73
            break;
74
        // ... handle other outcomes
75
    }
76
}
77
```
78

79
## Architecture
80

81
The Keycloak Adapter SPI follows a clean interface-based design with several key components:
82

83
- **HTTP Abstraction Layer**: `HttpFacade` provides platform-agnostic HTTP request/response handling
84
- **Session Management**: Multiple interfaces for mapping between SSO sessions, user principals, and HTTP sessions
85
- **Authentication State**: Enums and interfaces for tracking authentication outcomes and errors
86
- **Request Storage**: `AdapterSessionStore` for preserving request state during authentication flows
87
- **Challenge Handling**: `AuthChallenge` interface for implementing protocol-specific authentication challenges
88

89
This architecture enables platform-specific adapter implementations while maintaining consistent authentication patterns across different Java web frameworks and application servers.
90

91
## Capabilities
92

93
### HTTP Request/Response Abstraction
94

95
Platform-agnostic HTTP handling with request and response facades, cookie management, and certificate chain access. Essential for building adapters that work across different web frameworks.
96

97
```java { .api }
98
public interface HttpFacade {
99
    Request getRequest();
100
    Response getResponse();
101
    X509Certificate[] getCertificateChain();
102
}
103
```
104

105
[HTTP Facade](./http-facade.md)
106

107
### Session Management
108

109
Comprehensive session mapping and management capabilities for correlating SSO sessions with application sessions, including user session management and request storage.
110

111
```java { .api }
112
public interface SessionIdMapper {
113
    boolean hasSession(String id);
114
    void clear();
115
    Set<String> getUserSessions(String principal);
116
    String getSessionFromSSO(String sso);
117
    void map(String sso, String principal, String session);
118
    void removeSession(String session);
119
}
120

121
public class InMemorySessionIdMapper implements SessionIdMapper {
122
    // Thread-safe in-memory implementation
123
}
124
```
125

126
[Session Management](./session-management.md)
127

128
### Authentication State Management
129

130
Authentication outcome tracking, user account representation, and error handling for comprehensive authentication flow management.
131

132
```java { .api }
133
public enum AuthOutcome {
134
    NOT_ATTEMPTED, FAILED, AUTHENTICATED, NOT_AUTHENTICATED, LOGGED_OUT
135
}
136

137
public interface KeycloakAccount {
138
    Principal getPrincipal();
139
    Set<String> getRoles();
140
}
141

142
public interface AuthChallenge {
143
    boolean challenge(HttpFacade exchange);
144
    int getResponseCode();
145
}
146
```
147

148
[Authentication](./authentication.md)
149

150
## Types
151

152
### Core Session Types
153

154
```java { .api }
155
public interface SessionIdMapperUpdater {
156
    void clear(SessionIdMapper idMapper);
157
    void map(SessionIdMapper idMapper, String sso, String principal, String httpSessionId);
158
    void removeSession(SessionIdMapper idMapper, String httpSessionId);
159
    boolean refreshMapping(SessionIdMapper idMapper, String httpSessionId);
160
    
161
    // Predefined update strategies
162
    SessionIdMapperUpdater DIRECT = /* direct update implementation */;
163
    SessionIdMapperUpdater EXTERNAL = /* external update implementation */;
164
}
165

166
public interface UserSessionManagement {
167
    void logoutAll();
168
    void logoutHttpSessions(List<String> ids);
169
}
170

171
public interface AdapterSessionStore {
172
    void saveRequest();
173
    boolean restoreRequest();
174
}
175
```
176

177
### Error Handling Types
178

179
```java { .api }
180
// Marker interfaces for error identification
181
public interface AuthenticationError {
182
    // Marker interface - specific protocols implement subclasses
183
}
184

185
public interface LogoutError {
186
    // Marker interface - specific protocols implement subclasses  
187
}
188
```