Version 9.8
 —  LoginModules Guide  —

Preparing JAAS Configuration Files

You use JAAS configuration files to manage authentication against multiple components and products of the webMethods Product Suite. JAAS configuration files allow you to define a uniform and flexible mechanism of authentication. They have commonly structured components which you can easily configure in order to authenticate successfully against multiple products, applications, or processes. The JAAS configuration comprises one or more than one login modules, which are grouped in a login context. The login modules define the actual authentication mechanism, and allow you to easily manipulate the overall authentication by configuring the behavior of a particular login module. A login context that is part of the JAAS configuration file controls and invokes the login modules in a pre-configured order. Every login context is a different login mechanism and it is up to the product to choose which one to use according to complete the use case.

Software AG Security Infrastructure comprises a set of pre-defined login modules which enable you to authenticate within the products of the webMethods Product Suite. Security Infrastructure login modules are reusable entities, which you can easily organize and configure in a uniform login context of a JAAS configuration file. Thus, you can define simply the rules of authentication of a particular business scenario, in the means of correct configuration of its JAAS file. The JAAS configuration files comprise the following components:

The following tasks describe how you can organize and configure the components of a JAAS configuration file in a uniform way and authenticate against the products.


Creating Login Contexts

A login context is a grouping of login modules in a JAAS configuration file. It provides the basic methods for user authentication. The stack of login modules allows you to configure applications or products to use more than one login module. The JAAS framework allows for a very flexible handling of stacks of login modules. When authenticating, the calling program instantiates directly the login modules that are grouped in the login contexts.

The sample excerpt below outlines a login context that contains the following predefined login modules that are provided by Security Infrastructure (X509CertificateLoginModule, SSXLoginModule, and CentraSiteServerLoginModule). The login modules are specified in the login context with their full class name (for example, com.softwareag.security.jaas.login.modules.X509CertificateLoginModule). The classification of the login modules is defined by flags (the flags used in the sample below are required, requisite, optional). The flags are specified after the login modules names. At the end of each login module definition are placed the parameters that control the behavior of the module. In the example below, the X509CertificateLoginModule has six parameters, while the other two modules have only one parameter respectively. All login modules are separated in the login context by semi-colons (;). Semi-colons separate the login contexts as well.

SoftwareAGSampleLoginContext 
{
    com.softwareag.security.jaas.login.modules.X509CertificateLoginModule required 
        check_crl_status=true 
        crl_url="${com.softwareag.security.crl.url}" 
        truststore_url="${com.softwareag.security.truststore.url}" 
        truststore_password="${com.softwareag.security.truststore.password}" 
        truststore_type=jks
        overwrite_username=false; 

    com.softwareag.security.jaas.login.ssx.SSXLoginModule requisite 
        template_section=OS; 

    com.softwareag.security.jaas.login.xmlserver.CentraSiteServerLoginModule optional 
        XMLSERVER_URL="http://localhost:53305/CentraSite/CentraSite";
};

To succeed the overall login process, the login modules have to succeed depending on the classification that is set to them.

Top of page

Defining Login Modules

The process of authentication includes the successful calling of a login module. Login modules can prompt for and verify a user name and a password, a client certificate, or enquire for user details from a user repository. The JAAS configuration specifies the login module that is to be used with a particular product or application. You can define a set of login modules within the JAAS configuration file. Moreover, you can configure the specific behavior of the login modules depending on the application requirements. You include the login modules in the login context using their full class name. The following samples outline the correct login modules entries.

com.softwareag.security.jaas.login.modules.X509CertificateLoginModule
com.softwareag.security.jaas.login.ssx.SSXLoginModule
com.softwareag.security.jaas.login.xmlserver.CentraSiteServerLoginModule

Start of instruction setTo use the standard JAAS login modules with Software AG Runtime

  1. Open the <SoftwareAG_directory>/profiles/CTP/configuration/config.ini file.

  2. Change the value of the com.softwareag.platform.jaas.enabled parameter from "true" to "false".

  3. Restart Software AG Runtime.

Top of page

Configuring the Classification of Login Modules

JAAS specification classifies the login modules depending on their status towards the successful authentication. Depending on the particular classification of the login module, you can configure it to take a significant role in the overall authentication process, or leave it as an optional element to the overall success. The following classifications of login modules are available:

Top of page

Configuring the Parameters of Login Modules

The behavior of a specific login module that is included into the context list depends on the parameters that are set to it and used during the authentication process. JAAS configuration files allow you to modify, in the means of functionality, the behavior of the used login modules. To configure a login module, you can list a set of parameters that are available for the particular login module, and provide values to them, which are essential to the authentication. You define the parameters of a login module in the login context, after the classification information. You can add more than one parameter and you separate the parameters using a space or a new line.

You can also add the domain parameter in your login modules. This parameter enables a dynamic use of login modules. To activate the domain usage, you must add the domain parameter to the jaas.config file for the particular login module. When the user logs in providing a domain and user name, the login modules in the jaas.config file verify the provided domain value and begin the authentication process for the user only if the provided domain value corresponds to the one defined for the specific login module. This behavior makes it possible for many consumers to share the same configuration by dynamically modifying the authentication logic in each use case.

Note:
The domain usage is implemented for the InternalLoginModule and the LDAPLoginModule.

The full property list of the Security Infrastructure login modules that are provided by Software AG is available in the Predefined Login Modules section.

The JAAS configuration file now supports location tokens (@path and @url). For more information about path token support, see the Working with Software AG Runtime documentation.

Top of page

Specifying JAAS Configuration Files in Java Runtime

To use the created JAAS configuration file, you must point it to the installed Java Runtime Environment. You can specify the file in the JRE using the instructions below.

Specifying a JAAS configuration file must be done in the profile's config.ini file.

Start of instruction setTo specify a JAAS configuration file in the config.ini file

  1. Navigate to the config.ini file in the profile <install-dir>/profiles/<profile>/config.ini

  2. Open the file with a text editor.

  3. Change the value of the java.security.auth.login.config property to point to a valid JAAS configuration file location.

    For example, java.security.auth.login.config=@url\:osgi.configuration.area/jaas.config.

  4. Save your changes and close the config.ini file.

Note:
Only the content of the JAAS configuration file under: <install-dir>/profiles/<profile>/configuration/jaas.config will be migrated in future releases. You can still use a JAAS configuration file in a different location but you will have to migrate the file manually.

Top of page

Next Steps

If authentication is successful, JAAS creates a subject that contains one or more principals with security related attributes like passwords and cryptographic keys.

Top of page