Developing with programmatic security APIs for web applications
Use this information to programmatically secure APIs for web applications.
Before you begin
Programmatic security is used by security-aware applications when declarative security alone is not sufficient to express the security model of the application.
The logout, login, and authenticate APIs are new for Java™ Servlet 3.0 in this release of WebSphere® Application Server.
You can configure several options for web authentication that determine how the web client interacts with protected and unprotected Uniform Resource Identifiers (URI). Also, you 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.
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, you 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.
Procedure
- Add the required security methods in the servlet code.
- 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
Example
<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>
<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>
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 this information in any way as needed by
// the application
....
}
public void doGet(HttpServletRequest request,
HttpServletResponse response) {
....
// to logout the current user. If you 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
....
}
public void doGet(HttpServletRequest request,
HttpServletResponse response) {
....
// to logout the current user. If you 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
....
}
@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 this 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 that is 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.
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);
}
}
<security-role-ref>
<description> </description>
<role-name>Mgr</role-name>
</security-role-ref>