Authentication with HttpUrlConnection

1. Overview

In this tutorial, we’re going to explore how to authenticate HTTP requests using the HttpUrlConnection class.

2. HTTP Authentication

In web applications, servers may require clients to authenticate themselves. Failing to comply usually results in the server returning an HTTP 401 (Unauthorized) status code.

There are multiple authentication schemes that differ in the security strength they provide. However, the implementation effort varies as well.

Let’s see three of them:

• basic is a scheme which we’ll say more about in the next section
• digest applies hash algorithms on user credentials and a server-specified nonce
• bearer utilizes access tokens as part of OAuth 2.0

3. Basic Authentication

Basic authentication allows clients to authenticate themselves using an encoded user name and password via the Authorization header:

GET / HTTP/1.1
Authorization: Basic dXNlcjpwYXNzd29yZA==

To create the encoded user name and password string, we simply Base64-encode the username, followed by a colon, followed by the password:

basic(user, pass) = base64-encode(user + ":" + pass)

Remember some caution from RFC 7617, though:

This scheme is not considered to be a secure method of user authentication unless used in conjunction with some external secure system such as TLS

This is, of course, since the user name and password travel as plain text over the network within each request.

4. Authenticate a Connection

Okay, with that as background, let’s jump into configuring HttpUrlConnection to use HTTP Basic.

The class HttpUrlConnection can send requests, but first, we have to obtain an instance of it from an URL object:

HttpURLConnection connection = (HttpURLConnection) url.openConnection();

A connection offers many methods to configure it, like setRequestMethod and setRequestProperty.

As odd as setRequestProperty sounds, this is the one we want.

Once we’ve joined the user name and password using “:”, we can use the java.util.Base64 class to encode the credentials:

String auth = user + ":" + password;
byte[] encodedAuth = Base64.encodeBase64(auth.getBytes(StandardCharsets.UTF_8));

Then, we create the header value from the literal “Basic ” followed by the encoded credentials:

String authHeaderValue = "Basic " + new String(encodedAuth);

Next, we call the method setRequestProperty(key, value) to authenticate the request. As mentioned previously, we have to use “Authorization” as our header and “Basic ” + encoded credentials as our value:

connection.setRequestProperty("Authorization", authHeaderValue);

Finally, we need to actually send the HTTP request, like for example by calling getResponseCode(). As a result, we get an HTTP response code from the server:

int responseCode = connection.getResponseCode();

Anything in the 2xx family means that our request including the authentication part was okay!

5. Java Authenticator

The above-mentioned basic auth implementation requires setting the authorization header for every request. In contrast, the abstract class java.net.Authenticator allows setting the authentication globally for all connections.

We need to extend the class first. Then, we call the static method Authenticator.setDefault() in order to register an instance of our authenticator:

Authenticator.setDefault(new BasicAuthenticator());

Our basic auth class just overrides the getPasswordAuthentication() non-abstract method of the base class:

private final class BasicAuthenticator extends Authenticator {
protected PasswordAuthentication getPasswordAuthentication() {
return new PasswordAuthentication(user, password.toCharArray());
}
}

The Authenticator class utilizes the credentials of our authenticator to fulfill the authentication scheme required by the server automatically.

6. Conclusion

In this short tutorial, we’ve seen how to apply basic authentication to requests sent via HttpUrlConnection.