or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration-management.mdcryptographic-operations.mdidentity-management.mdindex.mdjose-implementation.mdsecurity-context.mdtoken-management.mdtoken-representations.mdutility-functions.md
tile.json

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

Core Keycloak library providing fundamental authentication and authorization functionality

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

To install, run

npx @tessl/cli install tessl/maven-org-keycloak--keycloak-core@26.2.0

index.mddocs/

Keycloak Core

Keycloak Core is the fundamental library for authentication and authorization in the Keycloak identity and access management ecosystem. It provides comprehensive JWT token handling, cryptographic operations, OAuth2/OpenID Connect protocol support, and extensive data representation classes for identity management operations.

Package Information

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

Core Imports

import org.keycloak.Config;
import org.keycloak.TokenVerifier;
import org.keycloak.KeycloakSecurityContext;
import org.keycloak.AuthorizationContext;
import org.keycloak.representations.AccessToken;
import org.keycloak.representations.IDToken;
import org.keycloak.representations.JsonWebToken;
import org.keycloak.crypto.KeyWrapper;
import org.keycloak.crypto.Algorithm;
import org.keycloak.jose.jwk.JSONWebKeySet;
import org.keycloak.util.TokenUtil;

Basic Usage

import org.keycloak.TokenVerifier;
import org.keycloak.representations.AccessToken;
import org.keycloak.crypto.KeyWrapper;
import org.keycloak.exceptions.TokenVerificationException;

// Basic token verification
try {
    AccessToken token = TokenVerifier.create(tokenString, AccessToken.class)
        .withDefaultChecks()
        .publicKey(publicKey)
        .verify()
        .getToken();
    
    String subject = token.getSubject();
    String issuer = token.getIssuer();
    boolean isActive = token.isActive();
    
    // Access roles and permissions
    AccessToken.Access realmAccess = token.getRealmAccess();
    if (realmAccess != null && realmAccess.isUserInRole("admin")) {
        // Handle admin access
    }
} catch (TokenVerificationException e) {
    // Handle verification failure
}

// Configuration management
Config.Scope authScope = Config.scope("authentication");
String defaultProvider = authScope.get("defaultProvider", "password");

Architecture

Keycloak Core is built around several key architectural components:

  • Token System: Comprehensive JWT implementation with specialized token types for different OAuth2/OIDC flows
  • Cryptographic Layer: Pluggable signature and encryption providers supporting RSA, ECDSA, EdDSA, and HMAC algorithms
  • JOSE Implementation: Complete JSON Object Signing and Encryption support including JWS, JWE, and JWK specifications
  • Representation Layer: Extensive data transfer objects for identity management, authorization policies, and configuration
  • Configuration System: Hierarchical configuration management with scoped property access
  • Verification Framework: Flexible token validation system with pluggable verification predicates

Capabilities

Token Management

Core JWT token creation, validation, and processing with support for access tokens, ID tokens, refresh tokens, and specialized Keycloak token types.

public class TokenVerifier<T extends JsonWebToken> {
    public static <T extends JsonWebToken> TokenVerifier<T> create(String tokenString, Class<T> clazz);
    public TokenVerifier<T> withDefaultChecks();
    public TokenVerifier<T> publicKey(PublicKey publicKey);
    public TokenVerifier<T> secretKey(SecretKey secretKey);
    public TokenVerifier<T> audience(String... audience);
    public T verify() throws TokenVerificationException;
}

Token Management

Cryptographic Operations

Comprehensive cryptographic support for signing, verification, key management, and algorithm abstraction with support for modern cryptographic standards.

public interface SignatureSignerContext {
    byte[] sign(byte[] data) throws SignatureException;
    String getAlgorithm();
    String getKid();
}

public interface SignatureVerifierContext {
    boolean verify(byte[] data, byte[] signature) throws SignatureException;
    String getAlgorithm();
    String getKid();
}

public class KeyWrapper {
    public String getKid();
    public String getAlgorithm();
    public KeyType getType();
    public KeyUse getUse();
    public KeyStatus getStatus();
    public PublicKey getPublicKey();
    public SecretKey getSecretKey();
}

Cryptographic Operations

JOSE Implementation

Complete JSON Object Signing and Encryption implementation including JWS (JSON Web Signature), JWE (JSON Web Encryption), and JWK (JSON Web Key) support.

public class JWSInput {
    public JWSHeader getHeader();
    public byte[] getContent();
    public <T> T readJsonContent(Class<T> type) throws IOException;
    public String getEncodedSignatureInput();
    public byte[] getSignature();
}

public class JSONWebKeySet {
    public List<JWK> getKeys();
    public JWK getKeyByKid(String kid);
}

JOSE Implementation

Token Representations

Comprehensive token representation classes for OAuth2/OpenID Connect tokens with Keycloak extensions for roles, permissions, and authorization.

