Overview#

Security-constraint is an element in the J2EE configuration.[1]

To "protect" a Tomcat Application or other J2EE Protected Resource, then you will need to modify the web.xml or context.xml file for the application. Typically, for Tomcat it is found $CATALINA_HOME/webapps/DirectoryWiki/WEB-INF

<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
        http://java.sun.com/xml/ns/j2ee/web-app_2_5.xsd"
        version="2.5">
    <display-name>A Secured Application</display-name>

    <!-- SERVLET -->
    <servlet>
        <servlet-name>catalog</servlet-name>
        <servlet-class>com.mycorp.CatalogServlet</servlet-class>
        <init-param>
            <param-name>catalog</param-name>
            <param-value>Spring</param-value>
        </init-param>
        <security-role-ref>
            <description>anyone Authenticated is in the Authenticated Role</description>
            <role-name>Authenticated</role-name>
            <!-- role name used in code -->
            <role-link>manager</role-link>
        </security-role-ref>        
        <security-role-ref>
            <description>Any Manager is in the Admin Role</description>
            <role-name>Admin</role-name>
            <!-- role name used in code -->
            <role-link>manager</role-link>
        </security-role-ref>
    </servlet>

   <!-- ... other stuff maybe -->
   
   <!--  START OF ACCESS RESTRICTION -->
   <security-constraint>
       <display-name>Administrative Constraint</display-name>
       <web-resource-collection>
           <web-resource-name>Administrative</web-resource-name>
           <url-pattern>/Delete.jsp</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>
   <security-constraint>
       <display-name>Any Authenticated Constraint</display-name>
       <web-resource-collection>
           <web-resource-name>Authenticated</web-resource-name>
           <url-pattern>/Edit.jsp</url-pattern>
           <url-pattern>/Comment.jsp</url-pattern>
           <url-pattern>/Login.jsp</url-pattern>
           <url-pattern>/NewGroup.jsp</url-pattern>
           <url-pattern>/Rename.jsp</url-pattern>
           <url-pattern>/Upload.jsp</url-pattern>
           <http-method>DELETE</http-method>
           <http-method>GET</http-method>
           <http-method>HEAD</http-method>
           <http-method>POST</http-method>
           <http-method>PUT</http-method>
       </web-resource-collection>
       <web-resource-collection>
           <web-resource-name>Read-only Area</web-resource-name>
           <url-pattern>/attach</url-pattern>
           <http-method>DELETE</http-method>
           <http-method>POST</http-method>
           <http-method>PUT</http-method>
       </web-resource-collection>
       <auth-constraint>
           <role-name>Admin</role-name>
           <role-name>Authenticated</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>/LoginForm.jsp</form-login-page>
           <form-error-page>/LoginForm.jsp</form-error-page>
       </form-login-config>
   </login-config>
   <security-role>
       <description>
           This logical role includes all authenticated users
       </description>
       <role-name>Authenticated</role-name>
   </security-role>
   <security-role>
       <description>
           This logical role includes all administrative users
       </description>
       <role-name>Admin</role-name>
   </security-role>
</web-app>

As shown in the preceding example, the <web-app> element is the root element for web applications. The <web-app> element contains the following elements that are used for specifying security for a web application:

<security-role-ref> element#

The security role reference element contains the declaration of a security role reference in the web application’s code.
  • <declaration> - an optional description of the role
  • <role-name> - the security role name used in the code
  • <role-link> - optional element used to link a security role reference to a defined <role-name>.

The security <role-name> specified here is the security role name used in the code. The value of the <role-name> element must be the String used as the parameter to the HttpServletRequest.isUserInRole(String role) method. The container uses the mapping of security-role-ref to security-role when determining the return value of the call.

The security <role-link> specified here contains the value of the name of the security role that the user may be mapped into. The role-link element is used to link a security role reference to a defined security role. The role-link element must contain the <role-name> of one of the security roles defined in the security-role elements.

<security-role> element#

A security role is an abstract name for the permission to access a particular set of resources in an application. A security role can be compared to a key that can open a lock. Many people might have a copy of the key. The lock doesn’t care who you are, only that you have the right key.

The security-role element is used with the security-role-ref element to map roles defined in code to roles defined for the web application. For more information about security roles, read Working with Security Roles.

<security-constraint> element#

A security constraint is used to define the access privileges to a collection of resources using their URL mapping.

The following elements can be part of a security constraint:

  • <web-resource-collection>
  • <auth-constraint>
  • <user-data-constraint>
Further descriptions are shown below.

<web-resource-collection> element#

Web resource collections describe a URL pattern and HTTP method pair that identify resources that need to be protected.
  • <web-resource-name> - The name you use for this resource. Its use is optional.
  • <url-pattern> - the request URI to be protected. Many applications have both unprotected and protected resources.
    • To provide unrestricted access to a resource, do not configure a security constraint for that particular request URI.
  • <http-method> - specifies that these defined HTTP methods are to be covered by the security constraint
  • <http-method-omission> - omits these defined HTTP methods from the security constraint

A little more explanation for the <url-pattern> element is required. The request URI is the part of a URL after the hostname and port. For example, let’s say that you have an ecommerce site with a catalog that you would want anyone to be able to access and browse, and a shopping cart area for customers only. You could set up the paths for your web application so that the pattern /cart/* is protected but nothing else is protected. Assuming that the application is installed at context path /myapp, the following are true:

  • http://localhost:8080/myapp/index.xhtml is not protected.
  • http://localhost:8080/myapp/cart/index.xhtml is protected.
A user will be prompted to log in the first time he or she accesses a resource in the cart/ subdirectory.

An HTTP method is protected by a <web-resource-collection> under any of the following circumstances:

  • If the HTTP method is not named in either <http-method> or <http-method-omission> of the <web-resource-collection> (which implies that all are protected)
  • If the collection specifically names the HTTP method in an <http-method> subelement
  • If the collection contains one or more <http-method-omission> elements, none of which names the HTTP method

<auth-constraint> element#

Authorization constraints indicate which users in specified roles which are Authorized to access to the <web-resource-collection>. The <role-name> specified here must either correspond to the <role-name> of one of the <security-role> elements defined for this web application, or be the specially reserved role name *, which is a compact syntax for indicating all roles in the web application.

Role names are case sensitive.

<user-data-constraint> element#

User data constraints specify network security requirements, in particular, this constraint specifies how data communicated between the client and the container should be protected. If a user transport guarantee of INTEGRAL or CONFIDENTIAL is declared, all username and password information will be sent over a secure connection using HTTP over SSL (HTTPS).

<login-config> element#

The login configuration element is used to specify the user authentication Method to be used for access to web content, the realm in which the user will be authenticated, and, in the case of form-based login, additional attributes. When specified, the user must Authenticate before access to any resource that is constrained by a security constraint will be granted.

When a user attempts to access a web resource that is constrained by a <security-constraint> element, the web container activates the authentication mechanism that has been configured for that resource. The authentication mechanism specifies how the user will be prompted to log in. If the <login-config> element is present and the <auth-method> element contains a value other than NONE, the user must be authenticated to access the resource. If you do NOT specify an authentication mechanism, authentication of the user is not required.

The types of user authentication methods are defined in the <auth-method> element and the values supported include:

  • NONE
  • BASIC
  • DIGEST
  • FORM
  • CLIENT-CERT

More Information#

There might be more information for this subject on one of the following:

Add new attachment

Only authorized users are allowed to upload new attachments.
« This page (revision-11) was last changed on 07-Feb-2016 13:37 by jim