Configuring Application-Managed Authentication

This document covers the following topics:

• General Information

• Activating Application-Managed Authentication

• Securing the Logon Page

• The Login Configuration

• Defining the Login Configuration on JBoss Application Server

• Defining the Login Configuration on IBM WebSphere Application Server

• Defining the Login Configuration on Apache Tomcat

• Forwarding the User Credentials to Natural

• Using Software AG Security Infrastructure

• Using Integrated Authentication Framework (IAF)

General Information

Natural for Ajax is a Java EE-based application that runs on an application server or web container. By default, the access to this application is not secured. The credentials that users enter in the Natural for Ajax logon page (see the graphic below) are used to authenticate them in the selected Natural environment. They are not used to authenticate them on the application server or web container.

You might, however, wish to authenticate the users already in the application server or web container, before they even attempt to access a Natural session. This can be achieved with container-managed security (see Configuring Container-Managed Security), but only for a subset of the supported application servers. With application-managed authentication, this can be achieved for all supported application servers and web containers.

When application-managed authentication has been activated, the user is first authenticated on the application server or web container. For the authentication, JAAS-based (Java Authentication and Authorization Service) login modules are used. The login modules to be used and their parameters are configured in a login configuration. The user credentials entered on the Natural for Ajax logon page are authenticated against a user repository that is defined by the configured login modules.

A login configuration can consist of several login modules that are executed one after the other. A specific login module is responsible to forward the entered credentials from the application server or web container to the Natural Web I/O Interface server, so that they can be reused to authenticate the user on the Natural server side.

Activating Application-Managed Authentication

Application-managed authentication is activated on a per-session basis in the configuration tool.

To activate-application managed authentication for a session

1. Invoke the configuration tool.

2. In the frame on the left, choose the Session Configuration link.

3. Add a new session or edit an existing session.

4. Select the Use JAAS-based authentication check box.

   The Forward credentials check box is then selected automatically. This makes sure that the credentials entered for the authentication on the application server or web container are forwarded to the Natural server.

5. Choose the OK button.

6. Choose the Save Configuration button.

   When a user opens the Natural for Ajax logon page and selects the session for which you made the above changes, the credentials entered on the logon page are now used to authenticate the user on the application server or web container and are then forwarded to the Natural server.

   This applies also when a user does not explicitly open the logon page in order to select a session manually, but instead passes the session name as an URL parameter to the logon page as described in Starting a Natural Application with a URL.

Securing the Logon Page

You may wish to authenticate the users before they even access the Natural for Ajax logon page. This is activated globally in the configuration tool.

To secure the logon page

1. Invoke the configuration tool.

2. In the frame on the left, choose the Session Configuration link.

3. Select the Use secure logon page check box.

4. Choose the Save Configuration button.

   When a user opens the Natural for Ajax logon page without specifying a session name beforehand, the user will now be prompted to enter the credentials in order to be authenticated on the application server or web container.

The Login Configuration

With JAAS, authentication is always done against a so-called realm. A realm defines the scope of security definitions. There can be several distinct realms. The user "George" in realm A, for example, is considered to be different from the user "George" in realm B. The realms are usually defined in a login configuration file. The location of this file depends on the application server or web container. A typical realm definition contains a set of login modules that are executed in a specific order to authenticate a user within this realm. The login modules are responsible for the actual authentication.

Natural for Ajax authenticates users against a realm named "NaturalWebIOAndAjaxRealm". Therefore, the login configuration of the application server or web container must contain a realm definition with this name.

Defining the Login Configuration on JBoss Application Server

The login configuration depends on the JBoss Application Server version. To define a sample configuration, proceed as described in one of the following sections, depending on the version that you are using:

• Choosing the Login Module (JBoss Application Server 7 and WildFly8)

Further configuration is described in the version-specific topics below:

• JBoss Application Server 7 and WildFly8

JBoss Application Server 7 and WildFly8

If you use other login modules than in the sample configuration, copy the JAR files with these login modules into the WEB-INF/lib directory of the Natural for Ajax web application, which is called cisnatural.war by default.

