In order to authenticate a user, create a session for the user, and then validate the user's user name and password and "log into" the session. This creates an identity, an instance of java.security.Identity, that is managed by the server context (a view of the server's state). Components can now access the identity for the user from the context by calling getCallerIdentity(), and can use this identity to test whether a user is authentic or to create an audit trail.
Note that the user's identifier and password must be validated against a user name and password that are already known to NAS. NAS looks for user and group entries, as well as the access control lists that determine their respective permissions, in the directory server.
Note.
You can use the NAS Administration Tool to create new users, or you can create entries progammatically within an application using the LDAP JDK included with each installation of NAS. For more information about setting up users in the directory server, see Storing and Managing Users and Groups in the Administration Guide.
Logging In to the Session
You can authenticate a user name and password and log into the session using the method loginSession() from the NAS feature HttpSession2 interface. For example, the following code (in a servlet) authenticates the user and logs them into a session:
String name = req.getParameter("username");
String pass = req.getParameter("password");
HttpSession session = req.getSession(true); // create user session
HttpSession2 sess2 = (HttpSession2) session;
if (sess2.loginSession(name,pass)) // authenticate user
{
// now we have an authenticated session for this user
}
else
{
// authentication failed
}
Once the user is logged into the session, the session can be trusted. Any servlets or EJBs that depend on the session being active can also trust that the user is authentic. If the session expires or the user logs out, the identity is no longer available, and attempts to retrieve the identity fail.
At run time, the container (EJBs) or servlet engine (servlets) throws an exception if an unauthorized user attempts to access the component.
Checking Identity
The identity that is created in the server when the client logs in is an instance of java.security.Identity. This object contains the client's name and other information pertinent to identification. You can determine which client has invoked a component through the caller's context using the method getCallerIdentity(). See Retrieving a Client's Identity below.
Note.
getCallerIdentity() returns null if the session does not exist (i.e. has expired) or if the session is not authenticated.
Identity objects can also identify roles (groups of users). For example, you create an identity for a role in order to test whether the current user is in that role using isCallerInRole(). See Checking a Client's Security Role.
Retrieving a Client's Identity
getCallerIdentity() operates on the standard EJBContext object for EJBs. This example shows an EJB retrieving a caller's identity:
/* Get the security identity of a client. */
Identity caller = EJBContext.getCallerIdentity();
/* Put client's name into human readable form. */
String clientName = caller.getName();
Since the servlet specification does not provide for this type of context, NAS provides two interfaces, ICallerContext and IServerContext, that enable you to derive the caller's identity from the standard ServletContext object. This example shows how to retrieve a caller's identity in a servlet:
ServletContext ctx = getServletContext();
nCtx = (com.netscape.server.IServerContext) ctx;
com.netscape.server.ICallerContext callerCtx = nCtx.getCallerContext();
/* Get the security identity of a client. */
Identity caller = callerCtx.getCallerIdentity();
/* Put client's name into human readable form. */
String clientName = caller.getName();
One possible use for getName() is to create an audit trail by logging the user's name and the current time. For more information, see Controlling Execution Flow. For other methods available in java.security.Identity, see the documentation at:
http://java.sun.com/products/jdk/1.1/docs/api/java.security.Identity.html
Checking a Client's Security Role
Once you create the identity, you can then pass it to a subsequent test for equality or use it as the role parameter of the isCallerInRole() method. The isCallerInRole() method is available in both javax.ejb.EJBContext (for EJBs) and com.netscape.server.ICallerContext (for servlets).
isCallerInRole() requires a java.security.Identity object as a parameter, so to use this method you need an identity that corresponds to the role with which you are concerned. You can create an identity for this role using createIdentityByString("role"), in the IServerContext interface. role must correspond to a user group in the Directory Server.
isCallerInRole() returns a boolean value indicating true or false. For example, in the following code fragment, an EJB checks to see if the client's role is PayrollDept:
/* Check if the client is in the PayrollDept role */
Identity PayRoll = EJBContext.createIdentityByString("PayrollDept");
boolean B = EJBContext.isCallerInRole(PayRoll);
This example shows the same logic in a servlet:
ServletContext ctx = getServletContext();
nCtx = (com.netscape.server.IServerContext) ctx;
com.netscape.server.ICallerContext callerCtx = nCtx.getCallerContext();
/* Check if the client is in the PayrollDept role */
Identity PayRoll = nCtx.createIdentityByString("PayrollDept");
boolean B = callerCtx.isCallerInRole(PayRoll);
Controlling Execution Flow
You can test a client's membership in a role in order to control execution flow. For example, in the following EJB code snippet, if a client is a member of the Payroll department, one set of statements is executed, while if the client is not a member of Payroll, a different set of statements is executed.
/* Check if the client is in the PayrollDept role */
Identity PayRoll = EJBContext.createIdentityByString("PayrollDept");
if (callerCtx.isCallerInRole(PayRoll))
{
// client can edit payroll entries
}
else
{
// client can only view payroll entries
}
This example shows the same logic in a servlet:
ServletContext ctx = getServletContext();
nCtx = (com.netscape.server.IServerContext) ctx;
com.netscape.server.ICallerContext callerCtx = nCtx.getCallerContext();
/* Check if the client is in the PayrollDept role */
Identity PayRoll = nCtx.createIdentityByString("PayrollDept");
if (callerCtx.isCallerInRole(PayRoll))
{
// client can edit payroll entries
}
else
{
// client can only view payroll entries
}
Checking Permission
You can check whether a user or group has permission to execute a given resource by using isAuthorized() to access a programmatic ACL. For more information about ACLs, see Access Control Lists.
Note.
This is different from declarative security, described in Declarative Security, as this ACL is an arbitrary list and is not connected to any specific resource. You can define any permissions you want in a named ACL.
For example, assume you have an ACL named HR_Database that like this:
john_smith write
fred_jones readwrite
bill_white read
In a servlet, you can conditionally execute a block of code based on the user's stated permissions, as in the following example:
HttpSession session = req.getSession; // assume an authorized session
HttpSession2 sess2 = (HttpSession2) session;
if ( sess2.isAuthorized(HR_Database, "read") }
{ ... }
In the above example, the conditional block of code executes if the user is john_smith.
Logging Out of the Session
When authentication is no longer necessary, you can log out of the session using logoutSession(). The session still exists, but it is no longer authenticated. Any subsequent calls to getCallerIdentity() return null.
For example, the following statement nullifies the authenticated identity, though the session remains:
sess2.logoutSession();
Authentication also ends if the session expires or is deleted.
Previous
