Class AuthenticationHandler

java.lang.Object
com.loomcache.server.security.AuthenticationHandler
public class AuthenticationHandler extends Object
Server-side authorization handler.

Architecture

Authentication can be handled externally by a Spring Cloud Gateway (or similar). LoomCache then performs authorization based on trusted headers:
  • X-Auth-User — the authenticated username
  • X-Auth-Roles — comma-separated roles (e.g., "ROLE_READ,ROLE_WRITE")
JAAS can also authenticate direct client username/password credentials from the wire AUTH message before role-based authorization is applied.

When a client connects via the gateway, the AUTH message carries:

  • Key = username (from X-Auth-User header)
  • Value = roles string (from X-Auth-Roles header)

LoomCache resolves roles to permission sets via AuthConfig and caches the resolved permissions per connection for the lifetime of the session.

Node-to-Node Communication

Inter-node connections are secured by mTLS and automatically trusted — no AUTH handshake is required for cluster-internal traffic.

Thread-safe: uses ConcurrentHashMap for session state.

  • Constructor Details

    • AuthenticationHandler

      public AuthenticationHandler(@Nullable AuthConfig config)
      Create an AuthenticationHandler with the given configuration.
      Parameters:
      config - the authentication configuration (if null, auth is disabled)

    • AuthenticationHandler

      public AuthenticationHandler(@Nullable AuthConfig config, Set<String> trustedGatewayAddresses, long sessionTimeoutMs)
      Create an AuthenticationHandler with gateway trust verification and session timeout.
      Parameters:
      config - the authentication configuration (if null, auth is disabled)
      trustedGatewayAddresses - set of trusted gateway IP addresses/hostnames (may be empty)
      sessionTimeoutMs - session timeout in milliseconds

    • AuthenticationHandler

      public AuthenticationHandler(@Nullable AuthConfig config, Set<String> trustedGatewayAddresses, long sessionTimeoutMs, @Nullable CertPermissionMapper certMapper)
      Create an AuthenticationHandler with gateway trust, session timeout, and optional cert mapper.
      Parameters:
      config - the authentication configuration (if null, auth is disabled)
      trustedGatewayAddresses - set of trusted gateway IP addresses/hostnames (may be empty)
      sessionTimeoutMs - session timeout in milliseconds
      certMapper - optional certificate-to-permission mapper (may be null)

  • Method Details

    • handleAuth

      public Message handleAuth(Message authMsg, ConnectionContext ctx)
      Handle an AUTH message from a gateway-authenticated client.

      Key = username (from gateway's X-Auth-User header). Value = roles string (from gateway's X-Auth-Roles header).

      Resolves roles to permissions using the configured role definitions and caches the result for the connection's lifetime.

      Audit logging: All authorization decisions are logged for compliance.

      Parameters:
      authMsg - the authentication message (must not be null)
      ctx - the connection context (must not be null)
      Returns:
      AUTH_RESPONSE message with result

    • isAuthenticated

      public boolean isAuthenticated(String connectionId)
      Check if a connection has been authorized. Returns true if auth is disabled or if the connection has a valid session.

    • isAuthorized

      public boolean isAuthorized(String connectionId, String command)
      Check if a connection is authorized for a specific command. Logs all authorization decisions for audit trail.
      Parameters:
      connectionId - the connection identifier
      command - the command name (e.g., "MAP_PUT", "QUEUE_PUSH")
      Returns:
      true if authorized

    • isAuthorized

      public boolean isAuthorized(String connectionId, AuthConfig.PermissionRequest request)
      Check if a connection is authorized for a scoped operation. Logs all authorization decisions for audit trail.
      Parameters:
      connectionId - the connection identifier
      request - request authorization metadata
      Returns:
      true if authorized

    • getUsername

      public String getUsername(String connectionId)
      Get the username for a connection. Returns "anonymous" if unknown.

    • getRole

      public Role getRole(String connectionId)
      Get the role for a connection. Returns READ_ONLY if unknown.

    • getSession

      public @Nullable AuthenticationHandler.AuthSession getSession(String connectionId)
      Get the session for a connection (contains username, permissions, and role). Used for comprehensive audit logging.

    • removeSession

      public void removeSession(String connectionId)
      Remove session state when a connection closes.

    • isEnabled

      public boolean isEnabled()
      Check if auth is enabled.

    • trustClusterPeer

      public void trustClusterPeer(String connectionId, String peerId)
      Mark a connection as a trusted cluster peer (mTLS authenticated). Cluster peers get full permissions — no role check needed.

    • resolveFromCertificate

      public @Nullable CertPermissionMapper.PermissionLevel resolveFromCertificate(ConnectionContext ctx)
      Resolve permission level from a connection's TLS client certificate. Returns null if no certificate is available or cert mapper is not configured.
      Parameters:
      ctx - the connection context (must not be null)
      Returns:
      the resolved permission level, or null if cert-based auth is not applicable

    • shutdown

      public void shutdown()
      Shutdown the session cleanup scheduler. Should be called when the handler is being destroyed.