Sun Java System Access Manager 7 2005Q4 Developer's Guide

Chapter 5 Using Authentication APIs and SPIs

This chapter provides information on using Sun JavaTM System Access Manager 7 2005Q4 authentication programming interfaces to use and to extend the Authentication Service.

This chapter contains the following sections:

Overview of Authentication APIs and SPIs

Access Manager provides both Java APIs and C APIs for writing authentication clients that remote applications can use to gain access to the Authenticate Service. This communication between the APIs and the Authentication Service occurs by sending XML messages over HTTP(S). The remote-auth.dtd is the template used in formatting the XML request messages sent to Access Manager and for parsing the XML return messages received by the external application. You can access remote-auth.dtd in the directory AccessManager-base /SUNWam/dtd.

New authentication modules are added to Access Manager by using the com.iplanet.authentication.spi package. The SPI implements the JAAS LoginModule, and provides additional methods to access the Authentication Service and module configuration properties files. Because of this architecture, any custom JAAS authentication module will work within the Authentication Service.


Note –

If contacting the Authentication Service directly through its URL http://AcceessManager-HostName.domain_name:port /service_deploy_uri/authservice without the API, a detailed understanding of remote-auth.dtd will be needed for generating and interpreting the messages passed between the client and server.


How the Authentication Java APIs Work

External Java applications can authenticate users with the Access Manager Authentication Service by using the Authentication Java APIs. The APIs are organized in a package called com.sun.identity.authentication and can be executed locally or remotely. The classes and methods defined in this package are used to initiate the authentication process and communicate authentication credentials to the specific modules within the Authentication Service. The classes and methods can be incorporated into a Java application to allow communication with the Authentication Service.

The first step necessary for an external Java application to authenticate to Access Manager is to create a new AuthContext object (com.sun.identity.authentication.AuthContext). The AuthContext class is defined for each authentication request as it initiates the authentication process. Since Access Manager can handle multiple organizations, AuthContext is initialized, at the least, with the name of the organization to which the requestor is authenticating. Once an AuthContext object has been created, the login() method is called indicating to the server what method of authentication is desired.

IndexName is the value of the authentication type. The following table summarizes IndexName values and their corresponding authentication types.

Table 5–1 IndexName Values

IndexName Value

Authentication Type 

AuthContext.IndexType.ROLE

Role-based 

AuthContext.IndexType.SERVICE

Service-based 

AuthContext.IndexType.USER

User-based 

AuthContext.IndexType.LEVEL

Authentication Level-based 

AuthContext.IndexType.MODULE_INSTANCE

Module-based 

The getRequirements() method then calls the objects that will be populated by the user. Depending on the parameters passed with the instantiated AuthContext object and the two method calls, Access Manager responds to the client request with the correct login requirement screens. For example, if the requested user is authenticating to an organization configured for LDAP authentication only, the server will respond with the LDAP login requirement screen to supply a user name and a password. The client must then loop by calling the hasMoreRequirements() method until the required credentials have been entered. Once entered, the credentials are submitted back to the server with the method call submitRequirements() . The final step is for the client to make a getStatus() method call to determine if the authentication was successful. If successful, the caller obtains a session token for the user; if not, a LoginException is thrown.

Because the Authentication Service is built on the JAAS framework, the Authentication API can also invoke any authentication modules written purely with the JAAS API.

For detailed information about Java APIs for authentication, see the Javadoc in the following directory:

AccessManager-base/SUNWam/docs

XML/HTTP Interface for Other Applications

Applications written in a programming language other than Java or C can exchange authentication information with Access Manager using the XML/HTTP(s) interface. Using the URL http://server_name.domain_name :port/service_deploy_uri /authservice, an application can open a connection using the HTTP POST method and exchange XML messages with the Authentication Service. The structure of the XML messages is defined in remote-auth.dtd. In order to access the Authentication Service in this manner, the client application must contain the following:

Examples of XML Messages

The following code examples illustrate how customers might configure the XML messages posted to the Authentication Service.


Note –

Although the client application need only write XML based on the remote-auth.dtd, when these messages are sent they include additional XML code produced by the Authentication API. This additional XML code is not illustrated in the following examples.


The following example illustrates the initial XML message sent to the Access Manager. It opens a connection and asks for authentication requirements regarding the exampleorg organization to which the user will login.


Example 5–1 Initial AuthContext XML Message


<?xml version="1.0" encoding="UTF-8"?>
<AuthContext version="1.0">
<Request authIdentifier="0">
<NewAuthContext orgName="dc=exampleorg,dc=com">
</NewAuthContext>
</Request>
</AuthContext>


               

The following example illustrates the successful response from Access Manager that contains the authIdentifier, the session identifier for the initial request.


Example 5–2 AuthIdentifier XML Message Response


<?xml version="1.0" encoding="UTF-8"?>
<AuthContext version="1.0">
<Response authIdentifier="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1oVb5esqDlkaY=">
<LoginStatus status="in_progress">
</LoginStatus>
</Response>
</AuthContext>


               

The following example illustrates the client response message back to Access Manager. It specifies the type of authentication module needed by the user to log in.


Example 5–3 Second Request Message With Authentication Module Specified


<?xml version="1.0" encoding="UTF-8"?>
<AuthContext version="1.0">
<Request authIdentifier="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1oVb5esqDlkaY=">
<Login>
<IndexTypeNamePair indexType="moduleInstance">
<IndexName>LDAP</IndexName>
</IndexTypeNamePair>
</Login>
</Request>
</AuthContext>


               

The following example illustrates the return message from Access Manager which specifies the authentication module’s login requirements. In this case, the LDAP requirements include a user name and password. Note the page time out value of 120 seconds.


Example 5–4 Return XML Message With Login Callbacks


<?xml version="1.0" encoding="UTF-8"?>
<AuthContext version="1.0">
<Response authIdentifier="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1oVb5esqDlkaY=">

<GetRequirements>
<Callbacks length="3">
<PagePropertiesCallback isErrorState="false">
<ModuleName>LDAP</ModuleName>
<HeaderValue>This server uses LDAP Authentication</HeaderValue>
<ImageName></ImageName>
<PageTimeOut>120</PageTimeOut>
<TemplateName></TemplateName>
<PageState>1</PageState>
</PagePropertiesCallback>
<NameCallback>
<Prompt>User Name: </Prompt>
</NameCallback>

