java.lang.Object
- com.albroco.barebonesdigest.DigestAuthentication

public final class DigestAuthentication
extends java.lang.Object

Utility class with high-level methods for parsing challenges and generating responses.

Create an instance of this class once a digest challenge is received. Use the instance to respond to the challenge and to authenticate future requests.

Basic usage

Here is a basic example of how to make a request using HttpURLConnection and, in case of a challenge, respond to the challenge:


 // Step 1. Create the connection
 URL url = new URL("http://httpbin.org/digest-auth/auth/user/passwd");
 HttpURLConnection connection = (HttpURLConnection) url.openConnection();

 // Step 2. Make the request and check to see if the response contains an authorization challenge
 if (connection.getResponseCode() == HttpURLConnection.HTTP_UNAUTHORIZED) {
     // Step 3. Create a authentication object from the challenge...
     DigestAuthentication auth = DigestAuthentication.fromResponse(connection);
     // ...with correct credentials
     auth.username("user").password("passwd");

     // Step 4 (Optional). Check if the challenge was a digest challenge of a supported type
     if (!auth.canRespond()) {
         // No digest challenge or a challenge of an unsupported type - do something else or fail
         return;
     }

     // Step 5. Create a new connection, identical to the original one.
     connection = (HttpURLConnection) url.openConnection();
     // ...and set the Authorization header on the request, with the challenge response
     connection.setRequestProperty(DigestChallengeResponse.HTTP_HEADER_AUTHORIZATION,
         auth.getAuthorizationForRequest("GET", connection.getURL().getPath()));
 }

Reuse challenges for future requests

The DigestAuthentication object can be used to authenticate future requests. This removes the need of making the request twice (once for the challenge and once for the actual request):


 HttpURLConnection anotherConnection = (HttpURLConnection) url.openConnection();
 anotherConnection.setRequestProperty(DigestChallengeResponse.HTTP_HEADER_AUTHORIZATION,
     auth.getAuthorizationForRequest("GET", initialConnection.getURL().getPath()));

Supporting other authentication schemes

To support other authentication schemes than Digest, you can use WwwAuthenticateHeader to parse WWW-Authenticate headers into individual challenges. Example:


 if (connection.getResponseCode() == HttpURLConnection.HTTP_UNAUTHORIZED) {
     // Parse the headers and extract challenges, this will return challenges of all types
     List<String> challengeStrings =
         WwwAuthenticateHeader.extractChallenges(connection.getHeaderFields());

     // Check the challenges and act on them...

     // ...or pass them to DigestAuthentication to handle digest challenges:
     DigestAuthentication auth =
         DigestAuthentication.fromChallenges(challengeStrings).username("user").password
         ("passwd");
 }

Overriding which challenge is used for the response

If the HTTP response from the server contains more then one Digest challenge, one will be chosen when generating the challenge response. Use challengeOrdering(Comparator) to define which challenge is preferred.

Supporting `auth-int` quality of protection

The auth-int quality of protection requires a digest of the entity body of the request to be included in the challenge response. To be compatible with servers that require auth-int quality of protection, use getAuthorizationForRequest(String, String, byte[]) instead of getAuthorizationForRequest(String, String).

auth-int is uncommon. It cannot be used with HTTP requests that does not include a body, such as GET. Some server implementations accept auth-int authentication for such requests as well, using a zero-length entity body.

Concurrency

This class is thread safe, read and write operations are synchronized.

Field Summary

