or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mdcore-adapters.mdhttp-operations.mdindex.mdjaas-integration.mdkey-rotation.mdpolicy-enforcement.mdtoken-storage.mdutility-operations.md
tile.json

tessl/maven-org-keycloak--keycloak-adapter-core

Core functionality for Keycloak OIDC/OAuth2 client adapters enabling Java applications to integrate with Keycloak identity and access management services

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

To install, run

npx @tessl/cli install tessl/maven-org-keycloak--keycloak-adapter-core@25.0.0

index.mddocs/

Keycloak Adapter Core

Keycloak Adapter Core provides the core functionality for Keycloak OIDC/OAuth2 client adapters, enabling Java applications to integrate with Keycloak identity and access management services. It includes essential components for authentication flow handling, token management, security context management, and bearer token validation.

Package Information

  • Package Name: keycloak-adapter-core
  • Package Type: Maven
  • Group ID: org.keycloak
  • Language: Java
  • Installation:
    <dependency>
      <groupId>org.keycloak</groupId>
      <artifactId>keycloak-adapter-core</artifactId>
      <version>25.0.3</version>
    </dependency>

Core Imports

import org.keycloak.adapters.KeycloakDeployment;
import org.keycloak.adapters.KeycloakDeploymentBuilder;
import org.keycloak.adapters.AdapterDeploymentContext;
import org.keycloak.adapters.AdapterTokenStore;
import org.keycloak.adapters.RefreshableKeycloakSecurityContext;

Basic Usage

import org.keycloak.adapters.*;
import java.io.InputStream;

// Build deployment configuration from JSON
InputStream configStream = getClass().getResourceAsStream("/keycloak.json");
KeycloakDeployment deployment = KeycloakDeploymentBuilder.build(configStream);

// Create deployment context for single-tenant
AdapterDeploymentContext deploymentContext = new AdapterDeploymentContext(deployment);

// For multi-tenant scenarios with resolver
KeycloakConfigResolver resolver = facade -> {
    // Custom resolution logic based on request
    return resolveDeploymentForTenant(facade);
};
AdapterDeploymentContext multiTenantContext = new AdapterDeploymentContext(resolver);

// Bearer token authentication
BearerTokenRequestAuthenticator bearerAuth = new BearerTokenRequestAuthenticator(deployment);
AuthOutcome outcome = bearerAuth.authenticate(httpFacade);

if (outcome == AuthOutcome.AUTHENTICATED) {
    AccessToken token = bearerAuth.getToken();
    String principal = AdapterUtils.getPrincipalName(deployment, token);
}

Architecture

Keycloak Adapter Core is built around several key components:

  • Deployment Management: KeycloakDeployment and KeycloakDeploymentBuilder for configuration management
  • Context Management: AdapterDeploymentContext for single/multi-tenant deployment resolution
  • Authentication: Various authenticator classes for different authentication flows
  • Token Management: RefreshableKeycloakSecurityContext for token lifecycle and refresh
  • Storage Abstraction: AdapterTokenStore interface for token persistence strategies
  • HTTP Client: HttpClientBuilder for secure HTTP communication with Keycloak server
  • Key Rotation: Public key locators for token verification with key rotation support

Capabilities

Core Adapter Management

Essential deployment configuration and context management for Keycloak integration. Handles single-tenant and multi-tenant scenarios with comprehensive configuration options.

public class KeycloakDeployment {
    public boolean isConfigured();
    public String getResourceName();
    public String getRealm();
    public String getAuthServerBaseUrl();
    public boolean isBearerOnly();
    public boolean isPublicClient();
    public HttpClient getClient();
}

public class KeycloakDeploymentBuilder {
    public static KeycloakDeployment build(InputStream is);
    public static KeycloakDeployment build(AdapterConfig adapterConfig);
}

public class AdapterDeploymentContext {
    public AdapterDeploymentContext(KeycloakDeployment deployment);
    public AdapterDeploymentContext(KeycloakConfigResolver configResolver);
    public KeycloakDeployment resolveDeployment(HttpFacade facade);
}

Core Adapter Management

Authentication and Security Context

Authentication flow handling with support for bearer tokens, basic authentication, and OAuth flows. Provides security context management with token refresh capabilities.

public abstract class RequestAuthenticator {
    public AuthChallenge getChallenge();
    public AuthOutcome authenticate();
}

public class BearerTokenRequestAuthenticator {
    public BearerTokenRequestAuthenticator(KeycloakDeployment deployment);
    public AuthOutcome authenticate(HttpFacade exchange);
    public AccessToken getToken();
    public String getTokenString();
}

public class RefreshableKeycloakSecurityContext extends KeycloakSecurityContext {
    public AccessToken getToken();
    public String getTokenString();
    public boolean refreshExpiredToken(boolean checkActive);
    public void logout(KeycloakDeployment deployment);
}

Authentication

Token Storage and Management

Token storage abstraction and utilities for managing token lifecycle, including cookie-based storage and token refresh operations.

public interface AdapterTokenStore {
    void checkCurrentToken();
    boolean isCached(RequestAuthenticator authenticator);
    void saveAccountInfo(OidcKeycloakAccount account);
    void logout();
    void refreshCallback(RefreshableKeycloakSecurityContext securityContext);
}

