IBM Business Analytics Proven Practices: Configuring Integrated Security for Cognos TM1 Web 10.2

Product(s): IBM Cognos TM1 10.2; Area of Interest: Security

How to set up integrated Windows Authentication for TM1 Web which now is a Java application in Cognos TM1 10.2 release. This is a supplement to the currently incomplete documentation.

Business Analytics Proven Practices Team, Business Analytics Proven Practices Team, IBM

Business Analytics Proven Practices Team



05 May 2014 (First published 24 March 2014)

Introduction

Purpose of Document

This document explains the steps required to configure IBM Cognos TM1 10.2 – TM1 Web for integrated security based on Kerberos using TM1 security modes 2 or 3.

Applicability

The techniques described herein apply to IBM Cognos TM1 10.2.0.1 (Fixpack 1) regardless of platform. Fixpack 1 is required as it addresses APAR PM97507.

Exclusions and Exceptions

There is currently no support for Single Sign-On (SSO) to TM1 Web when referring to a TM1 server configured for integrated security based on Kerberos. Refer to the IBM Cognos TM1 10.2 – TM1 Web F.A.Q. linked in the Resources section for details.

Further to this, there is no more support for integrated security based on NTLM as NTLM has been deprecated by Microsoft. Integrated security based on Kerberos is currently supported for TM1 servers running on Microsoft Windows platforms only. For details refer to the IBM Cognos TM1 10.2 – TM1 Web F.A.Q., items #10 and #11 of the What are known differences with the new web product? section.

Assumptions

The reader is expected to be familiar with the generic Kerberos authentication protocol and its concepts as well as Microsoft's Kerberos implementation and its tools. For details refer to the MIT Kerberos and Microsoft Kerberos links listed in the Resources section.

The reader is also expected to be familiar with JAAS and Java security concepts as described in the information accessible at the IBM JRE JAAS, security and JGSS link provided in the Resources section.


Setting the stage

IBM Cognos TM1 10.2 delivers a new implementation of the TM1 Web application in Java rather than as a Microsoft .NET application. The reasoning and detailed list of changes benefits and requirements can be found in the IBM Cognos TM1 10.2 – TM1 Web F.A.Q. document. One implication of this change is, that the technical aspects of authentication and single sign-on (SSO) to TM1 Web changed significantly. Whereas previous versions were implicitly leveraging the Microsoft Windows Kerberos functionality with a .NET application deployed to a Kerberos enabled Microsoft Internet Information Service, the new TM1 Web has to use a different approach since it is now using Java instead of .NET.

The new design is for the TM1 Web application to use the Java Generic Security Services (JGSS) API. This API is a Java version of a Generic Security Services (GSS) API which in turn allows for securely transmitting data between a client and server using a generic security protocol. The predominant security protocol being used is Kerberos but since the GSS API is agnostic of protocol specifics and their implementation details, the GSS APIs can leverage any suitable protocol on any platform.

With TM1 Web now being a Java application, this means TM1 Web is now platform agnostic and could be deployed independently of a TM1 server on non-Windows platforms. This implies that the JGSS API is used in conjunction with a Kerberos implementation but not necessarily Microsoft Kerberos. This means JGSS has to use the de-facto standard Kerberos implementation provided by the Massachusetts Institute of Technology (MIT), whose configuration aspects are less obvious than those of the Microsoft Kerberos implementation which is fully integrated into Windows.

TM1 Web will act as a client on behalf of a user looking to access a kerberized service, in this context a TM1 server on Windows in a given Microsoft Kerberos realm. In Microsoft Windows, a Kerberos realm is defined implicitly by a Windows domain. Therefore a user from a Windows domain which is trusted (implicit or explicit domain/forest trust required) by the domain in which the TM1 server is running can authenticate to the TM1 server through Kerberos. However, the user is not accessing the TM1 server directly but is using TM1 Web. For this to work, the Windows user will have to provide their Windows user name and password to TM1 Web which will run the authentication process on the user's behalf and if successful, the user is considered authenticated to TM1 Web as well.

