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

Class ApiKeyGuard

java.lang.Object
org.apache.juneau.rest.server.guard.RestGuard
org.apache.juneau.rest.server.auth.ApiKeyGuard
public class ApiKeyGuard extends RestGuard
AuthN RestGuard that authenticates requests via a raw API-key string.

On every request, the guard:

  1. Extracts the key from the configured source — header (default X-API-Key), query parameter, or cookie.
  2. Delegates lookup to the configured ApiKeyStore.
  3. On success, stashes the returned Principal on the request attributes under "juneau.principal".
  4. On any failure path (missing key, unknown key), throws AuthenticationException with a WWW-Authenticate: ApiKey realm="<realm>" response header.
Usage

// Default source: X-API-Key header. ApiKeyGuard.create().store(store).build(); // Custom header. ApiKeyGuard.create().store(store).fromHeader("X-Acme-Token").build(); // Query-param source (handy for browser clients that can't set custom headers). ApiKeyGuard.create().store(store).fromQuery("apiKey").build(); // Cookie source. ApiKeyGuard.create().store(store).fromCookie("api_key").build();

Security notes
  • API keys are credentials; never log them, always pair with TLS.
  • Query-string keys leak into proxy / access logs and browser history — prefer header or cookie sources for production traffic. Query-string is offered for legacy / debugging use only.
  • ApiKeyStore implementations should compare keys in constant time (MessageDigest.isEqual(byte[], byte[])).
See Also:
Since:
10.0.0

  • Constructor Details

    • ApiKeyGuard

      protected ApiKeyGuard(ApiKeyGuard.Builder builder)
      Constructor.
      Parameters:
      builder - The builder to read configuration from. Must not be null.

    • ApiKeyGuard

      public ApiKeyGuard(ApiKeyStore store)
      Convenience constructor: header source with default name "X-API-Key" and default realm.
      Parameters:
      store - The API-key store. Must not be null.

  • Method Details

    • create

      public static ApiKeyGuard.Builder create()
      Static creator.
      Returns:
      A new builder.

    • guard

      public boolean guard(RestRequest req, RestResponse res)
      Description copied from class: RestGuard
      Checks the current HTTP request and throws a BasicHttpException if the guard does not permit the request.

      By default, throws an SC_FORBIDDEN exception if RestGuard.isRequestAllowed(RestRequest) returns false.

      Subclasses are free to override this method to tailor the behavior of how to handle unauthorized requests.

      Overrides:
      guard in class RestGuard
      Parameters:
      req - The servlet request.
      res - The servlet response.
      Returns:
      true if request can proceed. Specify false if you're doing something like a redirection to a login page.

    • isRequestAllowed

      public boolean isRequestAllowed(RestRequest req)
      Description copied from class: RestGuard
      Returns true if the specified request can pass through this guard.
      Specified by:
      isRequestAllowed in class RestGuard
      Parameters:
      req - The servlet request.
      Returns:
      true if the specified request can pass through this guard.