tessl/maven-org-keycloak--keycloak-common
Common library and dependencies shared with server and all adapters for the Keycloak identity and access management system
—
Pending
enums-types.mddocs/
Enums and Types
This document covers the enumerations and type definitions in the org.keycloak.common.enums package that provide configuration options and policy definitions for various Keycloak components.
SSL Requirements
The SslRequired enum defines SSL requirement levels for different connection types.
public enum SslRequired {
/**
* SSL required for all connections
*/
ALL,
/**
* SSL required for external connections only (internal/localhost connections exempt)
*/
EXTERNAL,
/**
* SSL not required for any connections
*/
NONE;
/**
* Checks if SSL is required for the given client connection
*/
public boolean isRequired(ClientConnection connection);
/**
* Checks if SSL is required for the given host
*/
public boolean isRequired(String host);
}Usage Examples
// Configure SSL requirement
SslRequired sslPolicy = SslRequired.EXTERNAL;
// Check if SSL required for a connection
ClientConnection connection = getClientConnection();
if (sslPolicy.isRequired(connection)) {
// Enforce SSL for this connection
redirectToHttps(request);
}
// Check if SSL required for a host
String requestHost = request.getServerName();
if (sslPolicy.isRequired(requestHost)) {
// SSL required for this host
}
// Different SSL policies
switch (sslPolicy) {
case ALL:
// All connections must use SSL
break;
case EXTERNAL:
// Only external connections require SSL
break;
case NONE:
// SSL not required
break;
}Hostname Verification Policies
The HostnameVerificationPolicy enum defines hostname verification behavior for SSL connections.
public enum HostnameVerificationPolicy {
/**
* No hostname verification performed
*/
ANY,
/**
* @deprecated Allows wildcards in subdomain names
*/
@Deprecated
WILDCARD,
/**
* @deprecated CN must match hostname exactly
*/
@Deprecated
STRICT,
/**
* Similar to STRICT with better public suffix matching
*/
DEFAULT
}Usage Examples
// Configure hostname verification
HostnameVerificationPolicy policy = HostnameVerificationPolicy.DEFAULT;
// Apply hostname verification policy
switch (policy) {
case ANY:
// Skip hostname verification (not recommended for production)
sslContext.setHostnameVerifier((hostname, session) -> true);
break;
case DEFAULT:
// Use default hostname verification with proper public suffix handling
sslContext.setHostnameVerifier(getDefaultHostnameVerifier());
break;
case WILDCARD:
// Legacy wildcard support (deprecated)
logger.warn("WILDCARD hostname verification is deprecated");
break;
case STRICT:
// Legacy strict verification (deprecated)
logger.warn("STRICT hostname verification is deprecated, use DEFAULT");
break;
}Relative URL Usage
The RelativeUrlsUsed enum defines policies for relative URL usage in Keycloak configurations.
public enum RelativeUrlsUsed {
/**
* Always use relative URI and resolve based on browser request
*/
ALWAYS,
/**
* Relative URI not used, configuration contains absolute URI
*/
NEVER
}Usage Examples
// Configure relative URL policy
RelativeUrlsUsed urlPolicy = RelativeUrlsUsed.ALWAYS;
// Generate URLs based on policy
String baseUrl;
switch (urlPolicy) {
case ALWAYS:
// Use relative URLs, resolve from request
baseUrl = buildRelativeUrl(request);
break;
case NEVER:
// Use absolute URLs from configuration
baseUrl = getConfiguredBaseUrl();
break;
}
// Build endpoint URLs
String loginUrl = baseUrl + "/auth/realms/master/protocol/openid-connect/auth";
String tokenUrl = baseUrl + "/auth/realms/master/protocol/openid-connect/token";Account REST API Versions
The AccountRestApiVersion enum defines supported versions of the Account REST API.
public enum AccountRestApiVersion {
/**
* Version 1 Alpha 1 of the Account REST API
*/
V1_ALPHA1("v1alpha1");
/**
* Default API version
*/
public static final AccountRestApiVersion DEFAULT = V1_ALPHA1;
/**
* Gets enum value by string version
*/
public static AccountRestApiVersion get(String strVersion);
/**
* Gets the string representation of the version
*/
public String getStrVersion();
}Usage Examples
// Get default API version
AccountRestApiVersion defaultVersion = AccountRestApiVersion.DEFAULT;
String versionString = defaultVersion.getStrVersion(); // "v1alpha1"
// Parse version from string
String requestedVersion = request.getHeader("API-Version");
AccountRestApiVersion version = AccountRestApiVersion.get(requestedVersion);
if (version == null) {
// Unsupported version, use default
version = AccountRestApiVersion.DEFAULT;
}
// Build API endpoint with version
String apiPath = "/auth/realms/" + realmName + "/account/" + version.getStrVersion();
// Version-specific handling
switch (version) {
case V1_ALPHA1:
// Handle V1 Alpha 1 API features
processV1Alpha1Request(request, response);
break;
default:
// Handle with default version
processDefaultRequest(request, response);
break;
}Type Utilities and Patterns
SSL Policy Configuration Pattern
public class SslConfiguration {
private final SslRequired sslRequired;
private final HostnameVerificationPolicy hostnamePolicy;
public SslConfiguration(SslRequired sslRequired, HostnameVerificationPolicy hostnamePolicy) {
this.sslRequired = sslRequired;
this.hostnamePolicy = hostnamePolicy;
}
public boolean requiresSSL(ClientConnection connection) {
return sslRequired.isRequired(connection);
}
public boolean requiresSSL(String host) {
return sslRequired.isRequired(host);
}
public HostnameVerifier createHostnameVerifier() {
switch (hostnamePolicy) {
case ANY:
return (hostname, session) -> true;
case DEFAULT:
return createDefaultVerifier();
default:
logger.warn("Using deprecated hostname verification policy: {}", hostnamePolicy);
return createLegacyVerifier(hostnamePolicy);
}
}
}URL Policy Utilities
public class UrlBuilder {
private final RelativeUrlsUsed urlPolicy;
private final String configuredBaseUrl;
public UrlBuilder(RelativeUrlsUsed urlPolicy, String configuredBaseUrl) {
this.urlPolicy = urlPolicy;
this.configuredBaseUrl = configuredBaseUrl;
}
public String buildBaseUrl(HttpServletRequest request) {
switch (urlPolicy) {
case ALWAYS:
return buildFromRequest(request);
case NEVER:
return configuredBaseUrl;
default:
throw new IllegalStateException("Unknown URL policy: " + urlPolicy);
}
}
private String buildFromRequest(HttpServletRequest request) {
String scheme = request.getScheme();
String host = request.getServerName();
int port = request.getServerPort();
StringBuilder url = new StringBuilder();
url.append(scheme).append("://").append(host);
if (!isDefaultPort(scheme, port)) {
url.append(":").append(port);
}
return url.toString();
}
private boolean isDefaultPort(String scheme, int port) {
return ("http".equals(scheme) && port == 80) ||
("https".equals(scheme) && port == 443);
}
}API Version Management
public class ApiVersionManager {
public static boolean isSupported(String versionString) {
return AccountRestApiVersion.get(versionString) != null;
}
public static AccountRestApiVersion parseVersion(HttpServletRequest request) {
// Try header first
String versionHeader = request.getHeader("API-Version");
if (versionHeader != null) {
AccountRestApiVersion version = AccountRestApiVersion.get(versionHeader);
if (version != null) {
return version;
}
}
// Try path parameter
String versionParam = request.getParameter("version");
if (versionParam != null) {
AccountRestApiVersion version = AccountRestApiVersion.get(versionParam);
if (version != null) {
return version;
}
}
// Return default
return AccountRestApiVersion.DEFAULT;
}
public static void setVersionHeader(HttpServletResponse response, AccountRestApiVersion version) {
response.setHeader("API-Version", version.getStrVersion());
}
}Security Policy Validator
public class SecurityPolicyValidator {
public static void validateSslPolicy(SslRequired sslPolicy, HttpServletRequest request)
throws SecurityException {
if (sslPolicy == SslRequired.NONE) {
return; // No SSL required
}
if (!request.isSecure()) {
String host = request.getServerName();
if (sslPolicy == SslRequired.ALL) {
throw new SecurityException("SSL required for all connections");
}
if (sslPolicy == SslRequired.EXTERNAL && !isLocalhost(host)) {
throw new SecurityException("SSL required for external connections");
}
}
}
private static boolean isLocalhost(String host) {
return "localhost".equals(host) ||
"127.0.0.1".equals(host) ||
"::1".equals(host);
}
public static void validateHostnamePolicy(HostnameVerificationPolicy policy) {
if (policy == HostnameVerificationPolicy.WILDCARD ||
policy == HostnameVerificationPolicy.STRICT) {
logger.warn("Hostname verification policy {} is deprecated, " +
"consider using DEFAULT", policy);
}
}
}Integration Examples
Complete Security Configuration
public class SecurityConfig {
private final SslRequired sslRequired;
private final HostnameVerificationPolicy hostnamePolicy;
private final RelativeUrlsUsed urlPolicy;
public SecurityConfig(Properties config) {
this.sslRequired = SslRequired.valueOf(
config.getProperty("ssl.required", "EXTERNAL")
);
this.hostnamePolicy = HostnameVerificationPolicy.valueOf(
config.getProperty("hostname.verification", "DEFAULT")
);
this.urlPolicy = RelativeUrlsUsed.valueOf(
config.getProperty("relative.urls", "ALWAYS")
);
}
public void validateRequest(HttpServletRequest request) throws SecurityException {
SecurityPolicyValidator.validateSslPolicy(sslRequired, request);
SecurityPolicyValidator.validateHostnamePolicy(hostnamePolicy);
}
public String buildUrl(HttpServletRequest request, String path) {
UrlBuilder builder = new UrlBuilder(urlPolicy, getConfiguredBaseUrl());
String baseUrl = builder.buildBaseUrl(request);
return baseUrl + path;
}
}Install with Tessl CLI
npx tessl i tessl/maven-org-keycloak--keycloak-common