<PasswordCallback echoPassword="false">
<Prompt> Password: </Prompt>
</PasswordCallback>

</Callbacks>
</GetRequirements>
</Response>
</AuthContext>


               

The following example illustrates the client responses to the call for login requirements. They specify amadmin as the user and 11111111 for the password.


Example 5–5 Response Message With Callback Values


<?xml version="1.0" encoding="UTF-8"?>
<AuthContext version="1.0">
<Request authIdentifier="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1oVb5esqDlkaY=">
<SubmitRequirements>
<Callbacks length="3">

<NameCallback>
<Prompt>User Name:</Prompt>
<Value>amadmin</Value>
</NameCallback>

<PasswordCallback echoPassword="false">
<Prompt>Password:</Prompt>
<Value>11111111</Value>
</PasswordCallback>
</Callbacks>
</SubmitRequirements>
</Request>
</AuthContext>


               

The following example illustrates that a successful authentication has occurred. As the value of <Subject> uses the Java serialization, it can not be used by non-Java client applications. It’s value is retrieved by all applications from the session token.


Example 5–6 Successful Authentication XML Message


<?xml version="1.0" encoding="UTF-8"?>
<AuthContext version="1.0">
<Response authIdentifier="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1oVb5esqDlkaY=">
<LoginStatus status="success" ssoToken="AQIC5wM2LY4SfcwmVdbgTX+9WzyWSPlWjb1o
Vb5esqDlkaY=" successURL="http://torpedo.red.iplanet.com:/amconsole">
<Subject>AQICweczOhuelZ5TqD9kKOtiAepxqGP23q4oTnNMuJY//lI2S4KD1/gEN84uLwDGHll
lyFSthxoKLM7NDHh2vwAvrDmpsomJvUnbqnJJ90DS+28njGiDv+lv8FqIVhhbxrctbiIUEOHYK0F
zXnXjPYizdCmiWXJ+9DJ8T2HbYIDxn9U6eVNAMPq3uVb/RFuErEm5MuPu7PnWeCic12SZre4ZEcw
8TI45NKNjd/NZZD97bcqL5gEV7SVHspFldZKmo9vA86aEkvMs9P53RiJtrusHN1FKt9+4JqSrdcV
LKMzJVAr3z5EohwHh9/hzd7hgucO661gz7IqkT7WEpve/E8R4em0mg3HgHg7Bg7i3AkyX6YSkoAn
cdVXMdmWnb7OV5cBgUjO8zs8Pp5/3dA1XlwACmOqjxshk6Y6Ld6TAQ90qRFwymC1RdLGGCRnrt33
kmYVyB1lJyJxT8utPKyDOEKFRHh57NlKTbFhBKc1IGcdQ2crHifpXawx6YouQgQSWGdsqW9IahY4
+lqbBTPnGDyZkKz9yy2ZKVjDR05Hwku8elvEwBE40XTJ3gF/mbwCGbh3cyprahLqRXboy8eoEQf3
ubQmR2My+bh+NrsRfzfFV5oCcpJE6DtvYE/4zO+uKk3FbG+/NUJzAAor920V/0prtYeS58ZPW8C7
qwXINaW0xdMQV+pgE3NZvMlp5GeZlSIMmSCtXD49n4tqopSlsoK+eiwPODKxp992+6/uJhhVHH5I
0Ozuy6CDM dCJDGvnMENVCUZvki3+tb92fqQbVWixM4Ca6Nnz3jTIKk2uhm559jq9hra8gHHOfnn
u4e5jZjzfRdkO3GodiTMOHDnQATHtvT1PBXgorTfUwUa4ZjptvzFulHSi4eQaqs4Z8FAX2OAr8XG
HRkhBwoxrhjYiCDBpkNmpEiFNhWnTT3bwkAUFhtoDg6836kwHfxeLXKAz3T6qyNQzT+larSXUxrt
/TIjwDPR3vg4GF4RzbHlWA1WQtUS/9Qe/N3aegEEEvxPvo9fWq
</Subject>
</LoginStatus>
</Response>
</AuthContext>


               

How the Authentication SPIs Work

Access Manager provides the capability to plug new, Java-based authentication modules into its framework allowing proprietary authentication providers to be managed using the Access Manager console. A custom authentication module must first be created using Java. Once created, the custom module can be added to the list of available authentication modules.


Note –

This guide does not document the JAAS. For more information on these APIs, see the Java Authentication And Authorization Service Developer’s Guide. Additional information can be found at http://java.sun.com/products/jaas/.


Extending the AMLoginModule Class

Custom authentication modules extend the com.sun.identity.authentication.spi.AMLoginModule class. The class must also implement the init(), process() and getPrincipal() methods in order to communicate with the authentication module configuration files. The callbacks are then dynamically generated based on this file. Other methods that can be defined include setLoginFailureURL and setLoginSuccessURL which defines URLs to send the user to based on a failed or successful authentication, respectively.


Note –

To make use of the account locking feature with custom authentication modules, the InvalidPasswordException exception should be thrown when the password is invalid.


Pluggable JAAS Module

The Java Authentication and Authorization Service (JAAS) is a set of APIs that enable services to authenticate and enforce access controls upon users. It implements a Java technology version of the standard Pluggable Authentication Module (PAM) framework, and supports user-based authorization. Access Manager supports pure JAAS pluggable authentication modules. In Access Manager, pure JAAS modules extend the JAAS LoginModule rather than AMLoginModule. A pure JAAS module is plugged in to the Authentication framework using the Authentication API.

Authentication Post Processing

The Authentication SPI includes the AMPostAuthProcessInterface which can be implemented for post-processing tasks. The following are examples of post-processing tasks:

The Core Authentication Service contains the Authentication PostProcessing Class attribute which contains the authentication post-processing class name as its value. Custom post processing interfaces can also be implemented.

AMPostAuthProcessInterface can be implemented for post authentication processing on authentication success, failure and logout. The SPI is configurable at the organization , service and role levels. The Authentication Service invokes the post processing SPI methods on successful, failed authentication and logout.

The AMPostProcessInterface class has 3 methods:

Some supporting information on these methods is provided in the following sections. For a comprehensive listing and detailed information on all Access Manager methods, see the Javadoc installed in the following directory:

AccessManager-base/SUNWam/docs

onLoginSuccess

This method should be implemented for post-processing after a successful authentication. Authentication Service will invoke this method on successful authentication.

