Tutorial: How JAAS enables use of custom security repositories with J2EE applications

This tutorial describes how a developer can write a custom JAASTM LoginModule for using an LDAP authentication data store along with a Java TM 2 Platform, Enterprise Edition (J2EETM) application. The tutorial includes a sample implementation of a LDAP based LoginModule which is downloadable as jaastutorial.zip. The archive contains: 1. jaastutorial.jar 2. jaasclient.jar 3. jaastutorial.bat 4. jaastutorial.sh 5. login.cfg The following products were used in creating this tutorial: 1. Pramati Server 3.0 2. Pramati Studio 3.0 3. OpenLDAP 2.0.18 The following specifications apply to this tutorial: 1. Java Authentication and Authorization Service TM 1.0 2. Java TM 2 Platform, Enterprise Edition 1.3 3. Lightweight Directory Access Protocol 3.0

W hy JAAS in J2EE J2EE m ode l: role s, use rs and JAAS W riting the JAAS se curity m odule Ste p 1: W riting the LoginModule initialize () m e thod login() m e thod com m it() m e thod abort() m e thod logout() m e thod Ex ce ptions thrown by LoginModule m e thods Ste p 2: W riting the C allBack Handle r Ste p 3: C onfiguring the J2EE application Ste p 4: Pack aging the LoginModule along with application Ste p 5: Inte grating the LoginModule with the J2EE se rve r Sam ple LDAP-base d LoginModule Installing and configuring the O pe nLDAP Se rve r LDAP param e te rs for LoginModule and Use r Manage r C onfiguring LoginModule with Pram ati Se rve r C onfiguring the Use r Manage r C re ating use rs and role s from the Use r Manage r Se tting the clie nt classpath R unning the sam ple Sum m ary

Why JAAS in J2EE

www.pramati.com/docstore/1270002/index.htm 1/8

One of the limitations of J2EE Version 1.2 platform was it did not provide application developers with a standard route to integrating the application server realm with existing or custom security infrastructures. J2EE Version 1.3 now solves that with the inclusion of Java Authentication and Authorization Service (JAAS) framework. J2EE application servers that implement JAAS provide enterprise application developers with the standard Login Module API for tapping custom or legacy security systems from their applications. While application developers write to the LoginModule API (specifically, LoginC ontext API), the application server implements the LoginModule interface. The standards-based LoginModule interface gives J2EE developers the freedom to tap a variety of information sources that use Java Database C onnectivity, the lightweight directory access protocol (LDAP) or Shared File Systems to store authentication data - without requiring them to modify the application code. Indeed, there are increasing number of scenarios where J2EE application developers wish to tap custom authentication repositories from their applications. They would do this by writing a Login Module, packaging it along with their application and distributing to target J2EE application servers in a prescribed way. Read more on the limitations in the J2EE 1.2 Security Model.

J2EE Model: Roles, Users and JAAS

The J2EE model defines security at two levels: system and application. System level security is defined in terms of User Groups, called Roles, and in terms of security privileges mapping definitions, called Realms. Realms are mappings of one or more User Groups to a set of privileges or permissions. Application level security is constituted from User Groups and Realms. At the application level, security permissions also list the various application components that are accessible by each User Group in each Realm. Thus, when an application is deployed, its application level realms and roles are mapped to the system level realms and roles defined on the server. J2EE application servers implementing JAAS enable application developers to write a custom "pluggable" login module in the server environment. Such a module provides a conduit for roles defined in the packaged application to user group information stored in some custom authentication repository, say an LDAP server.

How LoginModule he lps application role s and groups m ap to authe ntication data store d in a custom re pository such as LDAP.

www.pramati.com/docstore/1270002/index.htm

2/8

Writing the JAAS Security Module

A J2EE application developer writing security with JAAS would basically write the Login Module. The JAAS interface implementation holds the authentication logic. Application servers typically ship with standard Login Module implementations. Application developers may want to write their own implementation, and will see how in this tutorial in the following steps: 1. Writing the 2. Writing the
L o g i n M o d u l e interface

(L o g i n C o n t e x t API) that enables client to pass authentication data to the server the server and application

C a l l B a c k H a n d l e r interface

3. C onfiguring the

L o g i n M o d u l e and C a l l B a c k H a n d l e r with

4. Packaging the application along with module classes 5. Integrating the LoginModule with the application server Read more on Standalone JAAS versus JAAS in the J2EE Model.

Step 1: Writing the LoginModule

In this tutorial, you will see code snippets from a
L o g i n M o d u l e implementation

for an LDAP Server. We also

