Single Sign-On (SSO) Support Requirements

Before attempting to configure SSO support for aXes, SSO support on IBM i needs to be configured properly. In order to assess if your IBM i has been configured properly, you need to be able to login using SSO using the terminal client emulator.

Please note that configuring your IBM i to use SSO is not in the scope of this guide. However, we have listed a few points you might consider if you encounter issues when configuring SSO on your IBM i.

Do you have the JSM service configured and working?  The best way to check to is make sure DE2 or WS2 are working properly.
Do you have the correct Kerberos Domain?  For example: BRANCH.MYCOMPANY.COM
Do you have the windows user name with proper permissions? For example: user1
Do you use you IBM FQN in the CHGTCPDMN command? For example: server.branch.company.com
Do you have the correct SPN setup on the Kerberos Domain Controller (KDC)? For example: HTTP/This email address is being protected from spambots. You need JavaScript enabled to view it.
Do you have the KEYTAB file for IBM i Applications? 

This Keytab file is used by IBMi applications to process the SSO authentication.

It is located in: /QIBM/UserData/OS400/NetworkAuthentication/keytab/krb5.keytab

Does the windows user name have an EIM mapping to an IBM i user?      
Is the windows user name account enabled for delegation on the KDC?      
Is the Service Account enabled for delegation on the KDC? For example:
HTTP/lansa01.syd.lansa.com.au needs to be enabled for delegation.

Configure the Keytab File for the JSM service.

The Keytab file configured for IBM i application cannot be used by the JSM service to authenticate users. You need to configure you own Keytab file called spnego.keytab.

Use the KTPASS utility on the windows KDC to generate the spnego.keytab.

Copy the spnego.keytab to the following folder in your axes instance.

The file should be located in /<axes_dir>/jsm/instance/system

 Display the spnego.keytab file to make sure the HTTP SPN is included.

Use the following command on the IBM i:

DSPKRBKTE KEYTABFILE('/<axes_dir>/jsm/instance/system/spnego.keytab')

This is the type of output to expect:

Also, to check your configuration, you can run the following command to Add a Kerberos Ticket.

ADDKRBTKT PRINCIPAL('HTTP/lansa08.syd.lansa.com.au' *DFT) KEYTABFILE(*DFT)

Check you joblog and you should see an entry like the below:

ADDKRBTKT PRINCIPAL('HTTP/lansa08.syd.lansa.com.au' *DFT) KEYTABFILE('/axes311/jsm/instance/system/spnego.keytab')

Which should result in a message in your joblog:


 
Configure the JSM-SSO service.

The following steps will configure the JSM SSO service based on a successful configuration of the previous steps.

Make sure the spnego.keytab file is located in <axes_dir>/jsm/instance/system/ folder.

Create a spnego.txt file and specify the default realm, default keytab file and the Windows KDC server.

Place the spnego.txt file in the same folder where the spnego.keytab file is located.

For example: Change values to match your setup.

#

# Be careful with whitespace and blanks lines as these can break the file parsing

#

[libdefaults]

   default_realm = SYD.LANSA.COM.AU

   default_keytab_name = system/spnego.keytab

   [realms]

      SYD.LANSA.COM.AU = {

         kdc = SYD1.SYD.LANSA.COM.AU:88

         }
   [domain_realm]

   [capaths]

Add the following properties to the file: <axes_dir>/jsm/instance/system/manager.properties

Manager.properties snippet example

#

# Kerberos

#

# sun.security.jgss.debug=true

# sun.security.krb5.debug=true

# com.ibm.security.jgss.debug=all

# com.ibm.security.krb5.Krb5Debug=all

java.security.krb5.conf=system/spnego.txt

javax.security.auth.useSubjectCredsOnly=false

Edit the file <axes_dir>/jsm/instance/system/httpd.xml file and add or update the ssoservice.jsp entry, with values matching your domain.

The snippet should be added in the <script> </script> tag, preferably just after the <script> tag

http.xml snippet example

<!--

   SSO service

-->

<match uri="/axes/ssoservice.jsp" class="com.lansa.mobile.service.HTTPServiceSSO">

  <parameter name="service.origin"  value="*"/>

  <parameter name="service.host"    value="lansa01.syd.lansa.com.au"/>

  <parameter name="service.realm"   value="SYD.LANSA.COM.AU"/>

  <parameter name="service.default.ports" value="true"/>

</match>

Check if you are running JRE version 1.6+

Open the trace file located at

/<axes_dir>/jsm/instance/trace/<latest_date>/manager.txt

And look for the line: “system: java.version”

If it displays 1.5.0 then you need to upgrade your JRE runtime to 1.6+ and follow step 6.

If it displays 1.6.0 (or greater) then go to step 7.

If necessary, change the job Description on IBM i to use JRE version 1.6+

Use the command:

CHGJOBD JOBD(axes_library>/JSM) then F4, then F10.

Change the RUNJSM start line version Parameter to v6.

As below:



Save your changes and restart aXes

Configure users’ browsers to perform spnego authentication.

Internet Explorer

To use Internet Explorer, you need to add the address in the trusted sites, at the following location:

Internet Options/Security/Local Intranet/Sites/Advanced/WebSites

Also make sure the settings of internet options / Security / local intranet / sites/ advanced references your domain.


 
Chrome

To use Chrome, you need to add / change the following Registry keys values to match your domain.

[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google]

[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome]

"AuthNegotiateDelegateWhitelist"="*.mycompany.com"

"AuthServerWhitelist"="*.mycompany.com"

Firefox

To use Firefox, add the following properties in the advanced option. In the address bar, type about:config, then change the following values to match your domain:

network.negotiate-auth.trusted-uris:

network.negotiate-auth.delegation-uris:

Test your settings.

Once aXes has been restarted on the IBM i, open the trace file located in:

/<axes_dir>/jsm/instance/trace/<latest_date>/manager.txt

check that the following lines display:

system: java.version : <version> (where version >= 1.6.0)

manager: start http instance 'WebServer', listen on port <port> across all interfaces (where port is the http port value)

Open a browser and navigate to the following address. Please note to use the FQN name of the server, and make sure you are logged in on Windows with the user mapped in the EIM.

http://server.mycompany.com:port/axes/ssoservice.jsp

Result with Internet Explorer

Result with Chrome

Result with Firefox

Configure the aXes SSO service.

Follow the below steps to enable aXes to use SSO.

Open the AxesTS.conf configuration file. Add the following configuration lines.

The tgturl should refer to the ssoservice defined in the JSM-SSO configuration point 4.

Httpd.xml snippet example

<listen port="5563" sslport="5564" interface="*ALL" backlog="256"secure="false" store="pki/wwwssl.jks" password="password" sslprotocol="TLSV1.2" buffersend="-1" bufferreceive="-1" nodelay="false" timeout="5"/>

axests.conf snippet example

# Enable single sign on with Kerberos

autosignon=1

tgturl=http://server.mycompany.com:port/axes/ssoservice.jsp?storetoken=true

Server: the address of the JSM http server (for example: lansa08.syd.lansa.com.au)

Port: the port defined as the JSM http server in the httpd.xml file located in <axes_dir>/jsm/instance/system/httpd.xml. The default listener port is 5563.

Restart aXes subsystem.

Test your configuration:

Open the following address:

http://server.domain.com:port/ts/ts2/index.html?sso=true

For example:

http://lansa08.syd.lansa.com.au:8311/ts/ts2/index.html?sso=true