In order to prepare for the step Forwarding the User Credentials to Natural, you need to provide the Natural for Ajax login module com.softwareag.njx.loginmodule.NJXLoginModule in the right place. This login module is contained in the JBoss7-WildFly8 directory of the installation medium, in the file njxlogin<nn>.jar. Copy this file also into the WEB-INF/lib directory of of the Natural for Ajax web application.

Defining the Login Configuration on IBM WebSphere Application Server

Copy the JAR files with the login modules to be used into the lib/ext directory of your IBM WebSphere installation. The Natural for Ajax login module com.softwareag.njx.loginmodule.NJXLoginModule mentioned below is contained in the file njxlogin<nn>.jar, which can be found in the WebSphere-specific directory of the installation medium.

To configure the login module

1. Make sure the application server is running.

2. Open your web browser and enter the following URL:

   http://<host>:<adminport>/ibm/console

   This opens the Administration Console.

3. Open the tree node Security > Global security.

4. On the right side of the screen, open Java Authentication and Authorization Service.

5. Choose Application logins.

6. Choose New.

7. Enter "NaturalWebIOAndAjaxRealm" as an alias.

8. Choose OK.

9. Choose Save.

10. Select NaturalWebIOAndAjaxRealm.

11. Choose New.

12. Enter the class name of your login module.

13. Configure the authentication strategy and custom properties of your login module.

14. Choose OK.

15. Choose Save.

16. Select NaturalWebIOAndAjaxRealm once more.

17. Choose New.

18. Enter the class name "com.softwareag.njx.loginmodule.NJXLoginModule".

19. Choose OPTIONAL as the authentication strategy.

20. Enter "useFirstPass" as the property name.

21. Enter "true" as the property value.

22. Select the Select check box.

23. Choose New.

24. Enter "storePass" as the property name.

25. Enter "true" as the property value.

26. Select the Select check box.

27. Choose OK.

28. Choose Save.

Defining the Login Configuration on Apache Tomcat

Copy the JAR files with the login modules to be used into the lib directory of your Apache Tomcat installation.

The Natural for Ajax login module com.softwareag.njx.loginmodule.NJXLoginModule mentioned below is contained in the file njxlogin<nn>.jar, which can be found in the Tomcat-specific directory of the installation medium. Copy the file njxlogin<nn>.jar into the WEB-INF/lib directory of the Natural for Ajax web application, which is called cisnatural by default.

In the conf directory of your Apache Tomcat installation, add a new properties file named njxjaas_config.properties. Within this file, configure the login modules in the following way:

NaturalWebIOAndAjaxRealm {
  your-login-module-class required
    param1="value1"
    param2="value2";

  com.softwareag.njx.loginmodule.NJXLoginModule optional
    useFirstPass=true
    storePass=true;
};

On Windows, edit the file startup.bat in the Apache Tomcat bin directory and add the following line:

set JAVA_OPTS=%JAVA_OPTS% -Djava.security.auth.login.config=%CATALINA_HOME%/conf/njxjaas_config.properties

Or, if you have installed Apache Tomcat as a Windows service, specify the above Java option in the Apache Tomcat Properties dialog.

On UNIX or Linux, edit the file startup.sh in the Apache Tomcat bin directory and add the following line:

JAVA_OPTS=$JAVA_OPTS -Djava.security.auth.login.config=$CATALINA_HOME/conf/njxjaas_config.properties

Forwarding the User Credentials to Natural

When the user has been authenticated on the application server or web container, the authenticated user with the credentials can be forwarded directly to the Natural Web I/O Interface server. Optionally, the user can be authenticated the Natural Web I/O Interface server again. Also optionally, the started Natural session can be started under the user ID of the client (impersonation).

However, this works only if both the authentication on the application server and the authentication on the Natural Web I/O Interface server are done with the same credentials against the same authentication system. This will be the case, for example, if the Natural Web I/O Interface server is configured to authenticate with RACF and you have configured a login module on the application server or web container that authenticates the user against the same system.