demonstrate how to test the LDAP LoginModule sample in a typical J2EE application server environment. This is how the LoginModule implementation class is defined:

p u b l i cc l a s sL D A P L o g i n M o d u l ei m p l e m e n t sL o g i n M o d u l e
The standard JAAS packages required by this class are imported as shown here:

i m p o r tj a v a x . s e c u r i t y . * ;
Standards methods in the LoginModule that must be implemented are: 1. 2. 3. 4. 5.
i n i t i a l i z e ( ) l o g i n ( ) c o m m i t ( ) a b o r t ( ) l o g o u t ( )

initialize()
The initialize method does the following: 1. Sets configurations required by the LoginModule 2. C ollects login information that is encapsulated in the C allBackHandler 3. Initializes and instantiates all configuration parameters for this instance of the LoginModule The client instantiates the LoginC ontext object and passes a C allBackHandler instance with the user name and password. When the LoginC ontext object is instantiated, the initialize() method of the LoginModule is triggered.

p u b l i cs t a t i cv o i dm a i n ( S t r i n ga r g s [ ] ) { L o g i n C o n t e x tl c=n e wL o g i n C o n t e x t ( " L o g i n " , n e wM y C a l l b a c k H a n d l e r ( a r g s [ 0 ] , a r g s [ 1 ] ) ) ; }

www.pramati.com/docstore/1270002/index.htm 3/8

login()
This method returns a boolean variable, which is true if the authentication information provided is valid. The login method performs the following tasks: 1. Fetches the login information 2. Authenticates the user The login information is fetched using the C allBackHandler. The code that does this is shown here:

C a l l b a c k [ ]c a l l s = n e wC a l l b a c k [ 2 ] ; c a l l s [ 0 ] = n e wN a m e C a l l b a c k ( " n a m e " ) ; c a l l s [ 1 ] = n e wP a s s w o r d C a l l b a c k ( " P a s s w o r d " , f a l s e ) ; c a l l b a c k H a n d l e r . h a n d l e ( c a l l s ) ;

The
l o g i n method

tries to connect to the server using the login information that is fetched. If the connection is

established, the method returns the value true. The following code snippet shows this:

b o o l e a nv e r i f i c a t i o n = f a l s e ; t r y { p r o p s . p u t ( C o n t e x t . S E C U R I T Y _ P R I N C I P A L , c b U s e r N a m e ) ; p r o p s . p u t ( C o n t e x t . S E C U R I T Y _ C R E D E N T I A L S , c b P a s s w o r d ) ; c t x=n e wI n i t i a l D i r C o n t e x t ( p r o p s ) ; v e r i f i c a t i o n = t r u e ; } r e t u r nv e r i f i c a t i o n ;
This code changes with the actual type of security framework for which the LoginModule is written.

commit() method
This method sets the subject in the session to the username that is validated by the the user is not validated, the
c o m m i t method l o g i n method.

It also

populates the subject with roles specified in the LDAP server (in this tutorial) for that user, and returns true. If returns false. The following code snippet shows this:

i f ( v e r i f i c a t i o n ) { s u b j e c t . g e t P r i n c i p a l s ( ) . a d d ( u s e r N a m e ) ; s u b j e c t . g e t P r i n c i p a l s ( ) . a d d ( r o l e ) ; r e t u r nt r u e ; } e l s er e t u r nf a l s e ; abort() method
This method is used to exit the LoginModule in case of runtime exceptions and is usually triggered by the application server. This method is invoked after the abort() method of LoginC ontext. The application developer must not directly call the abort method of the LoginC ontext interface.

logout() method
This method clears the principal settings of the subject in the session. It removes the privilege settings associated with the roles of the subject. The following code snippet shows this:

s u b j e c t . g e t P r i n c i p a l s ( ) . c l e a r ( ) ; v e r i f i c a t i o n = f a l s e ; r e t u r nt r u e ; Exceptions thrown by LoginModule methods

www.pramati.com/docstore/1270002/index.htm 4/8

According to the JAAS specifications, all LoginModule methods should only throw a LoginException. Any other exception during LoginModule execution should be caught and a LoginException thrown against it. The following code snippet shows how this can be done:

p u b l i cb o o l e a nl o g i n ( )t h r o w sL o g i n E x c e p t i o n { c a t c h ( I O E x c e p t i o ne ) { t h r o wn e wL o g i n E x c e p t i o n ( e . t o S t r i n g ( ) ) ; } } Step 2: Writing the CallBackHandler