public class CookieTokenStore {
    public static void setTokenCookie(KeycloakDeployment deployment, HttpFacade facade, RefreshableKeycloakSecurityContext session);
    public static KeycloakPrincipal<RefreshableKeycloakSecurityContext> getPrincipalFromCookie(KeycloakDeployment deployment, HttpFacade facade, AdapterTokenStore tokenStore);
    public static void removeCookie(KeycloakDeployment deployment, HttpFacade facade);
}

Token Storage

HTTP Client and Server Operations

HTTP client builder with SSL configuration and server request utilities for token operations, logout, and node registration.

public class HttpClientBuilder {
    public HttpClientBuilder socketTimeout(long timeout, TimeUnit unit);
    public HttpClientBuilder sslContext(SSLContext sslContext);
    public HttpClientBuilder trustStore(KeyStore truststore);
    public HttpClient build();
}

public class ServerRequest {
    public static void invokeLogout(KeycloakDeployment deployment, String refreshToken) throws IOException, HttpFailure;
    public static AccessTokenResponse invokeRefresh(KeycloakDeployment deployment, String refreshToken) throws IOException, HttpFailure;
    public static void invokeRegisterNode(KeycloakDeployment deployment, String host) throws HttpFailure, IOException;
}

HTTP Operations

Key Rotation and Token Verification

Public key location and token verification utilities supporting key rotation for secure token validation.

public interface PublicKeyLocator {
    PublicKey getPublicKey(String kid, KeycloakDeployment deployment);
    void reset(KeycloakDeployment deployment);
}

public class AdapterTokenVerifier {
    public static AccessToken verifyToken(String tokenString, KeycloakDeployment deployment) throws VerificationException;
    public static VerifiedTokens verifyTokens(String accessTokenString, String idTokenString, KeycloakDeployment deployment) throws VerificationException;
}

Key Rotation

JAAS Integration

JAAS (Java Authentication and Authorization Service) integration for enterprise Java applications with login modules and principal management.

public abstract class AbstractKeycloakLoginModule implements LoginModule {
    public void initialize(Subject subject, CallbackHandler callbackHandler, Map<String, ?> sharedState, Map<String, ?> options);
    public boolean login() throws LoginException;
    public boolean commit() throws LoginException;
    public boolean logout() throws LoginException;
}

public class RolePrincipal implements Principal {
    public RolePrincipal(String roleName);
    public String getName();
}

JAAS Integration

Policy Enforcement Point (PEP)

Policy Enforcement Point integration for authorization policy evaluation with Keycloak's authorization services.

public class HttpAuthzRequest implements AuthzRequest {
    public HttpAuthzRequest(OIDCHttpFacade oidcFacade);
    public String getMethod();
    public String getURI();
    public List<String> getHeaders(String name);
    public String getRemoteAddr();
}

public class HttpAuthzResponse implements AuthzResponse {
    public HttpAuthzResponse(OIDCHttpFacade oidcFacade);
    public void sendError(int statusCode);
    public void setHeader(String name, String value);
}

Policy Enforcement

Utility Operations

Utility functions for common adapter operations including principal name resolution, role extraction, HTTP requests, and credential management.

public class AdapterUtils {
    public static String generateId();
    public static Set<String> getRolesFromSecurityContext(RefreshableKeycloakSecurityContext session);
    public static String getPrincipalName(KeycloakDeployment deployment, AccessToken token);
    public static KeycloakPrincipal<RefreshableKeycloakSecurityContext> createPrincipal(KeycloakDeployment deployment, RefreshableKeycloakSecurityContext securityContext);
    public static void setClientCredentials(KeycloakDeployment deployment, Map<String, String> headers, Map<String, String> params);
}

public class HttpAdapterUtils {
    public static <T> T sendJsonHttpRequest(KeycloakDeployment deployment, HttpRequestBase httpRequest, Class<T> clazz) throws HttpClientAdapterException;
}

Utility Operations

Common Types

public enum AuthOutcome {
    AUTHENTICATED, NOT_ATTEMPTED, FAILED
}

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

public class OIDCAuthenticationError {
    public enum Reason {
        NO_BEARER_TOKEN, INVALID_STATE_COOKIE, OAUTH_ERROR, 
        SSL_REQUIRED, CODE_TO_TOKEN_FAILURE, INVALID_TOKEN, 
        STALE_TOKEN, NO_AUTHORIZATION_HEADER
    }
    
    public OIDCAuthenticationError(Reason reason, String description);
    public Reason getReason();
    public String getDescription();
}

public class HttpClientAdapterException extends Exception {
    public HttpClientAdapterException(String message);
    public HttpClientAdapterException(String message, Throwable t);
}

public interface CorsHeaders {
    String ACCESS_CONTROL_ALLOW_ORIGIN = "Access-Control-Allow-Origin";
    String ACCESS_CONTROL_ALLOW_CREDENTIALS = "Access-Control-Allow-Credentials";
    String ACCESS_CONTROL_ALLOW_METHODS = "Access-Control-Allow-Methods";
    String ACCESS_CONTROL_ALLOW_HEADERS = "Access-Control-Allow-Headers";
    String ACCESS_CONTROL_MAX_AGE = "Access-Control-Max-Age";
    String ORIGIN = "Origin";
    String ACCESS_CONTROL_REQUEST_METHOD = "Access-Control-Request-Method";
    String ACCESS_CONTROL_REQUEST_HEADERS = "Access-Control-Request-Headers";
    String ACCESS_CONTROL_EXPOSE_HEADERS = "Access-Control-Expose-Headers";
}