Specifying Security Constraints

In document Java Servlet Specification (Page 157-162)

Mapping Requests to Servlets

13.8 Specifying Security Constraints

Security constraints are a declarative way of defining the protection of web content. A security constraint associates authorization and or user data constraints with HTTP operations on web resources. A security constraint, represented as a security-constraint in a deployment descriptor, consists of the following elements:

■ web resource collection (web-resource-collection in deployment descriptor)

■ authorization constraint (auth-constraint in deployment descriptor)

■ user data constraint (user-data-constraint in deployment descriptor) The HTTP operations and web resources to which a security constraint applies (i.e. the constrained requests) are identified by one or more web resource collections. A web resource collection consists of the following elements:

■ URL patterns (url-pattern in deployment descriptor)

■ HTTP methods (http-method or http-method-omission elements in the deployment descriptor)

An authorization constraint establishes a requirement for authentication and names the authorization roles permitted to perform the constrained requests. A user must be a member of at least one of the named roles to be permitted to perform the constrained requests. The special role name “*” is a shorthand for all role names defined in the deployment descriptor. An authorization constraint that names no roles indicates that access to the constrained requests must not be permitted under any circumstances. An authorization constraint consists of the following element:

■ role name (role-name in deployment descriptor)

A user data constraint establishes a requirement that the constrained requests be received over a protected transport layer connection. The strength of the required protection is defined by the value of the transport guarantee. A transport guarantee of INTEGRAL is used to establish a requirement for content integrity and a transport guarantee of CONFIDENTIAL is used to establish a requirement for confidentiality. The transport guarantee of “NONE” indicates that the container must accept the constrained requests when received on any connection including an unprotected one. A user data constraint consists of the following element:

If no authorization constraint applies to a request, the container must accept the request without requiring user authentication. If no user data constraint applies to a request, the container must accept the request when received over any

connection including an unprotected one.

13.8.1

Combining Constraints

For the purpose of combining constraints, an HTTP method is said to occur within a web-resource-collection when no HTTP methods are named in the collection, or the collection specifically names the HTTP method in a contained http-method element, or the collection contains one or more http-method-omission elements, none of which names the HTTP method.

When a url-pattern and HTTP method pair occurs in combination( i.e, within a web- resource-collection) in multiple security constraints, the constraints (on the pattern and method) are defined by combining the individual constraints. The rules for combining constraints in which the same pattern and method occur are as follows:

The combination of authorization constraints that name roles or that imply roles via the name “*” shall yield the union of the role names in the individual constraints as permitted roles. A security constraint that does not contain an authorization constraint shall combine with authorization constraints that name or imply roles to allow unauthenticated access. The special case of an authorization constraint that names no roles shall combine with any other constraints to override their affects and cause access to be precluded.

The combination of user-data-constraints that apply to a common url- pattern and http-method shall yield the union of connection types accepted by

the individual constraints as acceptable connection types. A security constraint that does not contain a user-data-constraint shall combine with other user-data- constraint to cause the unprotected connection type to be an accepted connection type.

Chapter 13 Security 137

13.8.2

Example

The following example illustrates the combination of constraints and their translation into a table of applicable constraints. Suppose that a deployment descriptor contained the following security constraints.

<security-constraint> <web-resource-collection> <web-resource-name>precluded methods</web-resource-name> <url-pattern>/*</url-pattern> <url-pattern>/acme/wholesale/*</url-pattern> <url-pattern>/acme/retail/*</url-pattern> <http-method-exception>GET</http-method-exception> <http-method-exception>POST</http-method-exception> </web-resource-collection> <auth-constraint/> </security-constraint> <security-constraint> <web-resource-collection> <web-resource-name>wholesale</web-resource-name> <url-pattern>/acme/wholesale/*</url-pattern> <http-method>GET</http-method> <http-method>PUT</http-method> </web-resource-collection> <auth-constraint> <role-name>SALESCLERK</role-name> </auth-constraint> </security-constraint>

<security-constraint> <web-resource-collection> <web-resource-name>wholesale 2</web-resource-name> <url-pattern>/acme/wholesale/*</url-pattern> <http-method>GET</http-method> <http-method>POST</http-method> </web-resource-collection> <auth-constraint> <role-name>CONTRACTOR</role-name> </auth-constraint> <user-data-constraint> <transport-guarantee>CONFIDENTIAL</transport-guarantee> </user-data-constraint> </security-constraint> <security-constraint> <web-resource-collection> <web-resource-name>retail</web-resource-name> <url-pattern>/acme/retail/*</url-pattern> <http-method>GET</http-method> <http-method>POST</http-method> </web-resource-collection> <auth-constraint> <role-name>CONTRACTOR</role-name> <role-name>HOMEOWNER</role-name> </auth-constraint> </security-constraint>

Chapter 13 Security 139

The translation of this hypothetical deployment descriptor would yield the constraints defined in TABLE 13-4.

13.8.3

Processing Requests

When a Servlet container receives a request, it shall use the algorithm described in “Use of URL Paths” on page 115 to select the constraints (if any) defined on the url- pattern that is the best match to the request URI. If no constraints are selected, the container shall accept the request. Otherwise the container shall determine if the HTTP method of the request is constrained at the selected pattern. If it is not, the request shall be accepted. Otherwise, the request must satisfy the constraints that apply to the HTTP method at the url-pattern. Both of the following rules must be satisfied for the request to be accepted and dispatched to the associated servlet.

TABLE 13-4 Security Constraint Table

url-pattern

http-

method permitted roles supported connection types

/* all methods except GET, POST access precluded not constrained /acme/wholesale/* all methods except GET, POST

access precluded not constrained

/acme/wholesale/* GET CONTRACTOR

SALESCLERK

not constrained

/acme/wholesale/* POST CONTRACTOR CONFIDENTIAL

/acme/retail/* all

methods except GET, POST

access precluded not constrained

/acme/retail/* GET CONTRACTOR

HOMEOWNER

not constrained

/acme/retail/* POST CONTRACTOR

HOMEOWNER

1. The characteristics of the connection on which the request was received must satisfy at least one of the supported connection types defined by the constraints. If this rule is not satisfied, the container shall reject the request and redirect it to the HTTPS port.2

2. The authentication characteristics of the request must satisfy any authentication and role requirements defined by the constraints. If this rule is not satisfied because access has been precluded (by an authorization constraint naming no roles), the request shall be rejected as forbidden and a 403 (SC_FORBIDDEN) status code shall be returned to the user. If access is restricted to permitted roles and the request has not been authenticated, the request shall be rejected as unauthorized and a 401 (SC_UNAUTHORIZED) status code shall be returned to cause authentication. If access is restricted to permitted roles and the

authentication identity of the request is not a member of any of these roles, the request shall be rejected as forbidden and a 403 (SC_FORBIDDEN) status code shall be returned to the user.

In document Java Servlet Specification (Page 157-162)