Version 9.6
 —  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:

Note:
When you upgrade your existing installation and if you have created custom JAAS configuration, Software AG Installer creates an alternative JAAS configuration (jaas.config.new). The jaas.config.new configuration contains upgraded authentication mechanism and is not used for authentication. This way the existing JAAS configuration (jaas.config) remains intact and is used with the upgraded installation. To use the new authentication mechanism defined in the jaas.config.new file, you need to merge manually the content of the jaas.config.new file in the existing JAAS configuration (jaas.config). If you perform a fresh install or if the Installer does not discover an existing JAAS configuration in use on the system, it creates a default, upgraded JAAS configuration only. In this case the JAAS file name is jaas.config.

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.

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 following instructions:

Start of instruction setTo specify a JAAS configuration file in the console window

  1. Open a console window.

  2. Use a -Djava.security.auth.login.config interpreter console argument to specify the configuration file you want to use.

    For example, if you want to use a sample_jaas.config file in the current directory, and run the SampleLoginModule in that configuration file, enter the following:

    java -Djava.security.auth.login.config=sample_jaas.config sample.SampleLoginModule
    

Start of instruction setTo specify a JAAS configuration file in the Java security properties file

  1. On the local file system, navigate to: JAVA_HOME/jre/lib/security.

  2. Open the java.security file for editing.

  3. Locate the Default login configuration file section in the file.

  4. Enter the full path to the JAAS configuration file as the value of a login.config.url.<n> property. The number <n> starts from one and increases by one for each consecutive element. As a rule, the chain of login.config.url.<n> parameters must not be broken by missing element numbers; in other words, the numbers must start at 1 and be consecutive. Thus, you can specify more than one JAAS configuration file in the JRE. If you specify more than one configuration file, then the files are read and concatenated as a single configuration file.

    For example, if you want to use the sample_jaas.config file in the C:\MyLoginModule Directory on a Windows based OS, add the following line into the properties file:

    login.config.url.1=file:C:/MyLoginModule/sample_jaas.config
    

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