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. Programmatic security consists of the following methods
of the HttpServletRequest interface:
- getRemoteUser
- Returns the user name that the client used for authentication. Returns null if
no user is authenticated.
- isUserInRole
- (String role name): Returns true if the remote user is granted
the specified security role. If the remote user is not granted the specified
role, or if no user is authenticated, it returns false.
- getUserPrincipal
- Returns the java.security.Principal object that contains the remote user
name. If no user is authenticated, it returns null.
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. 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 (RAD) is used. You
also can create the security-role-ref element during assembly stage using
an assembly tool.
Example
This step is 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 and then it 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. You can use the isUserInRole method in a similar way.
After development,
a security-role-ref element can be created:
<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>
You 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 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
....
}