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:
Login Context
Login Modules
Classification of Login Modules
Configuration Properties of Login Modules
Comments within the JAAS file that describe the components
Note:
When deploying JAAS configuration on the IBM WebSphere Application
server fails, remove all comments from the configuration file.
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.
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.
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
To use the standard JAAS login modules with Software AG Runtime
Server
Open the <SoftwareAG_directory>/profiles/CTP/configuration/config.ini file.
Change the value of the
com.softwareag.platform.jaas.enabled parameter from
"true" to "false".
Restart Software AG Runtime Server.
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:
Requisite
The login module is required to succeed. If it succeeds, the authentication proceeds down the login module list that is defined in the login context. If it fails, the control is immediately returned to the application and the authentication does not proceed down the login module list.
Required
The login module is required to succeed. If it succeeds or fails, the authentication process still proceeds down the login module list that is defined in the login context.
Note:
The overall authentication succeeds only if all
requisite and required login modules succeed.
Sufficient
The login module is not required to succeed. If it succeeds, the control is immediately returned to the application and the authentication does not proceed down the login module list. If it fails, the authentication proceeds down the login module list.
Note:
If a sufficient login module is configured and
succeeds, then the overall authentication succeeds only if the previous
requisite and required login modules
succeeded.
Optional
The login module is not required to succeed. If it succeeds or fails, the authentication process still proceeds down the login module list.
Note:
If there are not configured requisite or
required login modules then the overall authentication succeeds
only if at least one sufficient or optional login
module succeeds.
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.
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:
To specify a JAAS configuration file in the console window
Open a console window.
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
To specify a JAAS configuration file in the Java security properties
file
On the local file system, navigate to: JAVA_HOME/jre/lib/security.
Open the java.security file for editing.
Locate the Default login configuration file section in
the file.
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
If authentication is successful, JAAS creates a subject that contains one or more principals with security related attributes like passwords and cryptographic keys.
