java - DropWizard Auth Realms

Question

In DropWizard, I can set up basic auth like so (in the Application#run impl):

BasicAuthProvider<SimplePrincipal> authProvider = new BasicAuthProvider(authenticator, "SECRET_REALM");
environment.jersey().register(authProvider);

I am wondering what the significance of the String realm ("SECRET_REALM") is?

From general security concepts, I understand a "realm" to be a place (database, directory, file, keystore, etc.) where users and roles/permissions are stored.

What does a realm mean in DropWizard, and what's the significance of specifying it inside BasicAuthProvider? Does it create something with this realm under the hood?

Answer 1

A realm is in a sense, some protected area/space in the server. The realm should have a name. If we run the example from this post, using cURL(which I recommend downloading, as it's useful in development), without any user credentials, we will see the following.

C:>curl -i  http://localhost:8080/simple
HTTP/1.1 401 Unauthorized
Date: Thu, 11 Dec 2014 18:55:02 GMT
WWW-Authenticate: Basic realm="Basic Example Realm"
Content-Type: text/plain
Transfer-Encoding: chunked

Credentials are required to access this resource.

This is how the Basic Auth Protocol works. When the server want the user agent to authenticate, to access a secured resource, it will send back a "401 Unauthorized", along with the header similar to

WWW-Authenticate: Basic realm="Basic Example Realm"

The name you provide to the BasicAuthProvider is the realm that will be provided in the header. You can see in the source code

if (required) {
    final String challenge = String.format(CHALLENGE_FORMAT, realm);
    throw new WebApplicationException(
                                    Response.status(Response.Status.UNAUTHORIZED)
                    .header(HttpHeaders.WWW_AUTHENTICATE, challenge)
                    .entity("Credentials are required to access this resource.")
                    .type(MediaType.TEXT_PLAIN_TYPE)
                    .build());

Now try to access the resource from the browser. You will see

You can also see the realm name there. The RFC 2617 just states (about the realm):

realm:
A string to be displayed to users so they know which username and password to use. This string should contain at least the name of the host performing the authentication and might additionally indicate the collection of users who might have access. An example might be "[email protected]".