or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mdhttp-facade.mdindex.mdsession-management.md
tile.json

tessl/maven-org-keycloak--keycloak-adapter-spi

Service Provider Interface for Keycloak authentication adapters across different application server environments

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.keycloak/keycloak-adapter-spi@26.2.x

To install, run

npx @tessl/cli install tessl/maven-org-keycloak--keycloak-adapter-spi@26.2.0

index.mddocs/

Keycloak Adapter SPI

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.

Package Information

  • Package Name: keycloak-adapter-spi
  • Package Type: maven
  • Language: Java
  • Installation: 
    <dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-adapter-spi</artifactId>
    <version>26.2.5</version>
</dependency>

Core Imports

import org.keycloak.adapters.spi.*;

For specific interfaces:

import org.keycloak.adapters.spi.HttpFacade;
import org.keycloak.adapters.spi.AuthOutcome;
import org.keycloak.adapters.spi.AuthChallenge;
import org.keycloak.adapters.spi.KeycloakAccount;
import org.keycloak.adapters.spi.SessionIdMapper;
import org.keycloak.adapters.spi.InMemorySessionIdMapper;
import org.keycloak.adapters.spi.SessionIdMapperUpdater;
import org.keycloak.adapters.spi.UserSessionManagement;
import org.keycloak.adapters.spi.AdapterSessionStore;
import org.keycloak.adapters.spi.AuthenticationError;
import org.keycloak.adapters.spi.LogoutError;

Basic Usage

import org.keycloak.adapters.spi.*;
import javax.security.cert.X509Certificate;

// Implement HTTP facade for your platform
public class MyHttpFacade implements HttpFacade {
    @Override
    public Request getRequest() { /* implementation */ }
    
    @Override
    public Response getResponse() { /* implementation */ }
    
    @Override
    public X509Certificate[] getCertificateChain() { /* implementation */ }
}

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

// Handle authentication outcomes
public void handleAuth(AuthOutcome outcome) {
    switch (outcome) {
        case AUTHENTICATED:
            // Process successful authentication
            break;
        case FAILED:
            // Handle authentication failure
            break;
        case NOT_ATTEMPTED:
            // No authentication attempted
            break;
        // ... handle other outcomes
    }
}

Architecture

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

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

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

Capabilities

HTTP Request/Response Abstraction

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.

public interface HttpFacade {
    Request getRequest();
    Response getResponse();
    X509Certificate[] getCertificateChain();
}

HTTP Facade

Session Management

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

public interface SessionIdMapper {
    boolean hasSession(String id);
    void clear();
    Set<String> getUserSessions(String principal);
    String getSessionFromSSO(String sso);
    void map(String sso, String principal, String session);
    void removeSession(String session);
}

public class InMemorySessionIdMapper implements SessionIdMapper {
    // Thread-safe in-memory implementation
}

Session Management

Authentication State Management

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

public enum AuthOutcome {
    NOT_ATTEMPTED, FAILED, AUTHENTICATED, NOT_AUTHENTICATED, LOGGED_OUT
}

public interface KeycloakAccount {
    Principal getPrincipal();
    Set<String> getRoles();
}

public interface AuthChallenge {
    boolean challenge(HttpFacade exchange);
    int getResponseCode();
}

Authentication

Types

Core Session Types

public interface SessionIdMapperUpdater {
    void clear(SessionIdMapper idMapper);
    void map(SessionIdMapper idMapper, String sso, String principal, String httpSessionId);
    void removeSession(SessionIdMapper idMapper, String httpSessionId);
    boolean refreshMapping(SessionIdMapper idMapper, String httpSessionId);
    
    // Predefined update strategies
    SessionIdMapperUpdater DIRECT = /* direct update implementation */;
    SessionIdMapperUpdater EXTERNAL = /* external update implementation */;
}

public interface UserSessionManagement {
    void logoutAll();
    void logoutHttpSessions(List<String> ids);
}

public interface AdapterSessionStore {
    void saveRequest();
    boolean restoreRequest();
}

Error Handling Types

// Marker interfaces for error identification
public interface AuthenticationError {
    // Marker interface - specific protocols implement subclasses
}

public interface LogoutError {
    // Marker interface - specific protocols implement subclasses  
}