Security annotations

With annotations, during application installation, policies and roles are merged with policies and roles defined within the deployment descriptor. This merge is performed by the Annotations Metadata Manager (AMM) facility. When the metadata is merged, the following inheritance rules are followed.

Scenario	Rules
Metadata in deployment descriptor only	No merge. The security metadata from the deployment descriptor is propagated.
Metadata in annotations only	No merge. The security metadata defined with annotations is propagated.
Metadata in both	Metadata from the deployment descriptor and annotations is merged. Metadata in annotations is overridden by the same type of data from the deployment descriptor.

Six security annotations are currently supported. For each annotation, a MergeAction implementation is defined.

@DeclareRoles

Within each annotated class, for each role, if the roles listed in the deployment descriptor does not contain a SecurityRole with the annotated role name, a new SecurityRole is created and added to this list of roles. Servlet 2.5 and greater and EJB 3.

@RunAs

For each annotated class, find the Servlet or the EJB associated with the given class. It then determines if a run-as element is defined in the deployment descriptor for the servlet or EJB. If one is not found, a new run-as element is created and added to the deployment descriptor. If a run-as element is found, this run-as element will be used instead of creating a new one. The role name used in the RunAs annotation must be defined in the deployment descriptor. Servlet 2.5 and greater and EJB 3.

@DenyAll

For each annotated method, if the method is not included in the deployment descriptor list of excluded methods, and a MethodPermission does not exist in the deployment descriptor, a new MethodElement is created and added to this list of excluded methods in the deployment descriptor. EJB 3 only.

@PermitAll

For each annotated class, find the EJB associated with the given class. It then searches the subset of the MethodElements in the list of all the MethodPermissions defined in the deployment descriptor for this EJB. If a MethodElement with a wildcard method name ("*") is not found and a wildcard method does not exist in the list of excluded methods or in the list of MethodElements with roles, a new MethodPermission and a new MethodElement are created. The new MethodPermission is marked unchecked and is added to the MethodPermission list in the deployment descriptor. The new MethodElement is added to the MethodElement list of the newly created unchecked MethodPermission. Similar action is done for all annotated methods. Instead of a wildcard MethodElement, the method signature must match exactly the signature of the annotated method. EJB 3 only.

@RolesAllowed

For each annotated class, find the EJB associated with the given class. It then finds the subset of the MethodElements in the list of all the MethodPermissions defined in the deployment descriptor for this EJB. If a MethodElement with a wildcard method name ("*") is not found, and a wildcard method does not exist in the list of excluded methods or in the list of unchecked MethodElements, a new MethodPermission and MethodElement are created. If a MethodPermission for this EJB exists with exactly the same roles as those found in the annotation, this MethodPermission will be used instead of creating a new one. For each role in the annotation, a new SecurityRole is created and added to the SecurityRole list in the MethodPermission, If the MethodPermission was newly created, it is added to the MethodPermission list in the deployment descriptor. The new MethodElement created is added to the MethodElement list of the MethodPermission. Similar processing is done for all annotated methods. Instead of a wildcard MethodElement, the method signature must exactly match the signature of the annotated method. Additionally, for each role in the annotation, if the deployment descriptor list of roles does not contain a SecurityRole with the annotated role name, a new SecurityRole is also created and added to this list of roles. EJB 3 only.

@ServletSecurity

For each annotated servlet, find the servlet associated with the given class base on the WebServlet annotation. If RolesAllowed in the ServletSecurity annotation is not found in the deployment descriptor, it then creates a role-name attribute for the role in the deployment descriptor. When an application starts, the WebContainer inspects all servlets with the RunAs, declareRoles, and ServletSecurity annotations, and sets those annotations on the setServletSecurity() method of the ServletRegistration annotation. The WebContainer notifies the security component to inspect all ServletRegistration annotations that have URL patterns and security constraints. The security component then determines if a URL pattern is defined in the deployment descriptor. If one is not defined in the deployment descriptor, the security constraints and RunAs role in the URL pattern are created and then used. If an exact match is already defined in the deployment descriptor, the security constraints and RunAs role in the URL pattern of the deployment descriptor are used instead of the annotation data. When the web authentication system property, com.ibm.wsspi.security.web.webAuthReq, is set to persisting, we can log into an unprotected URL if a valid username and password are provided. Servlet 3.0 only.

The Inherited servlet annotation is a metadata annotation and is not specified in the class. If a subclass does not have security annotation, it automatically inherits security annotation from the parent class. The subclass can overwrite the parent security annotations by specifying its security annotations.

All HTTP methods with no constraints

@WebServlet ("/Example") 
@ServletSecurity
public class Example extends HttpServlet {
}

All HTTP methods with no <auth-constraint> element and confidential TransportGuarantee required

@WebServlet ("/Example")
@ServletSecurity(@HttpConstraint(transportGuarantee = TransportGuarantee.CONFIDENTIAL))
public class Example extends HttpServlet { 
       
}

All HTTP methods with all access denied

@WebServlet ("/Example")
@ServletSecurity(@HttpConstraint(EmptyRoleSemantic.DENY))
public class Example extends HttpServlet {
      
}

All HTTP methods except for the GET and POST values with no constraints

@WebServlet (name="Example", urlPatterns={"/Example"}) 
@ServletSecurity((httpMethodConstraints = {
	@HttpMethodConstraint(value = "GET", rolesAllowed = "ALL ROLE"),
	@HttpMethodConstraint(value="POST", emptyRoleSemantic = EmptyRoleSemantic.DENY))
})
public class Example extends HttpServlet {
     
}

For GET, the <auth-constraint> element requires membership in ALL ROLE. For POST, all access is denied.

All HTTP methods except GET, the <auth-constraint> element requires membership in ALL ROLE, and the GET method has no constraints.

@WebServlet (name="Example", urlPatterns={"/Example"}) 
@ServletSecurity(value = @HttpConstraint(rolesAllowed = "ALL ROLE"),
	httpMethodConstraints = @HttpMethodConstraint("GET"))
public class Example extends HttpServlet {
    
}

All HTTP methods except TRACE, the <auth-constraint> element requires membership in ALL ROLE, and for TRACE, all access is denied.

@WebServlet (name="Example", urlPatterns={"/Example"})
@ServletSecurity(value = @HttpConstraint(rolesAllowed = "ALL ROLE"),
	httpMethodConstraints = @HttpMethodConstraint(value="TRACE",
	emptyRoleSemantic = EmptyRoleSemantic.DENY))
public class Example extends HttpServlet {
   
}

Related:

Authorization providers

JACC policy propagation

Dynamically update servlet security annotations

ServletSecurity