Home | Download | PDF | API | FAQ | Search | Feedback | History

> ## Checking Caller Identity Programmatically

> In general, security management should be enforced by the container in a manner that is transparent to the web component. The security API described in this section should be used only in the less frequent situations in which the web component methods need to access the security context information.

> The `HttpServletRequest` interface provides the following methods that enable you to access security information about the component's caller:

> - `getRemoteUser`: Determines the user name with which the client authenticated. If no user has been authenticated, this method returns `null`.
> - `isUserInRole`: Determines whether a remote user is in a specific security role. If no user has been authenticated, this method returns `false`. This method expects a `String` user `role-name` parameter.

> You can use either the `@DeclareRoles` annotation or the `<security-role-ref>` element with a `<role-name>` sub-element in the deployment descriptor to pass the role name to this method. Using security role references is discussed in Declaring and Linking Role References.

> - `getUserPrincipal`: Determines the principal name of the current user and returns a `java.security.Principal` object. If no user has been authenticated, this method returns `null`.

> Your application can make business logic decisions based on the information obtained using these APIs.

> The following is a code snippet from the file `<`AS_INSTALL`>\samples\webapps\apps\simple\web\jsp\security\protected\index.jsp` that uses these methods to access security information about the component's caller. You must have the samples server installed to view this file.

>     <%@ taglib prefix="fmt" uri="http://java.sun.com/jstl/fmt" %>
>     <fmt:setBundle basename="LocalStrings"/>

>     <html>
>     <head>
>     <title><fmt:message key="index.jsp.title"/>/title>
>     </head>
>     <body bgcolor="white">

>     <fmt:message key="index.jsp.remoteuser"/> <b><%= request.getRemoteUser() %>
>     </b><br><br>

>     <%
>       if (request.getUserPrincipal() != null) {
>     %>
>       <fmt:message key="index.jsp.principal"/> <b>
>     <%= request.getUserPrincipal().getName() %></b><br><br>
>     <%
>       } else {
>     %>
>       <fmt:message key="index.jsp.noprincipal"/>
>     <%
>       }
>     %>

>     <%
>       String role = request.getParameter("role");
>       if (role == null)
>         role = "";
>       if (role.length() > 0) {
>         if (request.isUserInRole(role)) {
>     %>
>           <fmt:message key="index.jsp.granted"/> <b><%= role %></b><br><br>
>     <%
>         } else {
>     %>
>           <fmt:message key="index.jsp.notgranted"/> <b><%= role %></b><br><br>
>     <%
>         }
>       }
>     %>

>     <fmt:message key="index.jsp.tocheck"/>
>     <form method="GET">
>     <input type="text" name="role" value="<%= role %>">
>     </form>

>     </body>
>     </html>

> ### Declaring and Linking Role References

> A security role is an application-specific logical grouping of users, classified by common traits such as customer profile or job title. When an application is deployed, these roles are mapped to security identities, such as principals (identities assigned to users as a result of authentication) or groups, in the runtime environment. Based on this mapping, a user with a certain security role has associated access rights to a web application.

> The value passed to the `isUserInRole` method is a `String` representing the role name of the user. A security role reference defines a mapping between the name of a role that is called from a web component using `isUserInRole(String role)` and the name of a security role that has been defined for the application. If a `<security-role-ref>` element is not declared in a deployment descriptor, and the `isUserInRole` method is called, the container defaults to checking the provided role name against the list of all security roles defined for the web application. Using the default method instead of using the `<security-role-ref>` element limits your flexibility to change role names in an application without also recompiling the servlet making the call.

> For example, during application assembly, the assembler creates security roles for the application and associates these roles with available security mechanisms. The assembler then resolves the security role references in individual servlets and JSP pages by linking them to roles defined for the application. For example, the assembler could map the security role reference `cust` to the security role with the role name `bankCustomer` using the `<security-role-ref>` element of the deployment descriptor.

> #### Declaring Roles Using Annotations

> The preferred method of declaring roles referenced in an application is to use the `@DeclareRoles` annotation. The following code sample provides an example that specifies that the roles of `j2ee` and `guest` will be used in the application, and verifies that the user is in the role of `j2ee` before printing out `Hello World`.

>     import java.io.IOException;
>     import java.io.PrintWriter;

>     import javax.annotation.security.DeclareRoles;
>     import javax.servlet.ServletException;
>     import javax.servlet.http.HttpServlet;
>     import javax.servlet.http.HttpServletRequest;
>     import javax.servlet.http.HttpServletResponse;

>     @DeclareRoles({"j2ee", "guest"})
>     public class Servlet extends HttpServlet {

>       public void service(HttpServletRequest req, HttpServletResponse resp)
>           throws ServletException, IOException {
>         resp.setContentType("text/html");
>         PrintWriter out = resp.getWriter();

>         out.println("<HTML><HEAD><TITLE>Servlet Output</TITLE>
>           </HEAD><BODY>");
>          if (req.isUserInRole("j2ee") && !req.isUserInRole("guest")) {
>           out.println("Hello World");
>         } else {
>           out.println("Invalid roles");
>         }
>         out.println("</BODY></HTML>");
>       }
>     }

> #### Declaring Roles Using Deployment Descriptor Elements

> An example of declaring roles referenced in an application using deployment descriptor elements is shown in the following `web.xml` deployment descriptor snippet:

>     <servlet>
>     . . .
>        <security-role-ref>
>           <role-name>cust</role-name>
>           <role-link>bankCustomer</role-link>
>        </security-role-ref>
>     . . .
>     </servlet>

> When you use the `isUserInRole(String role)` method, the String `role` is mapped to the role name defined in the <`role-name>` element nested within the `<security-role-ref>` element. The `<role-link>` element in the `web.xml` deployment descriptor must match a `<role-name>` defined in the `<security-role>` element of the `web.xml` deployment descriptor, as shown here:

>     <security-role>
>          <role-name>bankCustomer</role-name>
>     </security-role>