The rundown is like this:

  1. TM1 Web enforces authentication by employing the JRE's Java Authentication and Authorization Services (JAAS). This implies that a user is prompted by JAAS for his credentials. Since there is no support for single sign-on in TM1 10.2 and since we're assuming Windows authentication, these credentials will have to be a Windows user name and password. Once the user provides their credentials they will be passed to a JAAS Kerberos login module.
  2. The JAAS Kerberos login module leverages standard Kerberos to obtain the user's initial Kerberos ticket, the Ticket Granting Ticket (TGT), based on the provided credentials. This is achieved by presenting those credentials to the Authentication Service (AS) of the Key Distribution Center (KDC) in the configured Kerberos realm. In the scenario considered for this document, this will be an instance of Microsoft Active Directory which acts as a Windows Domain Controller. Once obtained, the TGT is provided to TM1 Web.
  3. TM1 Web issues a SystemServer call employing the TM1 Java API to query the TM1 server for its Service Principal Name (SPN). This name is what the TM1 server configured for integrated security will have registered with the KDC so clients can request authentication to it through Kerberos. TM1 Web requires that name so it can subsequently request a service ticket for the TM1 server identified by that SPN.
  4. After TM1 Web learns the SPN of the TM1 server, it leverages JGSS calls to request a service ticket for the TM1 server from the KDC's Ticket Granting Service (TGS) on behalf of the user.
  5. If TM1 Web obtains this service ticket, it sends it to the TM1 server which in turn uses it to authenticate the user by employing Microsoft Windows SSPI API calls to interface with Windows security and the login is successful.

The architecture looks like this:

Drawing 1: TM1 Web authentication process for integrated security showing the interaction of TM1 and Kerberos implementations available on the hosting platforms
Drawing 1: TM1 Web authentication process for integrated security showing the interaction of TM1 and Kerberos implementations available on the hosting platforms

For all of this to work properly, several configuration steps need to be performed for TM1 Web, the JRE used to run it and even the TM1 server. This document supplements the product documentation while at the same time providing a Best Practice configuration.


Configuring integrated Login for TM1 WEB using Kerberos

The configuration consists of the following steps

  • enable integrated security support for TM1 Web
  • verify TM1 server configuration
  • configure the JRE executing TM1 Web
    • for JAAS
    • for JGSS on top of MIT Kerberos

After implementing these steps successfully, users will be able to authenticate to TM1 Web using their Windows user credentials.

Some of the suggested settings may not match the commonly used approach and seem overly complicated. The reasoning behind the deviation is to provide a simple and “apply everywhere” set-up procedure which is not based on assumptions regarding the environment.

As of TM1 10.2, TM1 Web can be deployed to IBM WebSphere Application server. For instances where TM1 Web is deployed to IBM WebSphere rather than Apache Tomcat, implement the steps from the WebSphere section where applicable.

Verify TM1 server configuration

When TM1 server is configured for integrated security, this implies the server is run on Microsoft Windows. This means a decision must be made as to what type of account is used to run the corresponding Windows service for the TM1 server instance. Possible choices are a system account like LocalSystem or an actual domain account. It is not possible to use local user accounts except the system accounts and the machine hosting the TM1 server must be a member of a an actual Windows domain - using Workgroups won't work.

Security best practices calls for the use of an actual domain account, although using a system account such as LocalSystem is technically possible. We'll refer to this account as <tm1s_account> and expect it to be a member of a domain.

If the TM1 server account is from a different domain than the potential users of TM1 Web or if users from multiple domains will access TM1 Web, ensure that all user domains are trusted by the domain the account running the TM1 server is from. Single one-way trust is sufficient - basically a user must be able to authenticate to a resource in the domain the TM1 server is in based on the account used to run it.

In the earlier section titled Setting the stage, it was mentioned that for the Kerberos authentication to succeed, the TM1 server must be assigned an SPN. For supporting integrated security the TM1 server must be installed to Windows. Since Microsoft Kerberos is special regarding SPNs, the assignment of an SPN can happen either explicitly as in MIT Kerberos which is the de-facto standard, or implicitly, which is a specialty for Microsoft Kerberos. While the implicit way seems very straight-forward - simply run the service with a domain account without any further additional steps - it is tricky and not recommended. With this document being about a best practice, we'll stick to explicitly defining an SPN.