Method signature is:

 public void onLoginSuccess(Map requestParamsMap,
                               HttpServletRequest request,
                               HttpServletResponse response,
                               SSOToken ssoToken)
     throws AuthenticationException;

where

onLoginFailure

This method should be implemented for post processing after a failed authentication. Authentication Service will invoke this method on failed authentication.

Method signature is:

 public void onLoginFailure(Map requestParamsMap,
                             HttpServletRequest request,
                             HttpServletResponse response)
    throws AuthenticationException;

where

onLogout

This method should be implemented for post-processing on a logout request. Authentication Service will invoke this method on logout.

Method signature is:

 public void onLogout(HttpServletRequest request,
                       HttpServletResponse response,
                      SSOToken ssoToken)
    throws AuthenticationException;

where

Using Authentication APIs

Access Manager comes with a number of sample programs that demonstrate how you can use the Authentication APIs to extend the functionality of the authentication service and authentication modules.

Running the Sample Authentication Programs

The source code and Makefile are provided for all sample programs. For some sample programs, additional supporting files are also included. The instructions for compiling and executing the sample programs are the same for all samples described in this section.

Java API Code Samples and Their Locations

The following tables describe the locations of all the files you need to implement the sample programs on various platforms, and the variable names used for default directories in the source code and Makefiles. Table 5–2 summarizes file locations and variable names used for Solaris Sparc/x86.l Table 5–3 summarizes default directories for Linux. Table 5–4 summarizes default directories for Windows 2000.

Table 5–2 Default directories for Solaris Sparc/x86

Variable 

Description 

Location 

Api_sample_dir

Directory that contains authentication API sample files 

<install_root>/SUNWam/
	samples/authenitcation/api

Config_directory

Directory that contains configuration files 

/etc/opt/SUNWam/config

Product_Directory

Directory where Access Manager is installed. 

install_root>/SUNWam

Table 5–3 Default directories for Linux

Variable 

Description 

Location 

Api_Sample_Dir

Directory that contains authentication API sample files 

<install_root>/sun/
	identity/samples/authentication/api

Config_Directory

Directory that contains configuration files 

/etc/opt/sun/identity/config

Product_Directory

Directory where Access Manager is installed. 

<install_root>/sun/identity

Table 5–4 Default directories for Windows 2000

Variable 

Description 

Location 

Api_Sample_Dir

Directory that contains authentication API sample files 

<install_root>\samples\
	authentication\api

Config_Directory

Directory that contains configuration files 

<install_root>\lib

Product_Directory

Directory where Access Manager is installed. 

<install_root>

These steps are for all platforms.

ProcedureTo Compile and Execute the Java API Samples

  1. In the Makefile, modify the following variables as necessary to suit your Access Manager installation:

    BASE_DIR: Enter the path to the directory where Access Manager is installed.

    JAVA_HOME: Enter the path to the directory where the Java compiler is installed.

    DOMAIN: Enter the name of the organization to login to.

    SHARE_LIB: Enter the path to the directory where Access Manager jar files are stored.

    JSS_JAR_PATH: Enter the path to the directory where JSS jar files are stored.

    JSSPATH: Enter the path to the directory where JSS libraries are located.

  2. In the Certificate Sample Makefile only, modify the following as necessary:

    CERTNICKNAME: Enter the Certificate nickname.

    URL: Enter the Access Manger Server URL.

    PASSWORD: Enter the Certificate DB Password.

  3. Copy AMConfig.properties from Config_Directory in the Access Manager server installation to the client machine.

    (Note: For SSL check SSL Configuration Setup, step 2).

  4. In the Makefile, update the classpath to include the location of the newly created AMConfig.properties.

  5. In the client machine, create a directory named locale.

    C opy all the property files from the locale directory in the Access Manager server installation machine to the client machine. The locale directory on the server machine can be found under the Product_Directory.

  6. Update the classpath in the Makefile to include the location of newly created locale files.

  7. Include jaas.jar in your classpath if you are using a JDK version less than JDK1.4

  8. Compile the program.

    • On Solaris Sparc/x86, Linux, run the gmake command.

      • On Windows 2000, run the make command.

  9. Run the sample program.

    • On Solaris Sparc/x86 or Linux, run the following command: gmake run

      • On Windows 2000, run the following command: make run

ProcedureTo Configure SSL for Java API Samples

  1. In the Makefile, add this JVM property in the run target:

    -D "java.protocol.handler.pkgs=com.iplanet.services.comm"

  2. Copy AMConfig.properties from Config_Directory in the Access Manager server installation to the client machine.

  3. Edit the following properties in AMConfig.properties.

    com.iplanet.am.admin.cli.certdb.dir: Enter the path to the certificate database directory.

    com.iplanet.am.admin.cli.certdb.prefix: Enter the certificate database prefix.

  4. In the LDAP and JCDI Samples only:

    com.iplanet.am.server.protocol: Change the value to HTTPS.

    com.iplanet.am.server.port: Enter the appropriate port number from the server machine.

  5. Create or copy the certificate database file to the certificate db directory. Use the directory name in com.iplanet.am.admin.cli.certdb.dir.

  6. Rename the file to use the prefix specified in the property com.iplanet.am.admin.cli.certdb.prefix.

    For the details, see the Javadoc for the Remote Client API.

LDAPLogin Example

The LDAPLogin sample is an example of a custom Java application that uses the authentication remote APIs to authenticate to the LDAP module. You can modify the sample source code to authenticate to other existing or customized authentication modules. The sample source code, Makefile, and Readme.html are located in the following directory:

AccessManager-base/ SUNWam/samples/authentication/LDAP

To compile and run the sample program, follow the steps in To Compile and Execute the Java API Samples.

CertLogin Example

The CertLogin sample is an example of a custom Java application that uses digital certificates for authentication. You can modify the sample source code to authenticate to other existing or customized authentication modules. The sample source code, Makefile, and Readme.html are located in the following file:

AccessManager-base/ SUNWam/samples/authentication/Cert

ProcedureTo Run the CertLogin Program

  1. Enable SSL.

    Follow the instructions in To Configure SSL for Java API Samples.

  2. Compile and execute the sample code.

    See To Compile and Execute the Java API Samples

Using certutil for Client Certificate Management