public class AccessToken extends JsonWebToken {
    public String getScope();
    public String getSessionState();
    public Access getRealmAccess();
    public Map<String, Access> getResourceAccess();
    public Authorization getAuthorization();
    
    public static class Access {
        public Set<String> getRoles();
        public boolean isUserInRole(String role);
    }
}

public class IDToken extends JsonWebToken {
    public String getName();
    public String getGivenName();
    public String getFamilyName();
    public String getPreferredUsername();
    public String getEmail();
    public Boolean getEmailVerified();
    public AddressClaimSet getAddress();
}

Token Representations

Identity Management Representations

Extensive data transfer objects for user management, realm configuration, client settings, roles, groups, and authorization policies.

public class UserRepresentation extends AbstractUserRepresentation {
    public String getId();
    public String getUsername();
    public String getEmail();
    public String getFirstName();
    public String getLastName();
    public Boolean isEnabled();
    public Boolean isEmailVerified();
    public List<String> getGroups();
    public List<String> getRealmRoles();
    public Map<String, Object> getAttributes();
}

public class RealmRepresentation {
    public String getId();
    public String getRealm();
    public String getDisplayName();
    public Boolean isEnabled();
    public List<UserRepresentation> getUsers();
    public List<ClientRepresentation> getClients();
    public List<RoleRepresentation> getRoles();
}

Identity Management

Configuration Management

Hierarchical configuration system with scoped property access, type-safe configuration retrieval, and extensible provider architecture.

public class Config {
    public static void init();
    public static Scope scope(String... scope);
    public static String getProvider(String spi);
    public static String getAdminRealm();
    
    public interface Scope {
        String get(String key);
        String get(String key, String defaultValue);
        String[] getArray(String key);
        Integer getInt(String key);
        Integer getInt(String key, Integer defaultValue);
        Long getLong(String key);
        Long getLong(String key, Long defaultValue);
        Boolean getBoolean(String key);
        Boolean getBoolean(String key, Boolean defaultValue);
    }
}

Configuration Management

Security Context

Runtime security context management providing access to authentication state, token information, and authorization decisions.

public class KeycloakSecurityContext {
    public AccessToken getToken();
    public String getTokenString();
    public IDToken getIdToken();
    public String getIdTokenString();
    public RefreshToken getRefreshToken();
    public AuthorizationContext getAuthorizationContext();
    public String getRealm();
}

public class AuthorizationContext {
    public boolean hasPermission(String resource, String scope);
    public boolean hasResourcePermission(String resource);
    public boolean hasScopePermission(String scope);
    public Collection<Permission> getPermissions();
    public boolean isGranted();
}

Security Context

Utility Functions

Essential utility functions for token processing, JSON serialization, basic authentication, and common operations.

public class TokenUtil {
    public static void attachOIDCScope(MultivaluedMap<String, String> queryParams, 
                                     MultivaluedMap<String, String> formParams);
    public static boolean isOIDCRequest(String scope);
    public static boolean isOfflineTokenRequested(String scope);
    public static boolean hasScope(String scopes, String targetScope);
    public static RefreshToken getRefreshToken(String refreshToken);
    public static boolean isOfflineToken(RefreshToken refreshToken);
    
    // JWE encoding/decoding methods
    public static String jweDirectEncode(Object input, String encryptionAlg, 
                                       String contentEncAlg, SecretKey encryptionKey);
    public static <T> T jweDirectVerifyAndDecode(String jweStr, SecretKey encryptionKey);
}

public class JsonSerialization {
    public static String writeValueAsString(Object obj) throws IOException;
    public static byte[] writeValueAsBytes(Object obj) throws IOException;
    public static <T> T readValue(String json, Class<T> type) throws IOException;
    public static <T> T readValue(byte[] json, Class<T> type) throws IOException;
}

Utility Functions

Types

Core Enums

public enum TokenCategory {
    INTERNAL, ACCESS, ID, ADMIN, USERINFO, LOGOUT, AUTHORIZATION_RESPONSE
}

public enum KeyType {
    EC, RSA, OCT, OKP
}

public enum KeyUse {
    SIG, ENC
}

public enum KeyStatus {
    ACTIVE, PASSIVE, DISABLED
}

Exception Types

public class TokenVerificationException extends Exception {
    public TokenVerificationException(String message);
    public TokenVerificationException(String message, Throwable cause);
}

public class TokenNotActiveException extends TokenVerificationException {
    public TokenNotActiveException(JsonWebToken token, String message);
}

public class TokenSignatureInvalidException extends TokenVerificationException {
    public TokenSignatureInvalidException(JsonWebToken token, String message);
}

public class SignatureException extends Exception {
    public SignatureException(String message, Throwable cause);
}

Principal and Context Types

public class KeycloakPrincipal<T extends KeycloakSecurityContext> implements Principal {
    public String getName();
    public T getKeycloakSecurityContext();
}

public abstract class AbstractOAuthClient {
    // OAuth client base implementation
}