Fields
Modifier and Type	Field and Description
`static java.util.Comparator<DigestChallenge>`	`DEFAULT_CHALLENGE_COMPARATOR` Default comparator used when comparing which challenge to use when there is more than one to choose from.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`canRespond()` Returns `true` if a response can be generated to any of the challenges.
`DigestAuthentication`	`challengeOrdering(java.util.Comparator<? super DigestChallenge> orderingComparator)` Sets the challenge ordering, which will determine which challenge that will be used if there are several.
`static DigestAuthentication`	`fromChallenges(java.lang.Iterable<java.lang.String> challenges)` Creates an authentication from a number of challenges.
`static DigestAuthentication`	`fromDigestChallenge(DigestChallenge challenge)` Creates an authentication from a parsed Digest challenge.
`static DigestAuthentication`	`fromDigestChallenges(java.lang.Iterable<? extends DigestChallenge> challenges)` Creates an authentication from a number of parsed Digest challenges.
`static DigestAuthentication`	`fromResponse(java.net.HttpURLConnection connection)` Creates an authentication by reading response headers from an `HttpURLConnection` object.
`static <T extends java.lang.Iterable<java.lang.String>> DigestAuthentication`	`fromResponseHeaders(java.util.Map<java.lang.String,T> headers)` Creates an authentication from a map of HTTP response headers.
`static DigestAuthentication`	`fromWwwAuthenticateHeader(java.lang.String wwwAuthenticateHeader)` Creates an authentication from a single `WWW-Authenticate` header.
`static DigestAuthentication`	`fromWwwAuthenticateHeaders(java.lang.Iterable<java.lang.String> wwwAuthenticateHeaders)` Creates an authentication from a number of `WWW-Authenticate` headers.
`java.lang.String`	`getAuthorizationForRequest(java.lang.String requestMethod, java.lang.String digestUri)` Returns the value of `Authorization` header that can be used in a particular request.
`java.lang.String`	`getAuthorizationForRequest(java.lang.String requestMethod, java.lang.String digestUri, byte[] entityBody)` Returns the value of `Authorization` header that can be used in a particular request.
`DigestChallengeResponse`	`getChallengeResponse()` Picks a challenge among the available challenges and generates a response to it.
`java.lang.String`	`getPassword()` Returns the password to use for authentication.
`java.lang.String`	`getUsername()` Returns the username to use for authentication.
`boolean`	`isEntityBodyDigestRequired()` Returns `true` if the digest of the `entity-body` is required to generate a response to the preferred challenge.
`DigestAuthentication`	`password(java.lang.String password)` Sets the password to use for authentication.
`java.lang.String`	`toString()`
`DigestAuthentication`	`username(java.lang.String username)` Sets the username to use for authentication.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - DEFAULT_CHALLENGE_COMPARATOR
```
public static final java.util.Comparator<DigestChallenge> DEFAULT_CHALLENGE_COMPARATOR
```
    Default comparator used when comparing which challenge to use when there is more than one to choose from.
    Challenges that are not supported are ordered last.
    Challenges that use digest algorithms SHA-256 or SHA-256-sess are always preferred over challenges that use MD5, MD5-sess, or does not specify an algorithm.
    If the rules above are not enough challenges are ordered according to the following, from most preferred to least preferred:
    1. Challenges where the server supports qop types auth and auth-int.
    2. Challenges where the server supports qop type auth but not auth-int.
    3. Challenges where the server supports the unnamed legacy qop type for RFC 2069 compatibility and nothing else. This should rarely happen in practice.
    4. Challenges where the server supports qop type auth-int and nothing else. This is ranked last among the supported challenges because auth-int is limited and cannot authenticate requests without a body, such as HTTP GET.
- Method Detail
  - fromResponse
```
public static DigestAuthentication fromResponse(java.net.HttpURLConnection connection)
                                         throws ChallengeParseException
```
    Creates an authentication by reading response headers from an HttpURLConnection object.
    
    Parameters:
    
    connection - the connection
    
    Returns:
    
    a new DigestAuthentication object
    
    Throws:
    
    ChallengeParseException - if challenges could not be parsed
  - fromResponseHeaders
```
public static <T extends java.lang.Iterable<java.lang.String>> DigestAuthentication fromResponseHeaders(java.util.Map<java.lang.String,T> headers)
                                                                                                 throws ChallengeParseException
```
    Creates an authentication from a map of HTTP response headers.
    A note about the map representing the headers: header names are case insensitive in HTTP, but keys in a Map are case-sensitive. This method uses WwwAuthenticateHeader.extractChallenges(Map) and handles case in the same way.
    
    Parameters:
    
    headers - the headers, as a map where the keys are header names and values are iterables where each element is a header value string
    
    Returns:
    
    a new DigestAuthentication object
    
    Throws:
    
    ChallengeParseException - if challenges could not be parsed
  - fromWwwAuthenticateHeaders
```
public static DigestAuthentication fromWwwAuthenticateHeaders(java.lang.Iterable<java.lang.String> wwwAuthenticateHeaders)
                                                       throws ChallengeParseException
```
    Creates an authentication from a number of WWW-Authenticate headers.
    
    Parameters:
    
    wwwAuthenticateHeaders - the WWW-Authenticate headers
    
    Returns:
    
    a new DigestAuthentication object
    
    Throws:
    
    ChallengeParseException - if challenges could not be parsed
  - fromWwwAuthenticateHeader