Certutil is a command-line utility that can create and modify cert7.db and key3.db database files. It can also list, generate, modify, or delete certificates within the cert7.db file and create or change the password, generate new public and private key pairs, display the contents of the key database, or delete key pairs within the key3.db file. The key and certificate management process usually begins with creating keys in the key database, then generating and managing certificates in the certificate database.

JCDI Module Example

The JCDI Module Example demonstrates the use of Java Card Digital ID (JCDI) authentication with Access Manager. The sample has two components:

The remote client component is located in the following directory:

AccessManager-base/samples/authentication/api/jcdi

The server JCDI authentication module is located in the following directory:

AccessManager-basesamples/authentication/spi/jcdi

The sample illustrates JCDI authentication using the Remote Authentication API. You can modify the sample source code to authenticate to other existing or customized authentication modules. The source code, Makefile, and Readme.html are located in the following directory:

AccessManager-basesamples/authentication/api/jcdi

To compile and run the sample program, follow the steps in Running the Sample Authentication Programs.

Using Authentication SPIs

Access Manager provides the following sample programs to demonstrate how you can use the Authentication service programming interfaces (SPIs) to extend authentication functionality:

Implementing a Custom Authentication Module

Access Manager contains a sample exercise for integrating a custom authentication module with files that have already been created. This sample illustrates the steps for integrating an authentication module into the Access Manager deployment. All the files needed to compile, deploy and run the sample authentication module can be found in the following directory:

AccessManager-base/SUNWam/samples/authentication/providers

The following sections will use files from this sample as example code:

About the Login Module Sample

<PRODUCT_DIR> setting on different Platforms:

Solaris Sparc/x86: <PRODUCT_DIR> = base-directory/SUNWam

Linux: <PRODUCT_DIR> = base-directory/sun/identity

Windows 2000: <PRODUCT_DIR> = base-directory

Writing a Sample Login Module

Use the AMLoginModule SPI to write your own sample login module.

ProcedureTo Write a Sample Login Module

  1. Creating a Module Properties File.

  2. Writing the Principal Class.

  3. Implementing the LoginModule Interface.

    The following are the default directories used in the sample exercise for the various platforms:

    Solaris Sparc/x86: <PRODUCT_DIR> = base-directory/SUNWam

    Linux: <PRODUCT_DIR> = base-directory/sun/identity

    W2K: <PRODUCT_DIR> = base-directory

Creating a Module Properties File

Create a Module properties XML file with the same name of the class (no package name) and use the extension .xml. You must create an XML file with this naming convention even if no states required

Based on this configuration file, the Authentication user interface will dynamically generate a login page.

You can define page states in the module properties file as shown in Creating a Module Properties File. Each callback element corresponds to one login page state. When an authentication process is invoked, Callback[] values will be generated from the user’s Login Module for each state. All login state definitions start with 1. The module controls the login process, and then determines what the next state is.

Auth_Module_Properties.dtd defines the data structure that will be used by each authentication module to specify its properties. Auth_Module_Properties.dtd provides definitions to initiate, construct and send required callbacks information to the Authentication graphical user interface. Auth_Module_Properties.dtd is stored in the <PRODUCT_DIR>/dtd directory.


Example 5–7 Module Configuration Sample


<ModuleProperties moduleName="LoginModuleSample" version="1.0" >
         <Callbacks length="2" order="1" timeout="60" 
							header="This is a sample login page">
             <NameCallback>
             <Prompt> User Name </Prompt>
         </NameCallback>
         <NameCallback>
             <Prompt> Last Name </Prompt>
         </NameCallback>
         </Callbacks>
         <Callbacks length="1" order="2" timeout="60" 
							header="You made it to page 2" >
             <PasswordCallback echoPassword="false" >
             <Prompt> Just enter any password </Prompt>
             </PasswordCallback>
         </Callbacks>
    </ModuleProperties>
Module Configuration Sample
                  

In this module configuration sample, page state one has two callbacks. The first callback is for user ID, and second is for Last Name. When the user fills in the callbacks, the following events occur:

Writing the Principal Class

After creating module configuration XML file, the next step is to write a Sample Principal class which implements java.security.Principal. The constructor takes the user’s username as an argument. If authentication is successful, the module will return this principal to Authentication framework. The Authentication framework populates a Subject with a SamplePrincipal representing the user.

Implementing the LoginModule Interface

AMLoginModule is an abstract class which implements JAAS LoginModule. AMLoginModule provides methods for accessing Access Manager services and the module XML configuration. Login Module writers must subclass AMLoginModule class and implement the following methods:

For detailed descriptions, syntax, and parameters, see the Sun Java System Access Manager 7 2005Q4 Java API Reference. The following sections provide some supporting information about these methods.

init() This is an abstract method, Module writer should implement to initialize this LoginModule with the relevant information. If this LoginModule does not understand any of the data stored in sharedState or options parameters, the data can be ignored. This method is called by a AMLoginModule after thisSampleLoginModule has been instantiated, and prior to any calls to its other public methods. The method implementation should store away the provided arguments for future use. The init method may additionally peruse the provided sharedState to determine what additional authentication state it was provided by other LoginModules, and may also traverse through the provided options to determine what configuration options were specified to affect the LoginModule’s behavior. It may save option values in variables for future use.

process() The process method is called to authenticate a Subject. This method implementation should perform the actual authentication. For example, it may cause prompting for a user name and password, and then attempt to verify the password against a password database. If your LoginModule requires some form of user interaction (retrieving a user name and password, for example), it should not do so directly. That is because there are various ways of communicating with a user, and it is desirable for LoginModules to remain independent of the different types of user interaction. Rather, the LoginModule’s process method should invoke the handle method of the CallbackHandler passed to this method to perform the user interaction and set appropriate results, such as the user name and password and the AMLoginModule internally passes the GUI an array of appropriate Callbacks, for example a NameCallback for the user name and a PasswordCallback for the password, and the GUI performs the requested user interaction and sets appropriate values in the Callbacks.

Consider the following points while writing the process() method:

getPrincipal() This method should be called once at the end of a successful authentication session. A login session is deemed successful when all pages in the Module properties XML file have been sent and the module has not thrown an exception. The method retrieves the authenticated token string that the authenticated user will be known by in the Access Manager environment.


Note –

If the custom authentication module requires or already uses a service configuration XML file:


Compiling and Deploying the LoginModule program

