Core functionality for Keycloak OIDC/OAuth2 client adapters enabling Java applications to integrate with Keycloak identity and access management services
npx @tessl/cli install tessl/maven-org-keycloak--keycloak-adapter-core@25.0.0Keycloak 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.
<dependency>
<groupId>org.keycloak</groupId>
<artifactId>keycloak-adapter-core</artifactId>
<version>25.0.3</version>
</dependency>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;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);
}Keycloak Adapter Core is built around several key components:
KeycloakDeployment and KeycloakDeploymentBuilder for configuration managementAdapterDeploymentContext for single/multi-tenant deployment resolutionRefreshableKeycloakSecurityContext for token lifecycle and refreshAdapterTokenStore interface for token persistence strategiesHttpClientBuilder for secure HTTP communication with Keycloak serverEssential 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);
}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);
}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);
}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;
}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;
}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();
}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);
}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;
}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";
}