To assign an SPN to the TM1 server two steps need to be performed:

  • Registering an SPN to the Windows domain account running the TM1 server by use of the Windows setspn tool.
  • Specifying the SPN in the TM1 server configuration file.

Only after both steps have been performed is the TM1 server properly set up for Kerberos based authentication using Microsoft Kerberos.

Recall that using the LocalSystem account is technically possible but is not a best practice. Not implementing the above steps leads to configurations which may actually work in a Windows only environment but potentially cause issues when non-Microsoft Kerberos clients such as TM1 Web, need to access those environments. Refer to Appendix A for details.

Register an SPN for TM1

To define an SPN for the TM1 server that TM1 Web is to connect to, implement the following steps on the computer hosting the TM1 server:

  • Configure the TM1 server Windows service to run as the domain user <tm1s_account>.
  • As a domain administrator or otherwise sufficiently privileged Windows domain user, open a command window and issue the following command,
    setspn -U -F -S tm1s/<FQDN_HOST> <tm1s_account>

    For example,
    setspn -U -F -S tm1s/myserver.example.com example\tm1s_plan

    This will register the SPN of tm1s/myserver.example.com to the user account tm1s_plan from the example domain if that particular SPN is not registered anywhere in the forest so far.
  • The following command can be used to verify the SPN has been added
    setspn -L example\tm1s_plan

Specify the SPN in the TM1 server configuration

Now that the SPN has been registered with Microsoft Kerberos, specify this SPN in the TM1 server's configuration. This is important because when the TM1 server is queried by the TM1 API to return it's SPN, it will return it in the following order,

  • the value of the ServicePrincipalName property from tm1s.cfg
  • the result of the Windows API GetUserNameEx() call
  • the result of the Windows API GetUserName() call

This means that if no value is provided for the ServicePrincipalName, the name of the account running the TM1 server will be returned instead which is a Windows User Principal Name (UPN) rather than a proper SPN and thus can lead to issues as described in Appendix A.

To specify the ServicePrincipalName property,

  1. Open the TM1 server's configuration file tm1s.cfg in a text editor such as Notepad.
  2. Edit or add the ServicePrincipalName property to specify the SPN assigned in the Register an SPN for TM1 step. Notice that we have appended the realm name @EXAMPLE.COM to the SPN. This realm name will be used later in the Kerberos configuration file. Although specifying the realm name is not strictly required for Microsoft Kerberos, it ensures compliance to the Kerberos standard. Notice that the realm name is in upper case – this is to distinguish it from a domain name. For example the corresponding line would look like this,
    ServicePrincipalName=tm1s/myserver.example.com@EXAMPLE.COM
  3. Save and close the tm1s.cfg file.
  4. Restart the TM1 server Windows service for the changes to take effect.

Enable integrated security support for TM1 Web

TM1 Web must be configured explicitly to link to the JAAS configuration put in place. This is achieved by adding a key to the TM1 Web configuration which specifies the name of the JAAS login context to be used for the integrated security authentication and thus implicitly the login module, in this case Kerberos. The name of that login context was specified in the JAAS configuration file and for this document was set to a value of TM1SignedOnUserLoginContext.

  1. On the computer running TM1 Web, open the file <TM1_ROOT>/webapps/tm1web/WEB-INF/configuration/tm1web_config.xml in a text editor such as notepad or vi.
  2. Locate the line that reads,
    <add key="IntegratedSecurityModuleName" value="LoginModule name"/>
  3. Replace the value of this key with TM1SignedOnUserLoginContext. The line should read,
    <add key="IntegratedSecurityModuleName" value="TM1SignedOnUserLoginContext"/>
  4. Save and close the file.
  5. If TM1 Web was deployed to IBM WebSphere, it is necessary for you to re-build and re-deploy the TM1 Web application files.

Configure Application Server security settings for TM1 Web

IBM Cognos TM1 Web supports deployments to Apache Tomcat and IBM WebSphere, however TM1 Web comes pre-deployed to Apache Tomcat on any supported platform. Deploying TM1 Web to IBM WebSphere is an extra task. Regardless of which one TM1 Web is deployed to, additional configuration steps are required to allow the TM1 Web application to leverage JAAS and Kerberos. For Apache Tomcat deployments this is simply a matter of configuring the JRE which runs Tomcat but for IBM WebSphere additional steps are required.