If you are writing your own Custom Authentication module based on the AMLoginModule SPI or a pure JAAS module, then you can skip this step. Otherwise, after writing the sample Login Module, compile and deploy the sample found under AccessManager-base/samples/authentication/spi/providers.

ProcedureTo compile the Login Module

  1. Set the following environment variables.

    These variables will be used to run the gmake command. You can also set these variables in the Makefile. This Makefile is in the following directory: AccessManager-base /samples/authentication/spi/providers.

    JAVA_HOME: Set this variable to your installation of JDK. The JDK should be version 1.3.1_06 or higher.

    CLASSPATH: Set this variable to refer to am_services.jar which can be found in the Idetnity_base/lib directory. Include jaas.jar in your classpath if you are using JDK version less than JDK1.4

    BASE_DIR: Set this variable to the directory where the Access Manager is installed.

    BASE_CLASS_DIR: Set this variable to the directory where all the Sample compiled classes are located.

    JAR_DIR: Set this variable to the directory where the JAR files of the Sample compiled classes will be created.

  2. In the AccessManager-base/samples/authentication/spi/providers directory, run gmake.

ProcedureTo Deploy the Login Module Sample Program

  1. Copy LoginModuleSample.jar from JAR_DIR to AccessManager-base/web-src/services/WEB-INF/lib .

  2. Copy LoginModuleSample.xml from AccessManager-base /samples/authentication/spi/providers to AccessManager-base /web-src/services/config/auth/default .

  3. Redeploy the amserver.war file.

ProcedureTo Redeploy the amserver.war File

  1. In AccessManager-base/bin/amsamplesilent, set Deploy Level variable as follows:

    DEPLOY_LEVEL=21

  2. In AccessManager-base/bin/amsamplesilent, set container-related environment variables.

    • On Sun Java System Web Server 6.1, where /amserver is the default DEPLOY_URI:

      SERVER_HOST=WebServer-hostName
      SERVER_PORT=WebServer-portNumber
      SERVER_PROTOCOL=[http | https]
      SERVER_DEPLOY_URI=/amserver
      WEB_CONTAINER=WS6
      WS61_INSTANCE=https-$SERVER_HOST
      WS61_HOME= WebServer-base-directory
      WS61_PROTOCOL=$SERVER_PROTOCOL
      WS61_HOST=$SERVER_HOST
      WS61_PORT=$SERVER_PORT
      WS61_ADMINPORT=WebServer-adminPortWS61_ADMIN=WebServer-adminUserName
      
    • On Sun Java System Application Server 7.0, where /amserver is the default DEPLOY_URI:

      SERVER_HOST=ApplicationServer-hostName
      SERVER_PORT=ApplicationServer-portNumber
      SERVER_PROTOCOL=[http | https]
      SERVER_DEPLOY_URI=/amserver
      WEB_CONTAINER=AS7
      AS70_HOME=/opt/SUNWappserver7
      AS70_PROTOCOL=$SERVER_PROTOCOL
      AS70_HOST=$SERVER_HOST
      AS70_PORT=$SERVER_PORT
      AS70_ADMINPORT=4848
      AS70_ADMIN=admin
      AS70_ADMINPASSWD=ApplicationServer-adminPassword
      AS70_INSTANCE=server1
      AS70_DOMAIN=domain1
      AS70_INSTANCE_DIR=/var/opt/SUNWappserver7/domains/
        ${AS70_DOMAIN:-domain1}/${AS70_INSTANCE:-server1}
      AS70_DOCS_DIR=/var/opt/SUNWappserver7/domains/${AS70_DOMAIN:-domain1}/
        ${AS70_INSTANCE:-server1}/docroot
      #If Application Server is SSL Enabled then set the following:
      #AS70_IS_SECURE=true
      #SSL_PASSWORD=SSLpassword
      
    • On other supported platforms:

      Set platform-specific variables as is appropriate for the container.

  3. Redeploy the services web application by running the following command:

    AccessManager-base/bin/amconfig -s
      AccessManager-base/bin/amsamplesilent
    
  4. Restart the container instance.

    • Web Server example:

      /WebServer-base-directory/
        https-WebServer-instanceName/restart
      
    • Application Server example:

      /var/opt/SUNWappserver7/domains/${AS70_DOMAIN:-domain1}/
        ${AS70_INSTANCE:-server1}/bin/restartserv
      

Loading the Login Module Sample into Access Manager

Once you’ve compiled and deployed the login module, you must load the login module into Access Manager. You can load the login module by using either the Access Manager administration console, or by using the amadmin command.

ProcedureTo Load the Login Module Using the Administration Console

  1. Login to Access Manager Console as amadmin, using the URL:

    http://host.domain:port/Console-Deploy-URL

  2. Click Configuration.

  3. In the Configuration tab, under Authentication, click Core.

  4. Add class file name com.iplanet.am.samples.authentication.spi.providers. LoginModuleSample to the Pluggable Authentication Modules Classes list.

  5. Click Save.

ProcedureTo Load the Login Module Using the Command Line

  1. Write a sample XML file as shown in To Load the Login Module Using the Command Line, which will add the LoginModuleSample authentication module entry into the allowed modules and an authenticators list.


              <!--
                    Copyright (c) 2003 Sun Microsystems, Inc. 
    						 All rights reserved
                   Use is subject to license terms.
              -->
    
               <!DOCTYPE Requests
                    PUBLIC "-//iPlanet//iDSAME 5.0 Admin CLI DTD//EN"
                   "jar://com/iplanet/am/admin/cli/amAdmin.dtd"
               >
    
              <Requests>
    
                  <SchemaRequests serviceName="iPlanetAMAuthService"
    								SchemaType="Global">
                    <AddDefaultValues>
                     <AttributeValuePair>
                        <Attribute name="iplanet-am-auth-authenticators"/>
    
               <Value>com.iplanet.am.samples.authentication.spi.providers.
    								LoginModuleSample</Value>
                      </AttributeValuePair>
                    </AddDefaultValues>
    
                  </SchemaRequests>
              </Requests>
    
                         
  2. Use amadmin to load sample.xml:

    <AMADMIN> --runasdn uid=amAdmin,ou=People,<root_suffix> --password <password> --data sample.xml

    Solaris Sparc/x86: AMADMIN = <PRODUCT_DIR>/bin/amadmin

    On W2K: AMADMIN = <PRODUCT_DIR>\\bin\\amadmin

Running the LoginModule Sample Program

