Securing servlets with declarative security in the web.xml deployment descriptor is an essential practice in Java web applications. It allows you to define security constraints without writing specific code, instead leveraging the standard configuration mechanism in web.xml. Here’s how you can do it step-by-step:

---

1. Define a Security Constraint

The <security-constraint> element is used to define access rules (restrictions) for specific URL patterns or resources.

<security-constraint>
    <display-name>Protected Area</display-name>
    <web-resource-collection>
        <web-resource-name>ProtectedServlet</web-resource-name>
        <url-pattern>/protected/*</url-pattern>
        <http-method>GET</http-method>
        <!-- You can specify other methods like POST, PUT, DELETE, etc. -->
    </web-resource-collection>
    <auth-constraint>
        <!-- Specify user roles allowed to access these resources -->
        <role-name>ADMIN</role-name>
    </auth-constraint>
</security-constraint>

• <web-resource-collection>: Defines which resources (e.g., servlet paths or URL patterns) are protected.
  • Include one or more <url-pattern> sub-elements for specific paths.
  • Use <http-method> if you want to secure specific HTTP methods (e.g., GET or POST).
• <auth-constraint>: Specifies the roles allowed access to the protected URL patterns. Define roles in the <role-name> tag.

---

2. Configure the Authentication Mechanism

The <login-config> element specifies the type of authentication and the location of the login pages (if required).

<login-config>
    <auth-method>BASIC</auth-method> <!-- Can be BASIC, DIGEST, FORM, CLIENT-CERT -->
    <realm-name>MySecureRealm</realm-name>
</login-config>

• Auth Methods:
  • BASIC: Uses the browser’s built-in login dialog.
  • FORM: Uses custom login and error pages defined in web.xml.
  • DIGEST: Similar to BASIC, but passwords are hashed.
  • CLIENT-CERT: Authenticates users via client certificates (SSL/TLS).

Example for FORM Authentication:

<login-config>
    <auth-method>FORM</auth-method>
    <form-login-config>
        <form-login-page>/login.html</form-login-page>
        <form-error-page>/error.html</form-error-page>
    </form-login-config>
</login-config>

---

3. Define Security Roles

Use the <security-role> element to list all the roles used in your application.

<security-role>
    <role-name>ADMIN</role-name>
</security-role>
<security-role>
    <role-name>USER</role-name>
</security-role>

These roles correlate with the roles you define in the <auth-constraint> section.

---

4. Example web.xml Configuration

A complete example with all the above steps:

<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee" version="5.0">
    <security-constraint>
        <display-name>Secure Admin Pages</display-name>
        <web-resource-collection>
            <web-resource-name>Admin Resources</web-resource-name>
            <url-pattern>/admin/*</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <role-name>ADMIN</role-name>
        </auth-constraint>
       <user-data-constraint>
            <transport-guarantee>CONFIDENTIAL</transport-guarantee>
        </user-data-constraint>
    </security-constraint>

    <login-config>
        <auth-method>FORM</auth-method>
        <form-login-config>
            <form-login-page>/login.html</form-login-page>
            <form-error-page>/error.html</form-error-page>
        </form-login-config>
    </login-config>

    <security-role>
        <role-name>ADMIN</role-name>
    </security-role>
    <security-role>
        <role-name>USER</role-name>
    </security-role>
</web-app>

5. Configuring Realm

a. Tomcat: tomcat-users.xml

In Tomcat, the tomcat-users.xml file (located in the conf folder) is the default User Realm. You can define users and their roles directly in this file.

Example tomcat-users.xml:

<tomcat-users xmlns="http://tomcat.apache.org/xml"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://tomcat.apache.org/xml tomcat-users.xsd"
              version="1.0">
    <role rolename="ADMIN"/>
    <role rolename="USER"/>

    <user username="admin" password="admin1234" roles="ADMIN" />
    <user username="user1" password="password" roles="USER,ADMIN" />
    <user username="guest" password="guest" roles="USER" />
</tomcat-users>

• username: The username the user enters in the form.
• password: The password used for authentication.
• roles: The roles granted to this user. These roles must match the ones defined in web.xml (<security-role>).

When a user submits the form with j_security_check, the server matches their credentials against this file and determines whether they have the necessary role(s) to access the resource.

login.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Login</title>
</head>
<body>
<form class="login-form" method="post" action="j_security_check">
    <h2>Login</h2>
    <div class="error">
        <!-- Uncomment this for demonstration -->
        <!-- Invalid username or password -->
    </div>
    <label for="username">Username</label>
    <input type="text" id="username" name="j_username" placeholder="Enter your username" required>
    <label for="password">Password</label>
    <input type="password" id="password" name="j_password" placeholder="Enter your password" required>
    <button type="submit">Login</button>
</form>
</body>
</html>

error.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Access Denied</title>
</head>
<body>
<div class="error-container">
    <h1>Access Denied</h1>
    <p>Sorry, you are not authorized to access this page.</p>
    <a href="login.html">Return to Login</a>
</div>
</body>
</html>

---

Key Elements Explained:

1. <security-constraint>:
   • Protects resources (e.g., /admin/* or /protected/*).
   • Specifies roles allowed to access resources.
2. <auth-constraint>:
   • Specifies authorized roles for the secured resource.
3. <login-config>:
   • Defines the authentication mechanism (BASIC, FORM, DIGEST, CLIENT-CERT).
4. <user-data-constraint>:
   • Specifies transport security (e.g., CONFIDENTIAL ensures HTTPS is used).

---

Notes:

• The actual user-role mapping is provided by the application server (through deployment descriptors, database configuration, or an external realm). How roles map to users is server-specific.
• For FORM authentication, form-login-page is a path to your custom login page relative to the application’s context root.

This declarative approach is efficient for servlet security and follows the Jakarta EE standards.