0
# Keycloak Server SPI
1

2
Keycloak Server SPI (Service Provider Interface) is the core extensibility framework for the Keycloak identity and access management server. It provides comprehensive interfaces and contracts that enable developers to create custom providers for authentication, user storage, credential management, session handling, and other extensibility points.
3

4
## Package Information
5

6
- **Package Name**: org.keycloak:keycloak-server-spi
7
- **Package Type**: Maven JAR Library
8
- **Language**: Java
9
- **Version**: 26.2.5
10
- **Installation**: Add Maven dependency:
11

12
```xml
13
<dependency>
14
    <groupId>org.keycloak</groupId>
15
    <artifactId>keycloak-server-spi</artifactId>
16
    <version>26.2.5</version>
17
    <scope>provided</scope>
18
</dependency>
19
```
20

21
## Core Imports
22

23
```java
24
import org.keycloak.provider.Provider;
25
import org.keycloak.provider.ProviderFactory;
26
import org.keycloak.provider.Spi;
27
import org.keycloak.models.KeycloakSession;
28
import org.keycloak.models.RealmModel;
29
import org.keycloak.models.UserModel;
30
import org.keycloak.models.ClientModel;
31
import org.keycloak.component.ComponentModel;
32
```
33

34
## Basic Usage
35

36
```java
37
// Implementing a custom provider
38
public class MyCustomProvider implements UserStorageProvider {
39
    private KeycloakSession session;
40
    private ComponentModel model;
41

42
    public MyCustomProvider(KeycloakSession session, ComponentModel model) {
43
        this.session = session;
44
        this.model = model;
45
    }
46

47
    @Override
48
    public UserModel getUserById(RealmModel realm, String id) {
49
        // Custom user lookup implementation
50
        return null;
51
    }
52

53
    @Override
54
    public void close() {
55
        // Cleanup resources
56
    }
57
}
58

59
// Creating a provider factory
60
public class MyCustomProviderFactory implements UserStorageProviderFactory<MyCustomProvider> {
61
    public static final String PROVIDER_ID = "my-custom-provider";
62

63
    @Override
64
    public MyCustomProvider create(KeycloakSession session, ComponentModel model) {
65
        return new MyCustomProvider(session, model);
66
    }
67

68
    @Override
69
    public String getId() {
70
        return PROVIDER_ID;
71
    }
72
}
73
```
74

75
## Architecture
76

77
The Keycloak Server SPI is built around several key architectural patterns:
78

79
- **Provider Pattern**: Core abstraction using Provider/ProviderFactory/SPI interfaces for all extensibility points
80
- **Session Management**: KeycloakSession serves as the central context for all operations
81
- **Model Layer**: Rich set of model interfaces (UserModel, RealmModel, ClientModel) representing Keycloak entities
82
- **Component Framework**: Configuration-driven component system for provider instantiation and management
83
- **Storage Abstraction**: Pluggable storage providers for users, roles, clients, and other entities
84
- **Transaction Management**: Built-in transaction support for data consistency
85

86
## Capabilities
87

88
### Core Provider Framework
89

90
Foundation interfaces for creating extensible Keycloak providers. Essential for all custom integrations.
91

92
```java { .api }
93
public interface Provider {
94
    void close();
95
}
96

97
public interface ProviderFactory<T extends Provider> {
98
    T create(KeycloakSession session);
99
    void init(Config.Scope config);
100
    void postInit(KeycloakSessionFactory factory);
101
    void close();
102
    String getId();
103
}
104

105
public interface Spi {
106
    boolean isInternal();
107
    String getName();
108
    Class<? extends Provider> getProviderClass();
109
    Class<? extends ProviderFactory> getProviderFactoryClass();
110
}
111
```
112

113
[Provider Framework](./provider-framework.md)
114

115
### Session and Context Management
116

117
Central session interfaces providing access to all Keycloak services and transaction management.
118

119
```java { .api }
120
public interface KeycloakSession extends AutoCloseable {
121
    KeycloakContext getContext();
122
    KeycloakTransactionManager getTransactionManager();
123
    <T extends Provider> T getProvider(Class<T> clazz);
124
    RealmProvider realms();
125
    UserProvider users();
126
    ClientProvider clients();
127
}
128

129
public interface KeycloakContext {
130
    URI getAuthServerUrl();
131
    String getContextPath();
132
    UriInfo getUri();
133
    HttpHeaders getRequestHeaders();
134
    RealmModel getRealm();
135
    ClientModel getClient();
136
}
137
```
138