This sections provides instructions for running the login module on Solaris and on Windows platforms.

ProcedureTo Run the LoginModule on Solaris

  1. Use the following URL to log in to Access Manager console as amAdmin:

    http://host.domain:port/Console-Deploy-URI

  2. Click Identity Management, and in the Identity Management view select your organization.

  3. From the View menu, select Services.

  4. In the navigation frame, under Authentication, click Core.

  5. SelectLoginModuleSample to add it to the list of highlighted modules in Organization Authentication Modules.

    Make sure LDAP module is also selected. If not selected, you will not be able to login to Access Manager Console. You can use Control + mouse click to add additional modules.

  6. Click Save.

  7. Log out.

  8. Enter the following URL:

    http://host.domain:port/Service-Deploy-URI/UI/Login?module=LoginModuleSample

    If you choose to use an organization other than the default, be sure to specify that in the URL using the org parameter.

ProcedureTo Run the Login Module on Windows 2000

  1. Set the following environment variables. These variables will be used to run the make command. You can also set these variables in the Makefile.

    This Makefile is in the same directory as the Login Module Sample program files: AccessManager-base\samples\authentication\spi\providers

    JAVA_HOME: Set this variable to your installation of JDK. The JDK should be version 1.3.1_06 or higher.

    BASE: Set this variable to base-directory

    CLASSPATH: Set this variable to refer to am_services.jar which can be found in the base-directory\lib directory. Include jaas.jar in your classpath if you are using JDK version less than JDK1.4

    BASE_CLASS_DIR: Set this variable to the directory where all the Sample compiled classes are located.

    JAR_DIR: Set this variable to the directory where the JAR files of the Sample compiled classes will be created.

  2. In the base-directory\samples\authentication\spi\providers directory, run the make command.

ProcedureTo Deploy the Login Module

  1. Copy LoginModuleSample.jar from JAR_DIR to AccessManager-base\web-src\services\WEB-INF\lib

  2. In the Web Container from which this sample has to run, update the classpath with LoginModuleSample.jar.

  3. Update server.xml with the new classpath and server.xml locations:

    • Sun Java System Web Server : <WS-install-dir>\https-<WS-instance-name>\config\server.xml

    • Sun Java System Application Server: <AS-install-dir>\domain<appserver domain><appserver_instance>\config\server.xml

      Example:<AS-install-dir>\domain\domain1\server1\config\server.xml

  4. Copy LoginModuleSample.xml from base-directory \samples\authentication\spi\providers to base-directory\web-src\services\config\auth\default.

  5. Restart the web container

    Web Server: <WS-home-dir>\https-<WS-instance-name>\restart

    Application Server: AppServer-home-dir>\domains\<domain name><server_instance>\bin\restartserv

Implementing Authentication PostProcessing SPI

The Authentication SPI includes the AMPostAuthProcessInterface which can be implemented for post-processing tasks. The AMPostProcessInterface Javadoc are available at:

AccessManager-base/SUNWam/docs/com/sun/identity/authentication/spi/ AMPostAuthProcessInterface.html

The SPI is configurable at the organization, service and role levels. The Authentication Service invokes the post processing SPI methods on successful or failed authentication and on logout.

About the PostProcessing SPI Sample

<PRODUCT_DIR> or AccessManager-base directory on different Platforms:

ProcedureTo Compile the ISAuthPostProcessSample Program on Solaris Sparc/x86 or Linux

Follow these steps given below to compile the sample found under AccessManager-base/samples/authentication/spi/postprocess.

  1. Set the following environment variables.

    JAVA_HOME: Set this variable to your installation of JDK. The JDK should be version 1.3.1_06 or higher.

    CLASSPATH: Set this variable to refer to am_services.jar which can be found in the AccessManager-base/lib directory. Include jaas.jar in your classpath if you are using JDK version lower than JDK1.4

    BASE_DIR: Set this variable to the directory where Access Manager is installed.

    BASE_CLASS_DIR: Set this variable to the directory where all the Sample compiled classes are located.

    JAR_DIR: Set this variable to the directory where the JAR files of the Sample compiled classes will be created.

    These variables will be used to run the gmake command. You can also set these variables in the Makefile. This Makefile is in the following directory: AccessManager-base/samples/authentication/spi/postprocess.

  2. In the directory AccessManager-base /samples/authentication/spi/postprocess, run the gmake command.

ProcedureTo Deploy the ISAuthPostProcess Sample Program

  1. Copy ISAuthPostProcess.jar from JAR_DIR to AccessManager-base/lib.

  2. Update the Web Container configuration file server.xml.

    Add ISAuthPostProcessSample.jar to the classpath. The server.xml file for different web containers can be found at the following locations:

    Web Server: <WS-home-dir>/https-<WS-instance-name>/config/

    Application Server:<AS-home-dir>/domain/domain1/server1/config/

    For all other web containers consult, the manufacturer’s documentation.

  3. Restart the web container.

    Web Server: <WS-home-dir>/https-<WS-instance-name>/restart

    Application Server: <AS-install-dir>/<domains>/<domain name>/<server instance>/bin/restartserv Example: /<AS-home-dir>/domains/domain1/server1/bin/restartserv

    For all other web containers consult their documentation.

Configuring the Authentication Post Processing SPI

The Authentication PostProcessing Sample can be configured at the Organization, Service or Role level.

ProcedureTo Configure ISAuthPostProcess Sample for an Organization

  1. Log in to Access Manager console as amAdmin. Use the following URL:

    http://host.domain:port/Console-Deploy-URI

  2. Click Identity Management, and select your organization.

  3. From the View menu, click Services.

  4. In the navigation frame, under Authentication, click Core.

  5. Add the following to the Authentication PostProcessing Class attribute:

    com.iplanet.am.samples.authentication.spi.postprocess

  6. Add the following to the Authentication PostProcessing Class attribute:

    ISAuthPostProcessSample

  7. Click Save.

  8. Log out.

  9. Go to the following URL

    If you choose to use an organization other than the default, be sure to specify that in the URL using the org parameter.

    The postprocessing SPI will be executed on successful authentication, on failed authentication, and on Logout.

