+

Search Tips   |   Advanced Search

Develop with programmatic security APIs for web applications

Use this information to programmatically secure APIs for 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.

The authenticate, login, logout, getRemoteUser, isUserInRole and getAuthType servlet security methods are methods of the javax.servlet.http.HttpServletRequest interface. For more detailed information about these servlet security methods, read the Servlet security methods article.

The logout, login, and authenticate APIs are new for Java Servlet 3.0 in this release of WAS.

We can configure several options for web authentication that determine how the web client interacts with protected and unprotected Uniform Resource Identifiers (URI). Also, we can specify whether WebSphere Application Server challenges the web client for basic authentication information if the certificate authentication for the HTTPS client fails. For more information, see the Selecting an authentication mechanism article.

(zos) We can enable a login module to indicate which principal class is returned by these calls. Refer to the topic about mapping a registry principal to a System Authorization Facility user ID using a Java Authentication and Authorization Services login module for more information.

When the isUserInRole method is used, declare a security-role-ref element in the deployment descriptor with a role-name subelement containing the role name that is passed to this method, or use the @DeclareRoles annotation. Because actual roles are created during the assembly stage of the application, we can use a logical role as the 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 subelement to link the role name to the actual role. Creation of a security-role-ref element is possible if an assembly tool, such as Rational Application Developer, is used. You also can create the security-role-ref element during assembly stage using an assembly tool.

  1. Add the required security methods in the servlet code.

  2. Create a security-role-ref element with the role-name field. If a security-role-ref element is not created during development, make sure it is created during the assembly stage.


Results

A programmatically secured servlet application.


Example

These steps are required to secure an application programmatically. This action is particularly useful when a web application needs to access external resources and wants to control the access to external resources using its own authorization table (external-resource to remote-user mapping). In this case, use the getUserPrincipal or the getRemoteUser methods to get the remote user, then the application can consult its own authorization table to perform authorization. The remote user information also can help retrieve the corresponding user information from an external source such as a database or from an enterprise bean. We can use the isUserInRole method in a similar way.

After development, we can create a security-role-ref element: 

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

During assembly, the assembler creates a role-link element: 

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

We can add programmatic servlet security methods inside any servlet doGet, doPost, doPut, and doDelete service methods. The following example depicts using a programmatic security API: 

public void doGet(HttpServletRequest request, 
HttpServletResponse response) {

   ....
   // to logoff the current user   request.logout();
    
   // to login with a new user    request.login("bob","bobpwd")

   // 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 
   ....
                  
}

We can programmatic login with a user ID and password inside any servlet doGet, doPost, doPut, and doDelete service methods. The following example depicts using a programmatic login/logout API: 

public void doGet(HttpServletRequest request, 
HttpServletResponse response) {

   ....
   // to logout the current user. If we are not already authenticate, then no need to call the logout() method.
   request.logout();
    
   // to login with a new user    request.login("utle","mypwd")

   // the user utle subject now set on the thread and the LTPA SSO cookie is set in the response    ....
                  
}

We can programmatic authenticate with a different identity inside any servlet doGet, doPost, doPut, and doDelete service methods. In this example, if the web servlet is configured to use basicAuth, the web server returns a response code 401, the login prompt is displayed, and we can enter the user ID and password to authenticate. The following example depicts using a programmatic login/logout API: 

public void doGet(HttpServletRequest request, 
HttpServletResponse response) {

   ....
   // to logout the current user. If we are not already authenticate, then no need to call the logout() method.
    
   // to login with a new user    request.authenticate(response);

   // the new user subject now set on the thread and the LTPA SSO cookie is set in the response    ....
                  
}

When developing Servlet 3.0 modules, the value of the rolename argument in isCallerInRole method can be defined using Java annotations instead of declaring a security-role-ref elements in the deployment descriptor. 

@javax.annotation.security.DeclareRoles("Mgr")
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 
   ....
                  
}

The following example depicts a web application or servlet using the programmatic security model.

This example illustrates one use and not necessarily the only use of the programmatic security model. The application can use the information returned by the getUserPrincipal, isUserInRole, and the getRemoteUser methods in any other way that is meaningful to that application. Use the declarative security model whenever possible.

File : HelloServlet.java 

public class HelloServlet extends javax.servlet.http.HttpServlet {

 public void doPost(
  javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
  throws javax.servlet.ServletException, java.io.IOException {
 }
public void doGet(
  javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
  throws javax.servlet.ServletException, java.io.IOException {
   
        String s = "Hello";
   
         
        // get remote user using getUserPrincipal()
        java.security.Principal principal = request.getUserPrincipal();
        String remoteUserName = "";
        if( principal != null )
          remoteUserName = principal.getName();
// get remote user using getRemoteUser()
        String remoteUser = request.getRemoteUser();

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

        // display Hello username for managers and bob. 
        if ( isMgr || remoteUserName.equals("bob") )
            s = "Hello " + remoteUserName;

   String message =  "<html> \n" +
              "<head><title>Hello Servlet</title></head>\n" +
         "<body> /n +"
    "<h1> "  +s+ </h1>/n " + 
  byte[] bytes = message.getBytes();
  
  // displays "Hello" for ordinary users 
        // and displays "Hello username" for managers and "bob".
        response.getOutputStream().write(bytes);
 }

}

After developing the servlet, we can create a security role reference for the HelloServlet servlet as shown in the following example: 

<security-role-ref>
     <description> </description>
     <role-name>Mgr</role-name>
</security-role-ref>


What to do next

After developing an application, use an assembly tool to create roles and to link the actual roles to role names in the security-role-ref elements. See the information about securing web applications using an assembly tool.


Subtopics


Related concepts

  • Role-based authorization


    Related tasks

  • Configure servlet filters for form login processing
  • Secure web applications using an assembly tool
  • Select an authentication mechanism

    (zos) Map a registry principal to a System Authorization Facility user ID using a Java Authentication and Authorization Services login module