Package org.bluezoo.gumdrop.http

Class HTTPAuthenticationProvider

java.lang.Object
org.bluezoo.gumdrop.http.HTTPAuthenticationProvider
Direct Known Subclasses:
DefaultHTTPAuthenticationProvider, ServletAuthenticationProvider
public abstract class HTTPAuthenticationProvider extends Object
Abstract base class for HTTP authentication providers.

Implements the HTTP Authentication framework per RFC 9110 section 11. RFC 9110 section 11.6.1: a 401 response MUST include a WWW-Authenticate header with at least one applicable challenge. The generateChallenge() method produces this header value.

This class provides the common authentication logic for various HTTP authentication schemes including:

  • Basic - RFC 7617 username/password authentication
  • Digest - RFC 7616 challenge-response authentication
  • Bearer - RFC 6750 token-based authentication
  • OAuth - RFC 6749 access token authentication
  • JWT - JSON Web Token authentication

Concrete implementations must provide the authentication method, realm name, and credential verification logic by implementing the abstract methods.

Usage Example


 public class MyAuthProvider extends HTTPAuthenticationProvider {
     private final Realm realm;
     
     protected String getAuthMethod() {
         return HttpServletRequest.BASIC_AUTH;
     }
     
     protected String getRealmName() {
         return "MyApp";
     }
     
     protected boolean passwordMatch(String realm, String username, String password) {
         return this.realm.passwordMatch(username, password);
     }
     
     // ... other abstract method implementations
 }

Thread Safety

This class is thread-safe. Nonce management uses concurrent data structures.

Author:
Chris Burdess
See Also:

  • Constructor Details

    • HTTPAuthenticationProvider

      public HTTPAuthenticationProvider()

  • Method Details

    • getAuthMethod

      protected abstract String getAuthMethod()
      Gets the authentication method configured for this provider.

      The return value should be one of the standard authentication method constants from HttpServletRequest or HTTPAuthenticationMethods.

      Returns:
      the authentication method (e.g., "BASIC", "DIGEST"), or null if none configured

    • getRealmName

      protected abstract String getRealmName()
      Gets the realm name for this provider.

      The realm name is included in authentication challenges and is used to partition authentication spaces.

      Returns:
      the realm name, or null if none configured

    • passwordMatch

      protected abstract boolean passwordMatch(String realm, String username, String password)
      Verifies username and password credentials against the authentication realm.

      This method is called for Basic authentication and may also be used by other authentication mechanisms that require password verification.

      Parameters:
      realm - the realm name for credential lookup
      username - the username to verify
      password - the password to verify
      Returns:
      true if the credentials are valid, false otherwise

    • getDigestHA1

      protected abstract String getDigestHA1(String realm, String username)
      Gets the precomputed H(A1) hash for Digest authentication.

      For Digest authentication, H(A1) = MD5(username:realm:password). Implementations may store this precomputed hash for security, avoiding the need to store plaintext passwords.

      Parameters:
      realm - the realm name
      username - the username
      Returns:
      the H(A1) hash as a lowercase hexadecimal string, or null if the user doesn't exist

    • validateBearerToken

      protected abstract Realm.TokenValidationResult validateBearerToken(String token)
      Validates a Bearer token for token-based authentication.

      Called for Bearer authentication (RFC 6750). Implementations should verify the token's signature, expiration, and associated claims.

      Parameters:
      token - the bearer token to validate
      Returns:
      a Realm.TokenValidationResult with validation outcome, or null if Bearer authentication is not supported

    • validateOAuthToken

      protected abstract Realm.TokenValidationResult validateOAuthToken(String accessToken)
      Validates an OAuth 2.0 access token.

      Called for OAuth authentication (RFC 6749). Implementations should verify the token against the authorization server or introspection endpoint.

      Parameters:
      accessToken - the OAuth access token to validate
      Returns:
      a Realm.TokenValidationResult with validation outcome, or null if OAuth authentication is not supported

    • supportsDigestAuth

      protected boolean supportsDigestAuth()
      Checks if the underlying Realm supports HTTP Digest authentication.

      HTTP Digest authentication requires the Realm to provide the H(A1) hash via getDigestHA1(String, String). Some Realm implementations (e.g., LDAP with hashed passwords) cannot support this.

      The default implementation returns true, assuming Digest is supported. Subclasses should override this if they can determine whether the Realm actually supports Digest authentication.

      Returns:
      true if Digest authentication is supported, false otherwise

    • authenticate

      public final HTTPAuthenticationProvider.AuthenticationResult authenticate(String authorizationHeader)
      Authenticates a request using the Authorization header value.

      This method parses the Authorization header, determines the authentication scheme, and delegates to the appropriate authentication method based on the configured getAuthMethod().

      Parameters:
      authorizationHeader - the Authorization header value from the HTTP request, in the format "Scheme credentials" (e.g., "Basic dXNlcjpwYXNz")
      Returns:
      an HTTPAuthenticationProvider.AuthenticationResult indicating success or failure with details

    • generateChallenge

      public final String generateChallenge()
      Generates a WWW-Authenticate challenge header value for 401 responses.

      This method generates the appropriate challenge based on the configured authentication method. For Digest authentication, it includes a fresh nonce.

      Returns:
      the WWW-Authenticate header value (e.g., "Basic realm=\"MyApp\""), or null if no authentication is configured

    • supportsScheme

      public final boolean supportsScheme(String scheme)
      Checks if this provider supports the given authentication scheme.

      Scheme matching is case-insensitive per RFC 7235.

      Parameters:
      scheme - the authentication scheme to check (e.g., "Basic", "Digest", "Bearer")
      Returns:
      true if the scheme is supported by this provider, false otherwise

    • getSupportedSchemes

      public final Set<String> getSupportedSchemes()
      Gets the set of authentication schemes supported by this provider.
      Returns:
      an unmodifiable set of supported scheme names (e.g., {"Basic"} or {"Bearer"})

    • isAuthenticationRequired

      public boolean isAuthenticationRequired()
      Checks if authentication is required for requests to this provider.

      The default implementation returns true. Subclasses may override to implement optional authentication.

      Returns:
      true if authentication is required, false if authentication is optional