ProcedureTo Configure the ISAuthPostProcess Sample for a Service

  1. Log in to Access Manager console as amAdmin. Use the following URL:

    http://<host>.<domain>:<port>/<Console-Deploy-URI>

  2. Click Identity Management, and select your organization.

  3. From the View menu, select Services.

  4. Select Authentication Configuration

  5. From the Service Instance frame, select New Instance.

  6. Enter a name for the service.

  7. Add the following to the Authentication PostProcessing Class attribute: com.iplanet.am.samples.authentication.spi.postprocess. ISAuthPostProcessSampl

  8. Click Submit to save the changes.

  9. Click Service Name and define the Authentication Configuration for the new service.

  10. Log out.

  11. Go to the following URL: http://host.domain:port/Service-Deploy-URI/UI/Login?service=servicename

    If you choose to use an organization other than the default, be sure to specify that in the URL using the org parameter.

    The postprocessing SPI will get executed on successful authentication, failed authentication and on Logout for the service accessed.

ProcedureTo Configure ISAuthPostProcess Sample for a Role

  1. Log in to Access Manager console as amAdmin. Use the following URL:

    http://host.domain:port/Console-Deploy-URI

  2. Click the Identity Management tab, and select your organization.

  3. From the View menu, select Roles to view the role properties.

  4. From the View menu, select Services.

  5. Click Edit to edit the authentication configuration.

  6. Add the following to the Authentication post Processing Class attribute:

    com.iplanet.am.samples.authentication.spi.postprocess. ISAuthPostProcessSample

  7. Click Submit to save the changes.

  8. Log out.

  9. Go to the following URL:

    http://host.domain:port/Service-Deploy-URI/UI/Login?role=roleName

    If you choose to use an organization other than the default, be sure to specify that in the URL using the org parameter. Example: org=orgName

    The postprocessing SPI will be executed for the service accessed on successful authentication, on failed authentication, and on Logout.

Compiling On Windows 2000

Go to the base-directory\samples\authentication\spi\postprocess directory and run the make command.

ProcedureTo Deploy the ISAuthPostProcessSample Program

  1. Copy ISAuthPostProcess.jar from JAR_DIR to base-directory\lib

  2. In the Web Container from which this sample has to run, update the classpath with ISAuthPostProcess.jar.

  3. Restart Access Manager.

    base-directory\bin\amserver start

To Configure Authentication Post Processing SPI

This sample can be can be set in the Core Authentication Service for Organization and Authentication Configuration Service for Role OR Service.

See the section Configuring the Authentication Post Processing SPI.

Generating an Authentication User ID

This file explains how to compile, deploy and configure the Authentication User ID Generation SPI Sample.

In the following sections, the PRODUCT_DIR setting depends on which platform you’re using:

Solaris Sparc/x86: PRODUCT_DIR = <install_root>/SUNWam

Linux: PRODUCT_DIR = <install_root>/sun/identity

ProcedureTo Compile the UserIDGeneratorSample on Solaris Sparc/x86, Linux

The sample is located in the following directory:

AccessManager-base/samples/authentication/spi/genuid

  1. Set the following environment variables.

    These variables will be used to run the gmake command. You can also set these variables in the Makefile which is located in the following directory:

    AccessManager-base/samples/authentication/spi/genuid

    JAVA_HOME: Set this variable to your installation of JDK. The JDK should be version 1.3.1_06 or higher.

    CLASSPATH: Set this variable to refer to am_services.jar which can be found in the <PRODUCT_DIR>/lib directory. Include jaas.jar in your classpath if you are using JDK version less than JDK1.4.

    BASE_DIR: Set this variable to the directory where the Access Manager is installed.

    BASE_CLASS_DIR: Set this variable to the directory where all the Sample compiled classes are located.

    JAR_DIR: Set this variable to the directory where the JAR files of the Sample compiled classes will be created.

  2. In the directory AccessManager-base /samples/authentication/spi/genuid, run the gmake command:

ProcedureTo Deploy the UserIDGeneratorSample Program

  1. Copy UserIDGeneratorSample.jar from JAR_DIR to AccessManager-base/lib.

  2. in the Web Container from which this sample has to run, update the classpath with UserIDGeneratorSample.jar.

    • On Sun ONE Web Server, go to server instance configurationdirectory:

      <WS-home-dir>/https-<WS-instance-name>/config/

    • On Sun ONE Application Server, in the directory <AS-home-dir>/domain/domain1/server1/config/ update server.xml with the new classpath.

    • For all other containers, consult the documentation that came with the product.

  3. Restart web container.<WS-home-dir>/https-<WS-instance-name>/start

    <AS-home-dir>/domains/domain1/server1/bin/start

Configuring the UserIDGeneratorSample Program

The Authentication User ID Generation Sample can be configured at the Organization level, and then used or invoked by the out-of-box Membership/Self- registration authentication module.

ProcedureTo Configure UserIDGeneratorSample for an Organization

  1. Log in to Access Manager console as amAdmin. Use the following URL:

    http://host.domain:port/Console-Deploy-URI

  2. Click the Identity Management tab, and select your organization.

  3. From the View menu, select Services.

  4. In the navigation frame, under Authentication, click Core.

  5. Add the following to the Pluggable User Name Generator Class attribute: com.iplanet.am.samples.authentication.spi.genuid. UserIDGeneratorSample

  6. Click Save to save the changes.

  7. Log out.

ProcedureTo Access an Authentication Module for an Organization

This module is the one which invokes the UserIDGenerator SPI implementation class. By default, only the Membership/Self-registration authentication module calls this SPI implementation.

  1. Make sure that you have registered and enabled the Membership authentication module, and that you have created a template for the organization.

  2. Enter the following URL:

    http://host.domain:port/Service-Deploy-URI/UI/Login?module=Membership

    If you choose to use an organization other than the default, be sure to specify that in the URL using the org parameter. Example: org=orgName

  3. Click New User.

    You should be able to register any existing username or user ID.

    The UserIDGeneratorSample will be executed. You will be presented with the generated User IDs choice menu to choose any one username or user ID.

Compiling the UserIDGeneratorSample Program on Windows 2000

In the <install-root>\samples\authentication\spi\genuid directory, run the make command.

ProcedureTo deploy the UserIDGeneratorSample Program

  1. Copy UserIDGeneratorSample.jar from JAR_DIR to <install-root>\\lib

  2. In the Web Container from which this sample has to run, update the classpath with UserIDGeneratorSample.jar.

  3. Restart Access Manager.

    <install-root>\bin\amserver start

To Configure the UserIDGeneratorSample Program