```
public static DigestAuthentication fromWwwAuthenticateHeader(java.lang.String wwwAuthenticateHeader)
                                                      throws ChallengeParseException
```
    Creates an authentication from a single WWW-Authenticate header.
    
    Parameters:
    
    wwwAuthenticateHeader - the WWW-Authenticate header
    
    Returns:
    
    a new DigestAuthentication object
    
    Throws:
    
    ChallengeParseException - if challenges could not be parsed
  - fromChallenges
```
public static DigestAuthentication fromChallenges(java.lang.Iterable<java.lang.String> challenges)
                                           throws ChallengeParseException
```
    Creates an authentication from a number of challenges.
    Challenges can be of any type, not just Digest challenges. See RFC 7235, Section 2.1 for a definition of challenges. Some example of valid challenges:
    - Basic realm="simple"
    - Digest realm="testrealm@host.com", qop="auth,auth-int", nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", opaque="5ccc069c403ebaf9f0171e9517f40e41"
    - Newauth realm="apps", type=1, title="Login to \"apps\""
    Parameters:
    
    challenges - the challenges
    
    Returns:
    
    a new DigestAuthentication object
    
    Throws:
    
    ChallengeParseException - if challenges could not be parsed
  - fromDigestChallenges
```
public static DigestAuthentication fromDigestChallenges(java.lang.Iterable<? extends DigestChallenge> challenges)
```
    Creates an authentication from a number of parsed Digest challenges.
    
    Parameters:
    
    challenges - the digest challenges
    
    Returns:
    
    a new DigestAuthentication object
  - fromDigestChallenge
```
public static DigestAuthentication fromDigestChallenge(DigestChallenge challenge)
```
    Creates an authentication from a parsed Digest challenge.
    
    Parameters:
    
    challenge - the digest challenge
    
    Returns:
    
    a new DigestAuthentication object
  - canRespond
```
public boolean canRespond()
```
    Returns true if a response can be generated to any of the challenges.
    If this method returns false, it could mean that:
    1. The list of challenges is empty, or
    2. none of the challenges are supported (see DigestChallengeResponse.isChallengeSupported(DigestChallenge)).
    Returns:
    
    true if a response can be generated to any of the challenges
  - challengeOrdering
```
public DigestAuthentication challengeOrdering(java.util.Comparator<? super DigestChallenge> orderingComparator)
```
    Sets the challenge ordering, which will determine which challenge that will be used if there are several.
    By default, challenges are sorted using DEFAULT_CHALLENGE_COMPARATOR.
    This method must be called before a choice is made as to which challenge to use. Once a choice has been made it cannot be changed. This means that his method cannot be called after methods such as getChallengeResponse() or getAuthorizationForRequest(String, String).
    
    Parameters:
    
    orderingComparator - A comparator object that will be used to sort the challenges. The challenge that will be used is the first supported challenge according to the sort order defined by the comparator.
    
    Returns:
    
    this object
    
    Throws:
    
    java.lang.IllegalStateException - if this method is called after a method that requires a choice to be made regarding which of the available challenges to use: isEntityBodyDigestRequired(), getChallengeResponse(), getAuthorizationForRequest(String, String), getAuthorizationForRequest(String, String, byte[]).
  - isEntityBodyDigestRequired
```
public boolean isEntityBodyDigestRequired()
```
    Returns true if the digest of the entity-body is required to generate a response to the preferred challenge.
    For most challenges, setting the digest of the entity-body is optional. It is only required if the only quality of protection the server accepts is auth-int.
    
    Returns:
    
    true if the digest of the entity-body must be set
  - username
```
public DigestAuthentication username(java.lang.String username)
```
    Sets the username to use for authentication.
    
    Parameters:
    
    username - the username
    
    Returns:
    
    this object
    
    See Also:
    
    getUsername(), Section 3.2.2 of RFC 2617
  - getUsername
```
public java.lang.String getUsername()
```
    Returns the username to use for authentication.
    
    Returns:
    
    the username
    
    See Also:
    
    username(String)
  - password
```
public DigestAuthentication password(java.lang.String password)
```
    Sets the password to use for authentication.
    
    Parameters:
    
    password - the password
    
    Returns:
    
    this object
    
    See Also:
    
    getPassword()
  - getPassword