139
[Session Management](./session-management.md)
140

141
### Core Model Interfaces
142

143
Primary model interfaces representing Keycloak entities like realms, users, clients, and roles.
144

145
```java { .api }
146
public interface RealmModel extends RoleContainerModel {
147
    String getId();
148
    String getName();
149
    String getDisplayName();
150
    void setDisplayName(String displayName);
151
    boolean isEnabled();
152
    void setEnabled(boolean enabled);
153
    SslRequired getSslRequired();
154
    void setSslRequired(SslRequired sslRequired);
155
}
156

157
public interface UserModel extends RoleMapperModel {
158
    String getId();
159
    String getUsername();
160
    void setUsername(String username);
161
    String getFirstName();
162
    void setFirstName(String firstName);
163
    String getLastName();
164
    void setLastName(String lastName);
165
    String getEmail();
166
    void setEmail(String email);
167
}
168

169
public interface ClientModel extends ProtocolMapperContainerModel, ScopeContainerModel, RoleContainerModel {
170
    String getId();
171
    String getClientId();
172
    void setClientId(String clientId);
173
    String getName();
174
    void setName(String name);
175
    boolean isEnabled();
176
    void setEnabled(boolean enabled);
177
}
178
```
179

180
[Core Models](./core-models.md)
181

182
### User Storage Federation
183

184
Interfaces for integrating external user stores and implementing custom user storage providers.
185

186
```java { .api }
187
public interface UserStorageProvider extends Provider {
188
    // Base interface for user storage providers
189
}
190

191
public interface UserLookupProvider {
192
    UserModel getUserById(RealmModel realm, String id);
193
    UserModel getUserByUsername(RealmModel realm, String username);
194
    UserModel getUserByEmail(RealmModel realm, String email);
195
}
196

197
public interface UserQueryProvider extends UserQueryMethodsProvider, UserCountMethodsProvider {
198
    Stream<UserModel> searchForUserStream(RealmModel realm, String search);
199
    Stream<UserModel> searchForUserStream(RealmModel realm, String search, Integer firstResult, Integer maxResults);
200
    Stream<UserModel> getGroupMembersStream(RealmModel realm, GroupModel group);
201
}
202
```
203

204
[User Storage](./user-storage.md)
205

206
### Credential Management
207

208
Framework for handling various credential types including passwords, OTP, and WebAuthn.
209

210
```java { .api }
211
public interface CredentialProvider extends Provider {
212
    String getType();
213
    CredentialModel createCredential(RealmModel realm, UserModel user, CredentialModel credential);
214
    boolean deleteCredential(RealmModel realm, UserModel user, String credentialId);
215
    CredentialModel getCredentialFromModel(CredentialModel model);
216
}
217

218
public interface CredentialInputValidator {
219
    boolean supportsCredentialType(String credentialType);
220
    boolean isConfiguredFor(RealmModel realm, UserModel user, String credentialType);
221
    boolean isValid(RealmModel realm, UserModel user, CredentialInput input);
222
}
223

224
public interface CredentialInputUpdater {
225
    boolean supportsCredentialType(String credentialType);
226
    boolean updateCredential(RealmModel realm, UserModel user, CredentialInput input);
227
    void disableCredentialType(RealmModel realm, UserModel user, String credentialType);
228
}
229
```
230

231
[Credential Management](./credential-management.md)
232

233
### Authentication and Session Management
234

235
Interfaces for managing authentication flows, user sessions, and client sessions.
236

237
```java { .api }
238
public interface AuthenticationSessionModel extends CommonClientSessionModel {
239
    String getTabId();
240
    RootAuthenticationSessionModel getParentSession();
241
    Map<String, ExecutionStatus> getExecutionStatus();
242
    void setExecutionStatus(String authenticator, ExecutionStatus status);
243
    void clearExecutionStatus();
244
    UserModel getAuthenticatedUser();
245
    void setAuthenticatedUser(UserModel user);
246
}
247

248
public interface UserSessionModel {
249
    String getId();
250
    RealmModel getRealm();
251
    UserModel getUser();
252
    String getLoginUsername();
253
    String getIpAddress();
254
    String getAuthMethod();
255
    int getStarted();
256
    int getLastSessionRefresh();
257
    void setLastSessionRefresh(int seconds);
258
}
259
```
260

