Develop secure Web applications

Programmatic security is used by security aware applications when declarative security alone is not sufficient to express the security model of the application. Programmatic security consists of these steps:

1. Add the required security methods in the servlet or JSP code.
2. (Optional) Create security-role-ref element with role-name field. You do not have to create a security-role-ref element because the security API isUserInRole() can use the actual role name as a parameter. However, it is good practice to use role references so the software component is reuseable.

For a full code example, see Example: Secure Web application code.

Add required security methods in the servlet code

Programmatic security consists of these methods of the HttpServletRequest interface:

• getRemoteUser()
  This method returns user name the client used for authentication. returns null if no user has been authenticated.

• isUserInRole (String rolename)
  This method returns true if the remote user is granted the specified security role. If remote user is not granted the specified role or if no user is authenticated, it returns false.

• getUserPrincipal()
  This method returns java.security.Principal object containing the remote user name. If no user is authenticated, it returns null.

Programmatic servlet security methods can be added inside any of the servlet's doGet(), doPost(), doPut(), doDelete() service methods. Here is an example of usage of programmatic security APIs:

  public void doGet(HttpServletRequest request, HttpServletResponse response) {
    ...
    // to get remote user using getUserPrincipal()
    java.security.Principal principal = request.getUserPrincipal();     
    String remoteUser = principal.getName();
 
    // to get remote user using getRemoteUser()
    remoteUser = request.getRemoteUser();

    // to check if remote user is granted Mgr role
    boolean isMgr = request.isUserInRole("Mgr");

    // use the above information in any way as needed by the application 
    ...
  }

Create security-role-ref element with role-name field

This step is required to programmatically secure an application. If security-role-ref is not created during development, make sure it is created during assembly stage.

When the isUserInRole() method is used, a security-role-ref element should be declared in the deployment descriptor with a role-name element that contains the role name that is passed to this method. Since actual roles are created during assembly stage of the application, a developer can use logical role as role name and provide enough hints to the assembler in the description of the security-role-ref element to link that role to actual role. During assembly, assembler creates a role-link sub element to link the role-name to actual role. Creation of security-role-ref element is possible if developing tools such as WebSphere Studio Application Developer is used. You can also create the security-role-ref element during assembly with the Application Assembly Tool.

An example where it is useful to define logical roles is when you want a Web application to access external resources and to control the access to external resources by using its own authorization table (external-resource to remote-user mapping). In this case, the getUserPrincipal() or getRemoteUser() method can be used to get the remote user, and then the application can consult its own Authorization Table to perform authorization. The remote user information can also be used to retrieve the corresponding users information from an external source such as database or from an enterprise bean. isUserInRole() can also be used similarly.

Here is an example:

  <security-role-ref>
    <description>Provide hints to assembler for linking
     this role-name to actual role here</description>
    <role-name>Mgr</role-name>
  </security-role-ref>

During assembly, the assembler creates role-link as shown below:

  <security-role-ref>
    <description>Hints provided by developer to
     map role-name to role-link</description>
    <role-name>Mgr</role-name>
    <role-link>Manager</role-link>
  </security-role-ref>