To forward the user credentials to Natural

1. Invoke the configuration tool.

2. In the frame on the left, choose the Session Configuration link.

3. Add a new session or edit an existing session.

4. Make sure that the Forward credentials check box is selected.

5. Choose the OK button.

6. Choose the Save Configuration button.

Using Software AG Security Infrastructure

Software AG Security Infrastructure (SIN) has originally been designed as a common authentication infrastructure for the webMethods product suite. SIN is based on the above mentioned JAAS (Java Authentication and Authorization Service) framework and provides a number of predefined JAAS-based login modules. For detailed information on these login modules and their configuration, see the Software AG Security Infrastructure documentation at http://documentation.softwareag.com/webmethods/security_infrastructure.htm (Empower login required).

With this Natural for Ajax distribution, the SIN login modules are delivered in the top level directory /Support/SIN as a zip file with name SIN_<version>.zip. Unzip this file to a temporary directory. The login modules are then contained in the directory with the name jars. The JAR files of interest are:

• sin-common.jar

• sin-misc.jar

• sin-ssx.jar

• sin-xmlserver.jar

If you want to use the SIN login modules with Natural for Ajax, you have to copy the above JAR files into the proper directory of your application server or web container (for information on the proper directory, see the above sections which describe how to define the login configuration).

Natural for Ajax currently supports the following predefined login modules from the SIN package:

• SSXLoginModule

• SAMLArtifactLoginModule

SAMLArtifactLoginModule

When this login module is installed and configured for Natural for Ajax, the end user is not prompted for a user name or password during the login.

Make sure that the opensaml library and the Apache common libraries are in the class path of the login module (for detailed information, see the description of the SAMLArtifactLoginModule in the Software AG Security Infrastructure documentation) and then configure the use of SAML as described below.

To configure the use of SAML

1. Invoke the configuration tool.

2. In the frame on the left, choose the Session Configuration link.

3. Under Global Settings, make sure that the Use SAML for JAAS-based authentication check box is selected.

4. Add a new session or edit an existing session.

5. Make sure that the Use JAAS-based authentication check box is selected.

   When both Use SAML for JAAS-based authentication and Use JAAS-based authentication are selected, the user name and password fields are not visible in the Natural for Ajax logon page for the used session.

6. Choose the OK button.

7. Optional. Under Global Settings, select the Secure logon page check box.

   Now, the secure logon page will only be displayed in the case of an error in the SAML artifact validation.

8. Choose the Save Configuration button.

For more information on the above options, see Session Configuration.

In both logon pages (Natural for Ajax logon page and secure logon page), the end user is no longer prompted to enter user name and password. Instead, the SAML artefact ticket, which is transported in the HTTP header, is validated. The SAMLArtifactLoginModule can extract the user name from the SAML artefact. Therefore, it is not necessary to enter a user name. A valid SAML artefact inside the HTTP header provides the authentication for the Natural for Ajax server.

Important:
The Natural for Ajax application does not send a password. Therefore, you have to disable the password check on the Natural Web I/O Interface server. Make sure that only selected Natural for Ajax application servers have access to a Natural server which has been configured in this way.

Using Integrated Authentication Framework (IAF)

With Natural for Ajax, you can authenticate against a Software AG IAF server. Natural for Ajax delivers an IAF login module for this purpose. After you have successfully entered your login credentials, the IAF server creates an IAF token. This token will be sent to Natural for enhanced authentication.

The IAF login module needs a running IAF server. For detailed information on how to set up an IAF server, see the Software AG Security Infrastructure documentation at http://documentation.softwareag.com/webmethods/security_infrastructure.htm (Empower login required).

The name of the IAF login module is com.softwareag.njx.loginmodule.iaf.IAFLoginModule. It supports the following parameter:

iafConnection="ssl://myiafserver:11958?TRUST_STORE=C:\\SoftwareAG\\IAF\\iaf\\etc\\IAFAppCert.jks&VERIFY_SERVER=N";    

