Package org.apache.juneau.rest.server.auth

Interface ApiKeyStore

Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface ApiKeyStore
SPI for resolving a raw API key string to its associated Principal.

ApiKeyGuard extracts the key from a configurable source (header / query / cookie) and delegates lookup to an ApiKeyStore the host supplies. The store is the authoritative source of "is this key valid and which client owns it?" — it can hit a database, an in-memory map, an external KMS, etc.

Implementations should:

  • Treat the key as untrusted input (no logging of full keys, no exception messages echoing the key).
  • Compare keys with a constant-time comparison if the store is in-memory — this matters for short keys where a timing side-channel could leak bytes. MessageDigest.isEqual(...) over the UTF-8 byte arrays is the standard idiom.
  • Return Optional.empty() for any unknown / revoked / expired key; do not throw for ordinary "not found" misses (that would couple lookup failures to exception-construction overhead under load).
Example — in-memory store:

final Map<String,Principal> keys = Map.of( "key-alice", () -> "alice", "key-bob", () -> "bob" ); ApiKeyStore store = key -> Optional.ofNullable(keys.get(key));

See Also:
Since:
10.0.0

  • Method Summary

    Modifier and Type
    Method
    Description
    Optional<Principal>
    lookup(String key)
    Looks up the Principal associated with the supplied API key.

  • Method Details

    • lookup

      Optional<Principal> lookup(String key)
      Looks up the Principal associated with the supplied API key.
      Parameters:
      key - The raw API key from the configured source (header / query / cookie). Never null.
      Returns:
      The associated principal, or Optional.empty() if the key is unknown / revoked / expired.