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. Create security-role-ref element with role-name field. This element is not strictly required because the security API isUserInRole() method can use the actual role name as a parameter. However, it is good practice to use role references so the software component is reusable.

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. Because actual roles are created during the assembly stage of the application, a developer can use the 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 the actual role. During assembly, the assembler creates a role-link sub element to link the role-name to the actual role.

You can create the security-role-ref element during development with the WebSphere Development Studio Client:

1. Open the web.xml file for your application. It is located in the WEB-INF directory.
2. Click the Security tab.
3. Next to the Security roles window, click Add. Type a name and a decription for the security role. Repeat this step until you have added all the necessary roles.
4. Click the Servlets tab.
5. In the Servlets window, select the servlet for which you want to define the security-role-ref element.
6. Next to the Authorized roles window, click Edit.
7. Select the appropriate roles. Click OK.
8. Save the web.xml file.

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 check authorization. The remote user information can also be used to retrieve the corresponding users information from an external source such as database. 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>