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

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Keycloak Adapter SPI

Name: tessl/maven-org-keycloak--keycloak-adapter-spi
Author: tessl

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  
}

Workspace: tessl
Visibility: Public
Created: 6 months ago
Last updated: 2 months ago
Describes: pkg:maven/org.keycloak/keycloak-adapter-spi@26.2.x
Publish Source: CLI
Badge