Configure the Delivery Tier to Use Basic Authentication

Overview

This page explains how to configure the delivery tier to use HTTP Basic authentication instead of the default form-based authentication.

When to Use

Use HTTP Basic authentication when you need to secure delivery tier endpoints and want to rely on browser-based authentication dialogs or external tools that support Basic authentication.

Prerequisites

Access to the delivery tier project source code.
Familiarity with editing context.xml and web.xml files.
Appropriate permissions to restart the application server.

Implementation Steps

1. Replace the FormAuthenticator Valve

By default, the delivery tier uses the FormAuthenticator valve. To enable Basic authentication, update your application context configuration to use the BasicAuthenticator valve.

Edit site/webapp/src/main/webapp/META-INF/context.xml:

<Valve className="org.apache.catalina.authenticator.BasicAuthenticator" />

2. Update Security Constraints in web.xml

Replace the default security-constraint and login-config elements in your web.xml with the following configuration. This example protects the /preview path and requires the everybody role.

Edit site/webapp/src/main/webapp/WEB-INF/web.xml:

  <security-constraint>
    <web-resource-collection>
      <web-resource-name>Preview</web-resource-name>
      <url-pattern>/preview/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
      <role-name>everybody</role-name>
    </auth-constraint>
  </security-constraint>

  <login-config>
    <auth-method>BASIC</auth-method>
    <realm-name>HSTSITE</realm-name>
  </login-config>

The security-constraint element defines which URL patterns require authentication.
The auth-method is set to BASIC to enable HTTP Basic authentication.
The example uses the everybody role for demonstration purposes. Configure roles according to your security requirements.

Important:
Define all URL paths that require protection. Refer to SRV.12.8 in the Servlet Specification for details on configuring security constraints.

3. Restart the Application

After updating the configuration, restart your application server to apply the changes.

Verification

Access the /preview endpoint (for example, http://localhost:8080/site/preview).
Your browser should display a login dialog.
Enter a valid CMS username and password.
If authentication succeeds, you gain access to the protected resource.

To check authentication status in your custom delivery tier components, use the following method:

Principal principal = request.getUserPrincipal();
if (principal != null) {
    // The user is authenticated
}

If you provide an incorrect username or password, the server returns an HTTP 401 error.