The C allBackHandler is the JAAS interface that defines the type of data used for authentication. For example, a username-password or a user-certificate combination forms a security identity and credential pair. The type of data used for validating the identity is defined as part of the implementation of the C allBackHandler interface. The C allbackHandler implementation contains a single method, handle(). The following code snippet from the C allBackHandler distributed with the sample client application C lientLoginSample.java demonstrates this:

s t a t i cc l a s sM y C a l l b a c k H a n d l e ri m p l e m e n t sC a l l b a c k H a n d l e r { p r i v a t eS t r i n gu s e r n a m e ; p r i v a t eS t r i n gp a s s w o r d ;
The handle() method sets the value of the username and password attributes, passed by the client application, in the LoginModule's C allBackHandler. The following code snippet shows this:

h a n d l e ( ) { i f ( c a l l b a c k s [ i ]i n s t a n c e o fN a m e C a l l b a c k ) { N a m e C a l l b a c kn c b=( N a m e C a l l b a c k ) c a l l b a c k s [ i ] ; n c b . s e t N a m e ( u s e r n a m e ) ; } i f ( c a l l b a c k s [ i ]i n s t a n c e o fP a s s w o r d C a l l b a c k ) { P a s s w o r d C a l l b a c kp c b=( P a s s w o r d C a l l b a c k ) c a l l b a c k s [ i ] ; p c b . s e t P a s s w o r d ( p a s s w o r d . t o C h a r A r r a y ( ) ) ; } } Step 3: Configuring the J2EE application

A J2EE application package includes descriptors that contain information about security privileges for various modules/components of the application. Security privilege is defined at the application level and is associated with realms and roles. During deployment, these roles are mapped to roles defined in the server-level realm. C onfiguring a login module with a J2EE application involves the following steps: 1. C reating a login UI that validates user information by calling the LoginC ontext interface. 2. C reating application level realms and roles, and mapping permissions to application components 3. Distributing the Login Module classes with the application

Step 4: Packaging the Login Module along with Application

A J2EE application developer would want to configure the LoginModule with a target J2EE application server. Therefore, the LoginModule, along with the helper classes, is packaged into a separate JAR file that may be distributed independent of the application archives, and separately loaded from the server classpath.

www.pramati.com/docstore/1270002/index.htm

5/8

For this reason, there must be no code-level dependencies in the LoginModule on the J2EE application.

Step 5: Integrating the Login Module with the J2EE Application Server
The deployment process for a LoginModule is unlike J2EE applications and involves configuring the target application server. A J2EE application server organizes its security environment into realms, each of which maps to one or more login modules, and has one or more users and roles defined on it. This differs from application realms, which are associated with security permissions for the application and do not assume the existence of any LoginModule. Integrating a LoginModule with the application server involves the following steps: 1. C onfiguring the server with a realm that uses a specific LoginModule for security authentication. 2. Mapping the application realm and roles to the realm and roles defined by the LoginModule.

Sample LDAP-based LoginModule

The tutorial includes a sample implementation of a LDAP based LoginModule. Download the required sample files here (jaastutorial.zip). We illustrate the steps to integrate this implementation of the LDAP-based LoginModule with Pramati Server using a sample application. The sample application uses Pramati's implementation of the User Manager Module, which creates users on the LDAP Server and maps roles to various user names defined on the LDAP server. Get the User Manager API here.

Installing and configuring the LDAP server

This tutorial is written assuming a particular directory structure on a LDAP Server. If you do not have a LDAP Server installed, download one from www.openldap.org. You may access this FTP site. OpenLDAP Server is distributed for Unix/Linux platforms. Download the Quickstart Guide for LDAP and do as follows to create the required directory structure: 1. Replace the directory names
M Y D O M A I N and e x a m p l e with s l a p d . c o n f ,

the name

m y _ c o m p a n y . r o o t p w as m y _ p a s s w o r d . s l a p d . c o n f file:

2. In the LDAP server configuration file

set password against the name

3. Disable the schema checks on the LDAP server by adding the following line to the
s c h e m a c h e c ko f f

4. After configuring the LDAP Server with the directory structure, start the server as instructed in the Quickstart Guide.

LDAP parameters for Login Module and the User Manager

Name LDAPSe rve rUrl Value The UR L and port of the LDAP Se rve r. If the LDAP se rve r is running on the sam e host as the application se rve r, it would be ldap://localhost:389 (with LDAP Se rve r on port 389) A de fault standard conte x t factory im ple m e ntation is provide d by Sun. Se t this fie ld O NLY if you are using an othe r C onte x t Factory. Add the factory to the se rve r classpath too. You will ne e d to re start the se rve r. This is the application se rve r-le ve l re alm . For e x am ple , ldap cn 6/8

LDAPC onte x tFactory

R e alm nam e LDAPUse rKe y

www.pramati.com/docstore/1270002/index.htm

LDAPUse rSupe rC onte x t For e x am ple , dc=m y_com pany, dc=com LDAPR ole sKe y LDAPSupe rUse rDN sn For e x am ple , cn=m anage r,dc=m y_com pany,dc=com . This re fe rs to the distinguishing nam e of the LDAP supe r use r and is se t by the LDAP adm inistrator.

The LDAP supe r use r password to the se rve r. This is ne e de d LDAPSupe rUse rPassword to allow addition and re m oval of use rs by the LDAP Use r Manage r.

Configuring LoginModule with Pramati Server

1. Place the 2. Run
j a a s t u t o r i a l . j a r in

the classpath of the server by editing the

s e t u p . b a t .

s e t u p . b a t from

the command line.

3. Start the Server and then start the C onsole. 4. Select the Security node in the tree panel on the C onsole and select '+' for adding an LDAP realm. 5. In the View Panel, choose an appropriate server realm name, say, ldap. 6. Add the path to the LoginModule class as com.pramati.security.loginmodules.ldap.LDAPLoginModule. 7. Specify the
F l a g as R e q u i r e d .

8. The Init options require multiple name-value pairs and these are listed as LDAP parameters in the section above.

Configuring the User Manager

1. On the same page, give the fully qualified path of the User Manager class as
c o m . p r a m a t i . s e c u r i t y . l o g i n m o d u l e s . l d a p . L D A P U s e r M a n a g e r

2. The User Manager needs the same name-value pairs as the LoginModule in the Init Options. After configuring the LoginModule and the UserManager for the LDAP realm, click on Add button to register the LDAP realm with the application server. Ensure that the jaastutorial.jar package is present in the server classpath, before starting the server.

Creating users and roles using the User Manager

From the C onsole, configuring new users with unique user names and passwords, roles within the realm, and mapping the roles and users effectively test the LDAP User Manager Module. If the configuration is correct, new users and their role mappings are added to the realm that can be viewed from the C onsole.

Setting the client classpath

The
C l i e n t L o g i n S a m p l e is

a sample Java client that connects to the LDAP server through Pramati Server. The

client classpath is modified to point to sample classes and files, as well as the server classes required to run the Java client. The
C l i e n t L o g i n S a m p l e and

helper classes are packaged in

j a a s c l i e n t . j a r .

This must be placed in the client

classpath. The client requires the location of the Pramati Server and the realm to log in to. This information is stored in a file, login.cfg, which is packaged along with this tutorial. This file must be placed in the client classpath. Edit the
l o g i n . c f g file

to point to the server location and realm name. For example,

c o m . p r a m a t i . r e a l m = " r e a l m : / / 1 2 7 . 0 . 0 . 1 : 9 1 9 1 / l d a p "
The client also requires the following application server packages in its classpath:
j a a s . j a r

www.pramati.com/docstore/1270002/index.htm

7/8

j t a . j a r p r a m a t i _ c l i e n t . j a r s e c u r i t y _ i n t e r o p . j a r

Edit the file

j a a s t u t o r i a l . b a t to

point to the installation directory of Pramati Server. Run

j a a s t u t o r i a l . b a t from

the

command line to set the client classpath.

Running the sample

After setting the client classpath, run the
C l i e n t L o g i n S a m p l e program

by executing:

j a v aD j a v a . s e c u r i t y . a u t h . l o g i n . c o n f i g = < p a t ho fl o g i n . c f gf i l e > c o m . p r a m a t i . s e c u r i t y . s a m p l e s . C l i e n t L o g i n S a m p l e< u s e r n a m e >< p a s s w o r d >

Supply the username and password that has been configured on the LDAP server. The sample program will return the Role to which the User has been mapped. It then logs out the user from the realm. An error message is displayed if the username-password submitted is invalid.

Summary
The tutorial demonstrated the simplicity with which JAAS provides standards based pluggable security. We saw how a custom LoginModule is written and integrated with a typical standards compliant J2EE application server.
C opyright 2001-2002 Pram ati Te chnologie s. All of the m ate rial in this tutorial is copyright prote cte d and m ay not be publishe d in othe r work s without pe rm ission from Pram ati Te chnologie s. Java and all Java-base d m ark s are trade m ark s or re giste re d trade m ark s of Sun Microsyste m s, Inc. in the Unite d State s and othe r countrie s. All othe r trade nam e s and trade m ark s are the prope rty of the ir re spe ctive owne rs.

www.pramati.com/docstore/1270002/index.htm

8/8