For Microsoft Windows versions of TM1 10.2, the IBM JRE 7 is delivered and pre-configured along with the product. On other supported platforms, a JRE must be supplied and specified. Although other JREs may be used for Tomcat, the recommendation is to use an IBM JRE whenever available on a given platform. The steps described for Tomcat environments apply to both the IBM JRE delivered as part of TM1 10.2 and non-IBM JREs.

For IBM WebSphere deployments the JRE is delivered as part of the WebSphere product. As it's expected to have other applications deployed to the same instance of IBM WebSphere, configuring the WebSphere JRE would have side effects and is therefore not advised. The steps provided in this document will allow the reader to properly configure only the TM1 Web application and leave other applications unaffected.

Configure JAAS and Kerberos for Apache Tomcat

To enable the JAAS login which is used by TM1 Web, a JAAS login configuration file containing the required information must be created and provided to the JRE used for Apache Tomcat. The JAAS login configuration file will need to specify a LoginContext and all the login modules to be used for authenticating a user in that context along with their specific options. For TM1 Web the login module will be Kerberos and additional options are required to ensure the actual credentials typed in by a user at the login page are obtained and are not a set of cached credentials. Cached credentials could be those of a user who was authenticated by Microsoft Kerberos when logging in to the Windows machine or of a user who previously authenticated to TM1 Web on the same client computer.