```
public java.lang.String getPassword()
```
    Returns the password to use for authentication.
    
    Returns:
    
    the password
    
    See Also:
    
    password(String)
  - getChallengeResponse
```
public DigestChallengeResponse getChallengeResponse()
```
    Picks a challenge among the available challenges and generates a response to it.
    The response returned references the internal representation of this instance, modifying it will modify this instance. Example: Calling username on the response will change the value returned by getUsername().
    
    Returns:
    
    a challenge response
    
    Throws:
    
    java.lang.IllegalStateException - if this method is called when canRespond() returns false, that is, none of the available challenges are supported
  - getAuthorizationForRequest
```
public java.lang.String getAuthorizationForRequest(java.lang.String requestMethod,
                                                   java.lang.String digestUri)
```
    Returns the value of Authorization header that can be used in a particular request.
    The first time an Authorization header is generated nonce count will be set to 1. Each subsequent call will increase the nonce count by one. The server expects the nonce count to increase by exactly one for each request, so do not call this method unless you intend to use the result in a request.
    Calling this method has the same effect as calling getAuthorizationForRequest(String, String, byte[]) with a zero-length byte array for entityBody.
    
    Parameters:
    
    requestMethod - the HTTP request method, such as GET or POST.
    
    digestUri - the Request-URI of the Request-Line of the HTTP request, see DigestChallengeResponse.digestUri(String) for a discussion of what to set here
    
    Returns:
    
    an authorization string, to use in an Authorization header
    
    Throws:
    
    java.lang.IllegalStateException - If this method is called when canRespond() returns false, that is, none of the available challenges are supported
    
    InsufficientInformationException - If username or password has not been set
    
    See Also:
    
    DigestChallengeResponse.requestMethod(String), DigestChallengeResponse.digestUri(String), getAuthorizationForRequest(String, String, byte[])
  - getAuthorizationForRequest
```
public java.lang.String getAuthorizationForRequest(java.lang.String requestMethod,
                                                   java.lang.String digestUri,
                                                   byte[] entityBody)
```
    Returns the value of Authorization header that can be used in a particular request.
    This method takes the request's entity-body as an argument. The entity body is the message body after decoding any transfer encoding that might have been applied. Example: If Transfer-Encoding is gzip the entity body is the unzipped message and the message body is the gzipped message. Only some requests have entity bodies, GET requests for example do not. See DigestChallengeResponse.entityBody(byte[]) for more details.
    This method can be used for any request, but the entity-body is only used for "quality of protection" auth-int. Quality of protection auth-int requires a hash of the entity body of the message to be included in the challenge response.
    Not all requests have an entity-body, for example, GET requests do not. Some servers accept an entity-body of zero length for such requests (even though it is strictly speaking not correct to do so).
    The first time an Authorization header is generated nonce count will be set to 1. Each subsequent call will increase the nonce count by one. The server expects the nonce count to increase by exactly one for each request, so do not call this method unless you intend to use the result in a request.
    
    Parameters:
    
    requestMethod - the HTTP request method, such as GET or POST.
    
    digestUri - the Request-URI of the Request-Line of the HTTP request, see DigestChallengeResponse.digestUri(String) for a discussion of what to set here
    
    entityBody - the entity-body of the request (see above)
    
    Returns:
    
    an authorization string, to use in an Authorization header
    
    Throws:
    
    java.lang.IllegalStateException - If this method is called when canRespond() returns false, that is, none of the available challenges are supported
    
    InsufficientInformationException - If username or password has not been set
    
    See Also:
    
    DigestChallengeResponse.requestMethod(String), DigestChallengeResponse.digestUri(String), DigestChallengeResponse.entityBody(byte[]), getAuthorizationForRequest(String, String), isEntityBodyDigestRequired()
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object

Class DigestAuthentication

Basic usage

Reuse challenges for future requests

Supporting other authentication schemes

Overriding which challenge is used for the response

Supporting auth-int quality of protection

Concurrency

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_CHALLENGE_COMPARATOR

Method Detail

fromResponse

fromResponseHeaders

fromWwwAuthenticateHeaders

fromWwwAuthenticateHeader

fromChallenges

fromDigestChallenges

fromDigestChallenge

canRespond

challengeOrdering

isEntityBodyDigestRequired

username

getUsername

password

getPassword

getChallengeResponse

getAuthorizationForRequest

getAuthorizationForRequest

toString

Supporting `auth-int` quality of protection