Configuring the program on Windows 2000 is similar to configuring the program on Solaris. See Configuring the Authentication Post Processing SPI.

Implementing A Pure JAAS Module

A sample program demonstrates how to write pure a JAAS module to replay callbacks by authenticating using Access Manager Authentication Client API. It will authenticate a user by replaying the callbacks required by Access Manager the Authentication Module. You can modify this program to use other existing or customized Access Manager Authentication modules. This sample module can be plugged in into any standard JAAS framework using the JAAS API.


Note –

For detailed information on JAAS, see the Sun Developer Documentation at the following URL:http://java.sun.com/products/jaas/. For detailed information on how to write a JAAS module, see the JAAS LoginModule Developer’s Guide at the following URL:

http://java.sun.com/j2se/1.4.2/docs/guide/security/
				jaas/JAASLMDevGuide.html

Conventions Used in the Samples

Table 5–5 Default directories for Solaris Sparc/x86

Variable 

Description 

Location 

Config_directory

Directory that contains configuration files 

/CONFIG_DIR = /etc/opt/SUNWam/config

Product_Directory

Directory where Access Manager is installed. 

PRODUCT_DIR = <install_root>/SUNWam

Table 5–6 Default directories for Linux

Variable 

Description 

Location 

Config_Directory

Directory that contains configuration files 

CONFIG_DIR = /etc/opt/sun/identity/config

Product_Directory

Directory where Access Manager is installed. 

PRODUCT_DIR = <install_root>/sun/identity

Table 5–7 Default directories for Windows 2000

Variable 

Description 

Location 

Config_Directory

Directory that contains configuration files 

CONFIG_DIR = <install_root>\lib

Product_Directory

Directory where Access Manager is installed. 

 

ProcedureTo Run the Sample on Solaris Sparc x86 or Linux:

  1. In the Makefile, set the following variables:

    BASE: Enter the path to the directory where Access manager is installed.

    JAVA_HOME: Enter the path to the directory where Java compiler is installed

    CONFIG: Enter the entry specified in the login configuration file. This entry will be used to do the user authentication

  2. Copy AMConfig.properties from Access Manager server installation machine location <CONFIG_DIR> to the client machine where the sample will be run.

  3. On the client machine, be sure the following are in your classpath:

    • am_services.jar

    • jaas.jar

    • jss3.jar

    • AMConfig.properties

      Include jaas.jar in your classpath if you are using a JDK version less than JDK1.4

  4. A sample configuration file purejaassample.config is provided for testing this sample.

    The file contains only one entry named Sample. Sample is the name to be entered for CONFIG in the Makefile:


    Sample {
     PureJAASSampleLoginModule required ORG_NAME="dc=iplanet,dc=com"
    			INDEX_NAME="LDAP" debug=true;
     };                     

    The entry specifies that the LoginModule to be used to do the user authentication is the PureJAASSampleLoginModule and that this SampleLoginModule must succeed in order for authentication to be considered successful. It passes options with ORG_NAME as the organization name and INDEX_NAME as the Access Manager authentication module to which this sample must authenticate.

    If you must use a different login configuration, modify the Makefile. For example, change the following:

    -Djava.security.auth.login.config=purejaassample.config

    to this:

    -Djava.security.auth.login.config=your_jaas_config_file.config
    
  5. To compile, run the gmake command.

  6. To run the sample program run the gmake run command.

ProcedureTo Enable SSL

  1. In the sample client program, add this JVM property:

    -D "java.protocol.handler.pkgs=com.iplanet.services.comm"

  2. In the AMConfig.properties file, edit the following properties:

    com.iplanet.am.admin.cli.certdb.dir: <PRODUCT_DIR>/servers/alias

    com.iplanet.am.admin.cli.certdb.prefix: https-machine1.com-machine1-

    com.iplanet.am.server.protocol: https

    com.iplanet.am.server.port: Enter the appropriate port on the server machine where machine1 is the host name of the server

ProcedureTo Run the Sample on Windows 2000

  1. In make.bat, set the following properties:

    BASE: Enter the path to the directory where Access manager is installed

    JAVA_HOME: Enter the path to the directory where the Java compiler is installed.

    CONFIG: Enter the entry which will be used for user authentication. This entry is specified in the login configuration file.

  2. Copy AMConfig.properties from Access Manager server installation machine location <CONFIG_DIR> to the client machine where this sample will be run.

  3. On the client machine, make sure the following are in your classpath:

    • am_services.jar

    • jaas.jar

    • jss3.jar

    • AMConfig.properties

      Include jaas.jar in your classpath if you are using JDK version less than JDK1.4.

  4. A sample configuration file purejaassample.config is provided for testing this sample.

    The file contains only one entry named.Sample. Sample is the name to be entered for CONFIG in the Makefile.


    Sample {
     PureJAASSampleLoginModule required ORG_NAME="dc=iplanet,dc=com"
    			INDEX_NAME="LDAP" debug=true;
     };                     

    The entry specifies that the LoginModule to be used to do the user authentication is the PureJAASSampleLoginModule. SampleLoginModule is must succeed in order for authentication to be considered successful. It passes options with ORG_NAME as the organization name and INDEX_NAME as the Access Manager authentication module to which this sample has to authenticate.

    If you must use a different login configuration, modify the Makefile. For example, change the following:

    -Djava.security.auth.login.config=purejaassample.config

    to this:

    -Djava.security.auth.login.config=your_jaas_config_file.config
    
  5. To compile, run the make command.

  6. To run the sample program, run the make run command.

ProcedureTo Enable SSL

  1. In the sample client program, add this JVM property:

    -D "java.protocol.handler.pkgs=com.iplanet.services.comm"

  2. Edit the following properties in the AMConfig.properties file:

    com.iplanet.am.admin.cli.certdb.dir: <install-dir>\SUN\IdentityServer6\Servers\alias

    com.iplanet.am.admin.cli.certdb.prefix:https-machine1.red.iplanet.com-machine1-

    com.iplanet.am.server.protocol: https

    com.iplanet.am.server.port: Enter the appropriate port on the server machine where machine1 is the host name of the server

    For the detailed information, see the Javadoc for Remote Client APIs. By default, Access Manager Javadoc is installed in the following directory:

    AccessManager-base/SUNWam/docs

    For the detailed information on how to plug the Login Module into the standard JAAS Context, see the JAAS Reference Guide at the following URL:

    http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/JAASRefGuide.html