On the computer hosting TM1 Web, perform the following steps:

  1. Identify the JRE used by Apache Tomcat. Assuming an out of the box install on Windows, this will be the IBM JRE 7 which is found at <TM1_ROOT>/bin64/jre/7.0. For any other install check the JAVA_HOME environment variable picked up by Tomcat or investigate the PATH variable. We'll refer to the installation path of the JRE as <JRE_HOME>.
  2. In a text editor such as Notepad or vi, create a new empty file and save it under the name TM1WebLogin.config in <JRE_HOME>/lib/security. In the TM1 Web default Windows install this would be <TM1_ROOT>/bin/64/7.0/lib/security/TM1WebLogin.config.
  3. Back in the text editor, create a new login context with a name of TM1SignedOnUserLoginContext and specify the JRE's JAAS Kerberos login module. Note the option useDefaultCcache had been included to disable the default credential cache. For an IBM JRE the contents of the file should look like this.
    TM1SignedOnUserLoginContext {
     com.ibm.security.auth.module.Krb5LoginModule required 
     useDefaultCcache=false
     credsType=initiator;
    };

    Note the trailing semi-colon after the last option of the context. For details regarding these settings, refer to the IBM JRE 7 – JAAS login module configuration link in the Resources section at the end of this document.
  4. For an Oracle JRE, the contents of the file should look like this,
    TM1SignedOnUserLoginContext {
      com.sun.security.auth.module.Krb5LoginModule required 
      useTicketCache="false"
      isInitiator=”true”
      clearPass;
    };

    Once again, note the trailing semi-colon after the last option of the new login context.
  5. Save the file and close it.
  6. In a text editor open the JRE's security configuration file <JRE_HOME>/lib/security/java.security.
  7. Search for the text login.config.url. This should identify a snippet which looks like this:
    # Default login configuration file
    #login.config.url.1=file:${user.home}/.java.login.config
    login.config.url.1=file:${java.home}/lib/security/login.config

    Replace the name of the file (login.config) in the line which is not a comment (does not start with a # character) with TM1WebLogin.config. The result should look as follows,
    # Default login configuration file
    #login.config.url.1=file:${user.home}/.java.login.config
    login.config.url.1=file:${java.home}/lib/security/TM1WebLogin.config
  8. Save and close the file.

This concludes the setup of JAAS. Next the MIT Kerberos must be configured. Most JREs come with support for MIT Kerberos through the JGSS API. The underlying Kerberos library requires configuration though, in particular specifying which realms and domains are in play and to define other Kerberos specific settings. This information is provided in a file known as the Kerberos configuration file. While the Kerberos configuration file can be placed in various spots and picked up automatically, in this document we will put this file into the same default folder where other Java security related configurations are stored, that folder being <JRE_HOME>/lib/security. The file must be named either krb5.ini or krb5.conf - this document will use krb5.conf. For details about the possible locations of the file in IBM JRE, refer to the IBM JRE 7 – JGSS Kerberos login module configuration file link and for details about its contents and the meanings of all the options see the MIT Kerberos configuration file link - both links are provided in the Resources section of this document.

To create the Kerberos configuration file:

  1. Identify the JRE used by Apache Tomcat. Assuming an out-of-the-box install on Windows, this will be the IBM JRE 7 which is found at <TM1_ROOT>/bin64/jre/7.0. For any other install, check the JAVA_HOME environment variable picked up by Tomcat or investigate the PATH variable. Once again, we'll refer to the installation path of the JRE as <JRE_HOME>.
  2. In a text editor such as Notepad or vi, create a new empty file and save under the name krb5.conf in the <JRE_HOME>/lib/security directory. In the TM1 Web default Windows install this would be <TM1_ROOT>/bin/64/7.0/lib/security/krb5.conf.
  3. Add the following template of a Kerberos Configuration File for TM1 Web to the file:
    [libdefaults]
     default_realm = <REALM_NAME>
     default_tkt_enctypes = rc4-hmac des-cbc-crc
     default_tgs_enctypes = rc4-hmac des-cbc-crc
     ticket_lifetime = 1200
    [realms]
     <REALM_NAME> = {
     kdc = <fqdn_of_domain_controller>
     admin_server = <fqdn_of_domain_controller>
     default_domain = <domain_name>
     }
    [domain_realm]
     .<domain_name> = <REALM_NAME>
    [appdefaults]

    Note that the ticket_lifetime setting is specified in seconds and that the encryption types specified account for Windows setups that include older Windows version clients.
  4. In the template, the following edits are required,
    • Replace <domain_name> with the fully qualified lower case domain name of the domain which the TM1 server is running on.
    • Replace <REALM_NAME> with the fully qualified upper case name of the domain the authenticating users are from.
    • Replace <fqdn_of_domain_controller> with the fully qualified host name of a Microsoft Active Directory Domain Controller computer, or, if you want to leverage the Microsoft domain locator feature, the fully qualified domain name in lower case.
  5. In cases where users from multiple domains need to access TM1 Web,
    • Add another realm definition for each additional user domain.
    • Add another line in the [domain_realm] section to map the domain to the respective realm.
  6. Save and close the file.

The following Kerberos configuration example will allow users from two domains, EMEA.EXAMPLE.COM and US.EXAMPLE.COM, to authenticate. Users should prefix their user name with the domain (ie: domain\user) when logging in.

	[libdefaults]
		default_realm = EMEA.EXAMPLE.COM
	   	default_tkt_enctypes = rc4-hmac des-cbc-crc
		default_tgs_enctypes = rc4-hmac des-cbc-crc
		ticket_lifetime = 1200
	[realms]
     		EMEA.EXAMPLE.COM = {
           	kdc = dc1.emea.example.com
           	admin_server = dc1.emea.example.com
           	default_domain = emea.example.com
		}
		US.EXAMPLE.COM = {
                kdc = us.example.com
                admin_server = us.example.com
                default_domain = us.example.com
		}
	[domain_realm]
		.emea.example.com = EMEA.EXAMPLE.COM
		.us.example.com = US.EXAMPLE.COM
	[appdefaults]

Note the leading dot in front of the entries specified in the [domain_realm] section. We need to pay particular attention to how the entries in the [domain_realm] section are specified as this will determine the mapping of fully qualified domain names to the proper realms. The leading dot indicates a domain name which will effectively apply to all hosts in that domain or any sub-domain of it whereas a string without a leading dot simply specifies a single host.

Configure Kerberos and JAAS for IBM WebSphere

TM1 Web uses an application specific logon to authenticate users rather than interfacing with more general authentication services provided by Java application servers. As explained earlier, the login for integrated security employs a JAAS login module which in turn uses MIT Kerberos. There is a requirement for a Kerberos configuration to specify which realms and domains are in use and to define other Kerberos specific settings in addition to setting up the correct application specific JAAS module for the TM1 Web application in IBM WebSphere.

Kerberos configuration works by placing the Kerberos configuration file in one of several locations where it will be picked up automatically or by using a JRE property to specify its location explicitly. The file must be named either krb5.ini or krb5.conf - this document will use krb5.conf. For details about the possible locations of the file in IBM JRE, refer to the IBM JRE 7 – JGSS Kerberos login module configuration file link and for details about its contents and the meanings of all the options see the MIT Kerberos configuration file link - both links are provided in the Resources section of this document.

To create the Kerberos configuration file:

  1. In a text editor such as Notepad or vi, create a new empty file and save under the name krb5.conf. As a best practice for installs where TM1 is deployed to WebSphere, create this file in the TM1 installation folder.
  2. Add the following template of a Kerberos Configuration File for TM1 Web (krb5.conf) to the file :
    [libdefaults]
    	default_realm = <REALM_NAME>
    	default_tkt_enctypes = rc4-hmac des-cbc-crc
    	default_tgs_enctypes = rc4-hmac des-cbc-crc
    	ticket_lifetime = 1200
    [realms]
    	<REALM_NAME> = {
    	kdc = <fqdn_of_domain_controller>
    	admin_server = <fqdn_of_domain_controller>
    	default_domain = <domain_name>
    	}
    [domain_realm]
    	.<domain_name> = <REALM_NAME>
    [appdefaults]

    Note that the ticket_lifetime setting is specified in seconds and that the encryption types specified account for Windows setups that include older Windows version clients.
  3. In the template, the following edits are required,
    • Replace <domain_name> with the fully qualified lower case domain name of the domain which the TM1 server is running on.
    • Replace <REALM_NAME> with the fully qualified upper case name of the domain the authenticating users are from.
    • Replace <fqdn_of_domain_controller> with the fully qualified host name of a Microsoft Active Directory Domain Controller computer, or, if you want to leverage the Microsoft domain locator feature, the fully qualified domain name in lower case.
  4. In cases where users from multiple domains need to access TM1 Web,
    • Add another realm definition for each additional user domain.
    • Add another line in the [domain_realm] section to map the domain to the respective realm.
  5. Save and close the file.

The following Kerberos configuration example will allow users from two domains, EMEA.EXAMPLE.COM and US.EXAMPLE.COM, to authenticate. Users should prefix their user name with the domain (ie: domain\user) when logging in.

	[libdefaults]
		default_realm = EMEA.EXAMPLE.COM
	   	default_tkt_enctypes = rc4-hmac des-cbc-crc
		default_tgs_enctypes = rc4-hmac des-cbc-crc
		ticket_lifetime = 1200
	[realms]
     		EMEA.EXAMPLE.COM = {
           	kdc = dc1.emea.example.com
           	admin_server = dc1.emea.example.com
           	default_domain = emea.example.com
		}
		US.EXAMPLE.COM = {
                kdc = us.example.com
                admin_server = us.example.com
                default_domain = us.example.com
		}
	[domain_realm]
		.emea.example.com = EMEA.EXAMPLE.COM
		.us.example.com = US.EXAMPLE.COM
	[appdefaults]

Note the leading dot in front of the entries specified in the [domain_realm] section. We need to pay particular attention to how the entries in the [domain_realm] section are specified as this will determine the mapping of fully qualified domain names to the proper realms. The leading dot indicates a domain name which will effectively apply to all hosts in that domain or any sub-domain of it whereas a string without a leading dot simply specifies a single host.

The next step is to configure the JAAS login module.

When TM1 Web is deployed to IBM WebSphere, JAAS must be enabled for the specific application and not for overall WebSphere authentication. Instead of defining settings for the IBM WebSphere JRE which would apply to every application run in any instance of IBM WebSphere application server, the following steps should be used:

  1. Open WebSphere Administration Console and log in as a WebSphere administrator.
  2. Make sure the WebSphere server instance running TM1 Web is stopped.
  3. Go to Security → Global Security → Java Authentication and Authorization Service → Application logins.
    Illustration 1: The IBM WebSphere Administration Console showing the Global security configuration screen
    Illustration 1: The IBM WebSphere Administration Console showing the Global security configuration screen
  4. Click New... to add a new application login.
  5. For Alias provide TM1SignedOnUserLoginContext.
  6. Click New... to add a login module.
  7. For Module class name provide com.ibm.security.auth.module.Krb5LoginModule.
  8. Ensure Authentication strategy is set to REQUIRED.
  9. Specify a Custom property using the empty fields that are initially provided. For the Name field provide useDefaultCcache and for the Value field type false.
    Illustration 2: The IBM WebSphere Administration console showing the JAAS login module definition screen and its properties
    Illustration 2: The IBM WebSphere Administration console showing the JAAS login module definition screen and its properties
  10. Click OK.
  11. Click Save directly to the master configuration in the dialog that is presented. You should now see the Application logins list with the new entry now appearing in the list.
    Illustration 3: The IBM WebSphere Administration console dialog to save the configuration changes
    Illustration 3: The IBM WebSphere Administration console dialog to save the configuration changes
  12. In the left navigation pane, click on WebSphere application servers and find your server running TM1 Web. Click on its name.
  13. From the right hand items, locate the Server Infrastructure section and expand the Java and Process Management option.
  14. Select Process Definition.
  15. Click on Java Virtual Machine in the Additional Properties section on the right hand side.
  16. Scroll down to a field labelled Generic JVM arguments.
  17. Enter -Djava.security.krb5.conf=<TM1_ROOT>/krb5.conf into the field. This specifies the location of the Kerberos configuration file created earlier in this section.
  18. Click OK.
  19. Save to the master configuration.
  20. Restart IBM WebSphere server instance running TM1 Web.

Troubleshooting

Enable krb5 debugging

The easiest way to enable debugging for the Kerberos parts is to provide the debug parameter to the JAAS login module.

For Tomcat environments

In the JAAS configuration file, simply add the line debug=true into the login context definition as follows:

	TM1SignedOnUserLoginContext {
	 com.ibm.security.auth.module.Krb5LoginModule required 
	 useDefaultCcache=false
	 debug=true
	 credsType=initiator;
	};

For WebSphere environments

Add another parameter to the Application specific login module as follows,

  • Open the IBM WebSphere Administration Console and log in as a WebSphere administrator.
  • Make sure the WebSphere server instance running TM1 Web is stopped.
  • Go to Security > Global Security > Java Authentication and Authorization Service > Application logins.
  • Click on TM1SignedOnUserLoginContext.
  • Click com.ibm.security.auth.module.Krb5LoginModule.
  • Click the New button to add another property.
  • For the Name field type debug and in the Value field type true.
  • Save and apply the configuration.

At this point the WebSphere server instance hosting TM1 Web needs to be recycled for the changes to take effect. This will create extensive output in the Application Server's standard output file. The information will provide details about the client and server principals, the Kerberos handshakes and what failures might have occurred at the Kerberos protocol level.

Upon authentication a box states “invalid logon”

Ensure that Windows Authentication is selected at the login screen.

Upon authentication a box states “an error occurred”

This indicates an issue with the JGSS interaction or Kerberos related issues. Enable krb5 debugging (see above) and re-test. The trace output will show exceptions with lengthy stack-traces, you might need to scroll up. Search for the text PerformSingleSignon.

  • The krb5 trace output will show an exception labeled Configuration Error, when there is an issue with the JAAS configuration file. Be on the lookout for the trailing semi-colon after the last module option.
  • If the exception's message states Pre-authentication information was invalid (error code 24), this means the user's password was wrong.
  • If the exception's message states Server not found in Kerberos database (error code 7), this implies triple checking the SPN configured for the TM1 server. Make sure the SPN has been registered to Active Directory using setspn tool.
  • If the exception's message states Principal is null, this implies no input has been provided to the JAAS login prompt. This can happen because the Login button on the JAAS login prompt is enabled although no credentials have been provided yet. As there is no support for single sign-on, one must provide a Windows user name and password.

The standard output file contains “connection refused” exceptions

This is usually safe to ignore because this can happen when the login screen is called but TM1 Web has yet not retrieved the TM1 server information from the TM1 Administration Server.

Information to gather when requesting help

When looking to request help about an integrated security setup for TM1 Web in TM1 10.2, you are encouraged to provide the following information:

  • The TM1s.cfg of the TM1 server being connected to.
  • An output from the command setspn -L <tm1s_account>.
  • The JAAS configuration file.
  • The Kerberos configuration file (krb5.conf) from the TM1 Web host.
  • A krb5 trace.
  • Detailed information about Windows domains,
    • of the users authenticating
    • the account running TM1 Web
  • Output from the command <JRE_HOME>/bin/java -version.

Appendix A – Issues with combining MS Kerberos and MIT Kerberos

In Kerberos each identity is represented by what is called a principal. A principal consists of one or multiple name components separated by forward slash and the realm name in upper case following the “at” character (@). In common practice two types of principals have established - one for users referred to as user principal names (UPN) and another for services referred to as service principal names (SPN). They differ by interpretation of the principal name. A UPN's name is expected to refer to an actual user name whereas in a SPN the name typically has at least two components, one specifying the type of service and the second naming the instance (usually the server hosting the service). In either syntax the realm name is noted in upper case to differentiate it from domain names.

Examples of valid Kerberos UPNs are:

  • root/John@FEDSEC
  • John@EXAMPLE.COM.

Examples of valid Kerberos SPNs are:

  • tm1server/myserver.domain.com@FEDSEC
  • tm1server/myserver@EXAMPLE.COM.

We can see that a realm is not necessarily a domain name, it is simply a label assigned to the realm and is noted in upper case. On the other hand, domain names, which potentially are part of a SPN, are not case sensitive and can be specified in either upper or lower case. Domain names can't be case sensitive because Kerberos leverages Domain Naming Services (DNS) which by definition, is not case sensitive either. Valid Kerberos SPNs might also look like these:

  • tm1server/myserver@EXAMPLE.COM
  • tm1server/myserver.example.com@EXAMPLE.COM
  • tm1server/MYSERVER@EXAMPLE.COM
  • tm1server/MYSERVER-EXAMPLE.COM@EXAMPLE.COM

In Microsoft Windows, every domain implicitly defines a Kerberos realm and thus the DNS domain name and the realm name will match up but may differ in case. The important thing is that Microsoft Windows will automatically map things accordingly for SPNs and UPNs thus obfuscating the fact that Kerberos is actually case sensitive and a domain name is something different than a realm in MIT Kerberos. In short, Microsoft Windows basically allows a domain name and a realm name to be used interchangeably. This is not a concern for SPNs as MIT Kerberos also allows for mapping domain names to realms by explicit configuration, however this is a big concern for UPNs.

In Microsoft Kerberos, john@example.com is a valid UPN (notice the case). This UPN expresses that john is a member of the domain example.com. Unfortunately if this is read by MIT Kerberos APIs as a UPN it implies that john is a member of the realm example.com which, by definition, should be in upper case. Since this is a UPN there is no mapping available because lower case realms are not supported and MIT Kerberos will try to interact with the realm example.com, which it won't be able to find in its configuration. It is easy to see that this will eventually lead to an issue.

So the recommendation is to avoid using UPNs for services when doing Kerberos authentication in mixed (Microsoft Windows vs MIT Kerberos) environments. Services should define a proper SPN which can be handled properly by any Kerberos implementation. Unfortunately this case-sensitive issue is sometimes overlooked because servers or services may simply use the name of the account they run as for SPN. For example it's very common for Windows services to run as Local System which grants sufficient privileges on the local Windows system but for Microsoft Kerberos Local System is mapped to the machine's account name, which in turn is perceived to be a UPN and therefore subject to the issues described above. There is a concept of user to user authentication in Kerberos but this is intended for a completely different purpose and Microsoft's implementation of this concept also differs from MIT's.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Big data and analytics on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Big data and analytics
ArticleID=966557
ArticleTitle=IBM Business Analytics Proven Practices: Configuring Integrated Security for Cognos TM1 Web 10.2
publish-date=05052014