261
[Authentication Sessions](./authentication-sessions.md)
262

263
### Component Framework
264

265
Configuration-driven component system for managing provider instances and their configurations.
266

267
```java { .api }
268
public interface ComponentFactory<T extends Provider> extends ProviderFactory<T> {
269
    T create(KeycloakSession session, ComponentModel model);
270
    void validateConfiguration(KeycloakSession session, RealmModel realm, ComponentModel model) throws ComponentValidationException;
271
    void onCreate(KeycloakSession session, RealmModel realm, ComponentModel model);
272
    void onUpdate(KeycloakSession session, RealmModel realm, ComponentModel oldModel, ComponentModel newModel);
273
}
274

275
public class ComponentModel {
276
    private String id;
277
    private String name;
278
    private String providerId;
279
    private String providerType;
280
    private String parentId;
281
    private String subType;
282
    private MultivaluedHashMap<String, String> config;
283
}
284
```
285

286
[Component Framework](./component-framework.md)
287

288
### Theme and Localization
289

290
Framework for customizing Keycloak UI themes and handling internationalization.
291

292
```java { .api }
293
public interface Theme {
294
    String getName();
295
    String getParentName();
296
    String getImportName();
297
    Type getType();
298
    URL getTemplate(String name) throws IOException;
299
    InputStream getResourceAsStream(String path) throws IOException;
300
    Properties getMessages() throws IOException;
301
    Properties getProperties() throws IOException;
302
}
303

304
public interface ThemeSelectorProvider extends Provider {
305
    String getThemeName(Theme.Type type);
306
}
307

308
public interface LocaleSelectorProvider extends Provider {
309
    Locale resolveLocale(RealmModel realm, UserModel user);
310
}
311
```
312

313
### Validation Framework
314

315
Extensible validation system for form fields and user input validation.
316

317
```java { .api }
318
public interface Validator {
319
    String getId();
320
    ValidationResult validate(Object input, String inputHint, ValidationContext context, ValidatorConfig config) throws ValidationException;
321
}
322

323
public interface ValidationContext extends AttributeContext {
324
    KeycloakSession getSession();
325
    Attributes getAttributes();
326
    RealmModel getRealm();
327
    UserModel getUser();
328
}
329

330
public class ValidationResult {
331
    public static final ValidationResult VALID = new ValidationResult();
332
    private final boolean valid;
333
    private final Set<ValidationError> errors;
334
}
335
```
336

337
[Validation Framework](./validation-framework.md)
338

339
### Vault Integration
340

341
Secure secrets management through vault provider integration.
342

343
```java { .api }
344
public interface VaultProvider extends Provider {
345
    VaultRawSecret obtainSecret(String vaultSecretId);
346
}
347

348
public interface VaultStringSecret extends VaultCharSecret {
349
    Optional<String> get();
350
    default String getOrDefault(String defaultValue) {
351
        return get().orElse(defaultValue);
352
    }
353
}
354

355
public interface VaultTranscriber {
356
    String transcribe(String value);
357
}
358
```
359

360
[Vault Integration](./vault-integration.md)
361

362
## Common Types
363

364
```java { .api }
365
// Core model enumerations
366
public enum SslRequired {
367
    ALL, EXTERNAL, NONE
368
}
369

370
// Authentication execution status
371
public enum ExecutionStatus {
372
    SUCCESS, FAILED, SETUP_REQUIRED, ATTEMPTED, SKIPPED, CHALLENGED, FLOW_RESET
373
}
374

375
// Provider event base interface
376
public interface ProviderEvent {
377
    // Marker interface for provider events
378
}
379

380
// Component validation exception
381
public class ComponentValidationException extends Exception {
382
    public ComponentValidationException(String message);
383
    public ComponentValidationException(String message, Object... parameters);
384
}
385

386
// Model exceptions
387
public class ModelException extends RuntimeException {
388
    public ModelException(String message);
389
    public ModelException(String message, Throwable cause);
390
}
391

392
public class ModelDuplicateException extends ModelException {
393
    public ModelDuplicateException(String message);
394
    public String getDuplicateFieldName();
395
    public Object getDuplicateFieldValue();
396
}
397
```