Class AuthConfig

java.lang.Object
com.loomcache.common.config.AuthConfig
public final class AuthConfig extends Object
Authorization configuration for LoomCache.

Architecture

  Client → API Gateway (JWT validation) → LoomCache (role-based authorization)

LoomCache supports two authentication entry points. A Spring Cloud Gateway (or similar) can validate JWT tokens and forward trusted headers to LoomCache:

  • X-Auth-User — the authenticated username (from JWT subject)
  • X-Auth-Roles — comma-separated roles (from JWT claims)
Operators can also enable JAAS, LDAP, Kerberos, or opaque-token auth so the wire AUTH message carries credentials that are validated by configured backends. JAAS/LDAP/Kerberos principals and token credentials are mapped to LoomCache roles.

LoomCache resolves roles to permission sets defined in loomcache.yml and authorizes each operation against the resolved permissions.

Node-to-Node Authentication

Inter-node communication is secured by mTLS only — no tokens needed. Certificate trust = identity. All nodes share a CA-signed certificate.

Example Configuration (loomcache.yml)

loomcache:
  auth:
    enabled: true
    gateway-trust: false
    header:
      user: X-Auth-User
      roles: X-Auth-Roles
    role-prefix: "ROLE_"
    jaas:
      enabled: true
      login-context: LoomCache
      role-principal-classes: [com.example.security.RolePrincipal]
      login-modules:
        - class: com.example.security.LoomLoginModule
          flag: required
          options:
            users-file: /etc/loomcache/users.properties
    ldap:
      enabled: true
      user-provider: ldap://ldap.example.com/ou=people,dc=example,dc=com
      auth-identity: uid={USERNAME},ou=people,dc=example,dc=com
      authz-identity: "{departmentNumber}"
      use-ssl: true
    kerberos:
      enabled: true
      login-module-class: com.sun.security.auth.module.Krb5LoginModule
      principal: loomcache/[email protected]
      use-key-tab: true
      key-tab: /etc/security/keytabs/loomcache.keytab
      store-key: true
      do-not-prompt: true
    token:
      enabled: true
      credentials:
        ci-bot:
          sha256: 2bb80d537b1da3e38bd30361aa855686bde0ba5fbda3e13d3a0c742b7725e18f
          username: ci-bot
          roles: [admin]
    roles:
      read-only:
        permissions: [MAP_GET, SET_CONTAINS, QUEUE_PEEK]
        endpoints: [10.0.0.0/8, 2001:db8::/32]
      data-writer:
        permissions: [MAP_GET, MAP_PUT, MAP_DELETE, QUEUE_PUSH, QUEUE_POP]
      admin:
        permissions: ["*"]
      support:
        permissions: [MAP_GET, HEALTH_CHECK, METRICS_READ, CLUSTER_INFO]

  • Method Details

    • enabled

      public boolean enabled()

    • gatewayTrust

      public boolean gatewayTrust()

    • userHeader

      public String userHeader()

    • rolesHeader

      public String rolesHeader()

    • rolePrefix

      public String rolePrefix()

    • roleSeparator

      public String roleSeparator()

    • trustedGatewayAddresses

      public Set<String> trustedGatewayAddresses()

    • roles

      public Map<String, AuthConfig.Role> roles()

    • certPermissions

      public Map<String,String> certPermissions()
      Certificate CN pattern to permission level string mappings. Keys are CN patterns (exact or wildcard like "cluster-*"), values are permission level strings: "READ_ONLY", "READ_WRITE", or "ADMIN".
      Returns:
      immutable map of CN pattern to permission level string

    • jaasConfig

      public AuthConfig.JaasConfig jaasConfig()

    • ldapConfig

      public AuthConfig.LdapConfig ldapConfig()

    • kerberosConfig

      public AuthConfig.KerberosConfig kerberosConfig()

    • tokenConfig

      public AuthConfig.TokenConfig tokenConfig()

    • resolvePermissions

      public Set<String> resolvePermissions(Set<String> roleNames)
      Resolve the combined permissions for a set of role names. Strips the role prefix if configured (e.g., "ROLE_READ" → "read"). Unknown roles are logged at WARN level and yield no permissions.
      Parameters:
      roleNames - the role names from the gateway header (must not be null)
      Returns:
      merged permission set from all matched roles

    • resolvePermissionConfigs

      public Set<AuthConfig.PermissionConfig> resolvePermissionConfigs(Set<String> roleNames)
      Resolve the combined scoped permission configs for a set of role names.
      Parameters:
      roleNames - the role names from the gateway/auth backend (must not be null)
      Returns:
      merged scoped permission configs from all matched roles

    • normalizeRoleNames

      public Set<String> normalizeRoleNames(Set<String> roleNames)
      Normalize a set of gateway role names using the configured role-prefix rules.
      Parameters:
      roleNames - the raw role names from the gateway header
      Returns:
      normalized role names suitable for policy matching

    • resolveRoleNamesForEndpoint

      public Set<String> resolveRoleNamesForEndpoint(Set<String> roleNames, @Nullable String remoteAddress)
      Normalize roles and keep only those whose endpoint policy allows the remote address. Roles without endpoint rules remain available from any source.
      Parameters:
      roleNames - raw or normalized role names (must not be null)
      remoteAddress - client source address, if known
      Returns:
      normalized role names that exist and match the endpoint policy

    • resolvePermissions

      public Set<String> resolvePermissions(Set<String> roleNames, @Nullable String remoteAddress)
      Resolve permissions after applying per-role endpoint restrictions.
      Parameters:
      roleNames - raw or normalized role names (must not be null)
      remoteAddress - client source address, if known
      Returns:
      merged permission set for roles allowed from the endpoint

    • resolvePermissionConfigs

      public Set<AuthConfig.PermissionConfig> resolvePermissionConfigs(Set<String> roleNames, @Nullable String remoteAddress)
      Resolve scoped permission configs after applying per-role endpoint restrictions.
      Parameters:
      roleNames - raw or normalized role names (must not be null)
      remoteAddress - client source address, if known
      Returns:
      merged scoped permission configs for roles allowed from the endpoint

    • isRoleEndpointAllowed

      public boolean isRoleEndpointAllowed(String roleName, @Nullable String remoteAddress)
      Check whether a configured role is available from a remote endpoint. Unknown roles are treated as unbounded so certificate permission-level mappings keep their existing behavior unless an operator explicitly defines matching roles.
      Parameters:
      roleName - role name to check (must not be null)
      remoteAddress - client source address, if known
      Returns:
      true if the role has no endpoint policy, is unknown, or matches the source

    • isAuthorized

      public boolean isAuthorized(Set<String> permissions, String command)
      Check if a set of permissions authorizes a specific command.
      Parameters:
      permissions - the resolved permissions (from resolvePermissions, must not be null)
      command - the command to check (e.g., "MAP_PUT", must not be null)
      Returns:
      true if authorized

    • isAuthorized

      public boolean isAuthorized(Set<String> permissions, Set<AuthConfig.PermissionConfig> permissionConfigs, AuthConfig.PermissionRequest request)
      Check command-level and fine-grained scoped permissions for a request.
      Parameters:
      permissions - legacy command permissions (must not be null)
      permissionConfigs - scoped permission configs (must not be null)
      request - request metadata to authorize (must not be null)
      Returns:
      true if authorized by either command permission or scoped permission

    • authorizeRoles

      public boolean authorizeRoles(Set<String> roleNames, String command)
      Convenience: resolve roles and check authorization in one call.
      Parameters:
      roleNames - the role names to authorize (must not be null)
      command - the command to check (must not be null)
      Returns:
      true if authorized

    • authorizeRoles

      public boolean authorizeRoles(Set<String> roleNames, AuthConfig.PermissionRequest request)
      Convenience: resolve roles and check scoped authorization in one call.
      Parameters:
      roleNames - the role names to authorize (must not be null)
      request - the scoped request to check (must not be null)
      Returns:
      true if authorized

    • parseRolesHeader

      public Set<String> parseRolesHeader(@Nullable String headerValue)
      Parse the roles header value into a set of role names.
      Parameters:
      headerValue - the header value to parse (may be null or blank)
      Returns:
      set of parsed role names, or empty set if headerValue is null/blank

    • disabled

      public static AuthConfig disabled()

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • builder

      public static AuthConfig.Builder builder()