The Natural for Ajax login modules com.softwareag.njx.loginmodule.NJXLoginModule and com.softwareag.njx.loginmodule.iaf.IAFLoginModule are contained in the following files:

• njxlogin<nn>.jar

• njxiaflogin<nn>.jar

The above JAR files are contained in the application server-specific directory of the installation medium. You have to copy these files into the proper directory of your application server or web container (see below).

The IAF login module uses parts of the Software AG Security Infrastructure. Therefore, the following additional JAR files are required:

• IafClient.jar

• entirex.jar

• sin-common.jar

The above JAR files are delivered in the top level directory /Support/SIN of the installation medium, in a zip file with name SIN_<version>.zip. Unzip this file to a temporary directory. The JAR files are then contained in the directory with the name jars. Note that the file entirex.jar is contained in the file IafClient.jar and needs to be extracted from there. You have to copy these files into the proper directory of your application server or web container (see below).

Further configuration information is provided in the topics below:

• Configuration on JBoss Application Server 7 and WildFly8

• Configuration on IBM WebSphere Application Server

• Configuration on Apache Tomcat

Configuration on JBoss Application Server 7 and WildFly8

Prepare the login modules as described under Choosing the Login Module (JBoss Application Server 7 and WildFly8) .

Copy all required JAR files (see above) from the installation medium to standalone\deployments\cisnatural.war\WEB-INF\lib.

Edit the file standalone.xml and add the definition for the IAF login module under <security-domains>:

<security-domain name="NaturalWebIOAndAjaxRealm" cache-type="default">
 <authentication>
  <login-module code="com.softwareag.njx.loginmodule.iaf.IAFLoginModule" flag="required">
   <module-option name="iafConnection" value="ssl://myiafserver:11958?TRUST_STORE=C:\\SoftwareAG\\IAF\\iaf\\etc\\IAFAppCert.jks&amp;VERIFY_SERVER=N"/>
  </login-module>
  <login-module code="com.softwareag.njx.loginmodule.NJXLoginModule" flag="optional">
   <module-option name="password-stacking" value="useFirstPass"/>
   <module-option name="useFirstPass" value="true"/>
  </login-module>
 </authentication>
</security-domain>

Configuration on IBM WebSphere Application Server

Prepare the login modules as described above under Defining the Login Configuration on IBM WebSphere Application Server.

Copy all required JAR files (see above) from the installation medium to lib/ext.

Configure the IAF login module as described below.

To configure the IAF login module

1. Configure the login module in the same way as described under Defining the Login Configuration on IBM WebSphere Application Server.

2. For the step "Enter the class name of your login module", enter the following:

   com.softwareag.njx.loginmodule.iaf.IAFLoginModule

3. For the step "Configure the authentication strategy and custom properties of your login module" proceed as follows:

   • Enter the class name of your login module: "com.softwareag.njx.loginmodule.iaf.IAFLoginModule".

   • Choose REQUIRED as the authentication strategy.

   • Enter "iafConnection" as the property name.

   • Enter the IAF connection string as the property value. Example:

     iafConnection="ssl://myiafserver:11958?TRUST_STORE=C:\\SoftwareAG\\IAF\\iaf\\etc\\IAFAppCert.jks&VERIFY_SERVER=N";

4. Proceed with the remaining configuration steps described under Defining the Login Configuration on IBM WebSphere Application Server.

Configuration on Apache Tomcat

Prepare the login modules as described above under Defining the Login Configuration on Apache Tomcat.

Copy all required JAR files (see above) from the installation medium to WEB-INF/lib.

Edit the file njxjaas_config.properties and add the definition for the IAF login module:

NaturalWebIOAndAjaxRealm {
  com.softwareag.njx.loginmodule.iaf.IAFLoginModule required
    iafConnection="ssl://myiafserver:11958?TRUST_STORE=C:\\SoftwareAG\\IAF\\iaf\\etc\\IAFAppCert.jks&VERIFY_SERVER=N";

  com.softwareag.njx.loginmodule.NJXLoginModule optional
    useFirstPass="true"
    tomcatMode="true"
    storePass="true";    
};