Configure integrated login for TM1 Web

You can configure TM1® Web for integrated login. You can also set up single sign-on (SSO) for HTTP-based clients by using Integrated Windows Authentication (IWA) using the Kerberos protocol.

Overview

TM1 Web does not authenticate users but defers to TM1 Server for authentication. When you log in to TM1 Web, you are prompted for credentials based on the security mode that is configured on the IBM® TM1 Server. When a user provides credentials, TM1 Web uses TM1 Server authentication on the user's behalf with the provided credentials. For integrated login, the server that is being accessed by TM1 Web must be configured for integrated login.

Integrated login works without any configuration in TM1 Web. You can select a server that is configured for integrated login and TM1 Web prompts for your credentials. When you enter your credentials, TM1 Web sends them to the TM1 Server for authentication.

Important: If you set up TM1 Server, TM1 Web, and Planning Analytics Workspace Local using security mode 2 or 3 (integrated login), websheets cannot be used in Planning Analytics Workspace. For more information, see Configure security mode 2 or 3 to use websheets in Planning Analytics Workspace.

You might want to configure single sign-on so that users are not prompted for credentials when they access TM1 Web. For this approach to work, TM1 Web must be configured to integrate with Windows Authentication (Kerberos) to accept a user's forwarded Windows credentials and then perform an integrated login to a TM1 Server on the user's behalf with those credentials. Since TM1 Web does not support Kerberos for authentication directly, you must set up the security features of the WebSphere® Liberty Profile server that TM1 Web is deployed to.

The setup process requires the following double-hop authentication:

Single sign-on from the client to IBM WebSphere Liberty Profile

First, you must enable the IBM WebSphere Liberty Profile (WLP) application server's security. Next, a user registry must be configured for WebSphere Liberty Profile to authenticate users against it. Last, WebSphere Liberty Profile must be configured to allow SSO to it.

For Integrated Windows Authentication, you must use the Simple and Protected GSS-API Negotiation Mechanism (SPNEGO) web authentication provider. This provider allows Kerberos enabled clients to achieve single sign-on to WebSphere Liberty Profile. A user who is logged in to Windows using a client that supports Integrated Windows Authentication can authenticate to WebSphere Liberty Profile without getting prompted because of the Kerberos protocol.

Single sign-on from IBM WebSphere Liberty Profile to TM1 Server using TM1 Web

Single sign-on from IBM WebSphere Liberty Profile to each TM1 Server that is configured for integrated login uses the Java™ Generic Security Services API (JGSS) and Java Authentication and Authorization Services (JAAS) to delegate the received Kerberos user credentials to TM1 Web. TM1 Web performs a Kerberos-based authentication with TM1 Server on the user's behalf.

After you implement this setup successfully, users who are using browsers that are enabled for Integrated Windows Authentication can authenticate to TM1 Web configured to access a TM1 Server that is running security mode 2 or 3 (integrated login) with their Windows user credentials.

Before you begin

Make sure that the following prerequisites are configured:

All computers that participate in the setup are running Microsoft Windows and are joined to a Windows domain.
Mutual trust is set up between all domains that any computer from the setup is registered to.
All computers in the setup can resolve the fully qualified domain name of all other computers and Windows domain controllers that are used in the configuration.
An instance of TM1 Server is configured for integrated login. For more information, see Configure integrated login for the IBM TM1 Server. The following settings must be configured:
- A Service Principal Name (SPN) is registered to a Windows account that runs the Windows service for the TM1 Server instance.
- The SPN is specified in the ServicePrincipalName parameter in the tm1s.cfg file.
- The IntegratedSecurityMode in the tm1s.cfg file is set to 2 or 3.
- The SecurityPackageName is set to Kerberos.
- For all users who access the TM1 Server, the UniqueID element in the }ClientProperties dimension is set to a string with the syntax <sAMAccountName>@<DOMAIN>.
An instance of TM1 Application Server is installed on a computer in the setup.
A domain user can log in to a client computer that is different from the computer that the TM1 Application Server components are installed on. The user must be able to run a supported browser to access TM1 Web. For more information, see Enable web browsers for integrated login.

Conventions

The setup uses the following conventions:

<PA>: The Planning Analytics installation root folder.
<PA_APP_DOMAIN>: The name of the Microsoft Windows domain, for example, mydomain.sample.com.
<PA_APP_REALM>: The <PA_APP_DOMAIN> in uppercase, for example, MYDOMAIN.SAMPLE.COM.
<PA_APP_HOST>: The fully qualified host name of the computer where TM1 Application Server is installed, for example, appsrv1.mydomain.sample.com.
<PA_APP_ACCOUNT>: A user account from a Windows domain that is used to run TM1 Application Server.
<PA_SPN>: A string composed of HTTP (in uppercase), the / delimiter, and the <PA_APP_HOST>. For example, HTTP/appsrv1.mydomain.sample.com.

Set up an account for the TM1 Application Server

As a domain administrator, create a domain user account or find an existing domain user account that will be used to run the TM1 Application Server service. This user account is referred to as <PA_APP_ACCOUNT>. For example, mydomain/pa11.
Ensure <PA_APP_ACCOUNT> has sufficient file system permissions on <PA_APP_HOST>. In particular, the account requires modify permission on the following folders:
- <PA>/wlp
- <PA>/logs
- <PA>/temp
On <PA_APP_HOST>, make sure the IBM Cognos® TM1 service that runs the TM1 Application Server (WLP) is started by <PA_APP_ACCOUNT>. (See 1).
1. Using the Windows Services control pane, right-click the IBM Cognos TM1 service and click Properties.
2. On the Log On tab, add the <PA_APP_ACCOUNT> and password.
3. Click OK.
On <PA_APP_HOST>, get a domain Administrator to create a Kerberos keytab file by using the Microsoft ktpass tool.
Note: WebSphere Liberty Profile requires server credentials for supporting Kerberos authentication to it. These credentials are stored in a keytab file. To create this file, you must use the Microsoft ktpass tool.

In a CMD window, type the following command:
```
ktpass -out <keytab_file> -princ <PA_SPN>@<PA_APP_REALM> 
-mapuser <PA_APP_ACCOUNT> -pass <password> -mapOp set 
-ptype KRB5_NT_PRINCIPAL
```
For example:
```
ktpass -out pa.keytab -princ HTTP/appsrv1.mydomain.sample.com@MYDOMAIN.SAMPLE.COM 
-mapUser mydomain\pa11 -pass pssw0rd -mapOp set -ptype KRB5_NT_PRINCIPAL
```
This command creates a pa.keytab file in the current folder that contains the Kerberos server credentials.

Note: The keytab contains keys that are encrypted using a specific encryption scheme called encryption type in Windows. The Active Directory administrator knows which ones are supported by the Active Directory infrastructure. If in doubt, put keys into the keytab for all supported encryption types by using the append -crypt all option.

When you use the ktpass tool, several things happen:
- The principal specified in the -princ parameter will be registered as an SPN to the account specified for the -mapuser parameter.
- The UserPrincipalName (=User Login Name) of the account will be changed in Active Directory to the SPN specified for the -princ parameter. This is intended and required and must not be reverted manually.
- The output of this command is a binary keytab file. The file can be moved. It does not depend on a host or host name.
CAUTION:
The keytab contents can get invalidated if changes are applied to the PA_APP_ACCOUNT in Active Directory after the keytab has been created. If the supported encryption types for the Active Directory account or the User Login Name get changed, re-create the keytab.
Tip:
You can use the JRE klist tool in <PA>\jre\bin\ to view the contents of the keytab file. For example:
```
klist -k -t <PA>/pa.keytab
```
Ensure that the account is trusted for delegation.
1. Ask an Active Directory administrator use the Active Directory Users and Computers tool to investigate the account's properties.
2. Navigate to the Delegation tab.
3. Ensure that the account is set to Trust this user for delegation to any service (Kerberos).

Configure SPNEGO/Kerberos web authentication for WebSphere Liberty Profile

On <PA_APP_HOST>, create a Kerberos configuration file for WebSphere Liberty Profile.
- Using a text editor, create a text file in the <PA> folder named krb5.conf.
- Copy and paste the following lines into the krb5.conf file.
```
[libdefaults]
    default_realm = <PA_APP_REALM>
    default_keytab_name = FILE:<keytab_file>
    default_tkt_enctypes = aes128-cts-hmac-sha1-96
    default_tgs_enctypes = aes128-cts-hmac-sha1-96
    forwardable = true
    renewable = true
    noaddresses = true
    clockskew = 300
    udp_preference_limit = 1
[realms] <PA_APP_REALM> = 
    {
        kdc = <PA_APP_DOMAIN>:88
        default_domain = <PA_APP_DOMAIN>
    }
[domain_realm]
    .<PA_APP_DOMAIN> = <PA_APP_REALM>
```
- Replace the variables with actual values in your environment and save the file as krb5.conf.
Note:
- The entry for default_keytab_name = must refer to the keytab file that is created in 4.
- The entry for default_tkt_enctypes = aes128-cts-hmac-sha1-96 is an example from Windows 2012 R2. You must use the encryption types that are supported in your environment. Refer to your Active Directory Administrator for that information.
- Depending on the structure of the domain trees in the Active Directory forest, the Kerberos configuration file might require more entries in the [realms] and [domain_realm] sections. Contact your Active Directory Administrator to learn about your domain structure. For more information about the Kerberos configuration file, see The Kerberos configuration file in the WebSphere Application Server Network Deployment documentation.
A configuration based on the example values might look like the following example:
```
[libdefaults]
    default_realm = MYDOMAIN.SAMPLE.COM
    default_keytab_name = FILE:<PA>\pa.keytab
    default_tkt_enctypes = aes128-cts-hmac-sha1-96
    default_tgs_enctypes = aes128-cts-hmac-sha1-96
    forwardable = true
    renewable = true
    noaddresses = true
    clockskew = 300
    udp_preference_limit = 1
[realms] 
    MYDOMAIN.SAMPLE.COM =
    {
        kdc = mydomain.sample.com:88
        default_domain = mydomain.sample.com
    }
[domain_realm]
     .mydomain.sample.com = MYDOMAIN.SAMPLE.COM 
```
Optional: Use the kinit tool in <PA>\jre\bin\ to verify the Kerberos configuration file:
1. Copy the krb5.conf file to <PA>\jre\lib\security folder. The file must be named krb5.conf for this test. When the test is complete, you will remove the file.
2. Request a Kerberos ticket for <PA_SPN>:
```
kinit -k -t <keytab_file> HTTP/<PA_APP_HOST>
```
  For example:
```
kinit -k -t <PA>\pa.keytab HTTP/appsrv1.mydomain.sample.com
```
  The tool confirms that a ticket has been stored to the default ticket cache.
3. Optional: Use the JRE klist tool in <PA>\jre\bin\ to view the Kerberos ticket.
  For example:
```
klist 
```
4. Remove the krb5.conf file from <PA>\jre\lib\security folder to prevent confusion. It is not required in this location anymore.

Modify WebSphere Liberty Profile configuration

The following steps change the WebSphere Liberty Profile configuration file manually. These manual changes are reverted when you make any other changes that require regenerating the application server configuration file in Cognos Configuration. Therefore, you must back up the server.xml file when these manual configuration changes are complete and potentially restore it when Cognos Configuration overwrites the file.

Stop the TM1 Application service.
In a text editor, open the <PA>/wlp/usr/server/tm1/server.xml file.

Add the following feature elements before the </featureManager> element:

<feature>appSecurity-2.0</feature>
<feature>ldapRegistry-3.0</feature>
<feature>spnego-1.0</feature>

Before the <application id=”tm1”...> tag, add the following element:
```
<ldapRegistry
    id="ldap"
    realm="<PA_APP_DOMAIN>"
    host="<PA_APP_DOMAIN>"
    port="389"
    ignoreCase="true"
    baseDN="<base_DN>"
    bindDN="<binduser_accountDN>"
    bindPassword="<binduser_password>"
    ldapType="Microsoft Active Directory"
/>
```
Tip: You can use the IBM WebSphere securityUtility to encode passwords in the server.xml file.

By using the domain name for host, the Microsoft DNS locator feature is used, which prevents a single point of failure in case the referenced Domain Controller becomes unavailable. The baseDN is generally composed of the string cn=Users and a comma-separated list of dc elements that represent each part of the domain name.

For example:
```
Domain: mydomain.sample.com
BaseDN: cn=Users,dc=mydomain,dc=sample,dc=com
```
The binduser_accountDN must be the Distinguished Name of a user account from the referenced domain, which has browsing privileges to all user entries in that domain.

Tip: You can also use the User Principal Name syntax.

For example:
```
cn=admin1,cn=Users,dc=mydomain,dc=sample,dc=com
```
Or
```
bindDN="admin1@mydomain.sample.com"
```
The LDAP registry element tells WebSphere Liberty Profile where to look up information for the user who tries to authenticate. Therefore, the LDAP registry must reference the domain that the authenticating user is from. For users from multiple domains to be able to authenticate, you must define one LDAP registry for each domain. Multiple LDAP registries will automatically become federated without explicit configuration. Add multiple <ldapRegistry> elements as required.
Optional: If user names in Active Directory contain the / character (forward slash), you must add another configuration element because the forward slash is a special character in WebSphere security realms.
After the last <ldapRegistry> element, add the following <federatedRepository> element, which will configure WebSphere Liberty Profile to use the pipe character | instead so that it can tolerate the forward slash in user names.
```
<federatedRepository>
	<primaryRealm name="TM1Web Kerberized" delimiter="|" allowOpIfRepoDown="true">
		<participatingBaseEntry name="<baseDN_ofRegistry>"/>
		<uniqueUserIdMapping inputProperty="uniqueName" outputProperty="uniqueName"/>
		<userSecurityNameMapping inputProperty="principalName" outputProperty="principalName"/>
		<userDisplayNameMapping inputProperty="principalName" outputProperty="principalName"/>
	</primaryRealm>
</federatedRepository>
```
Remember: Adjust the <baseDN_of_Registry> value in the <participatingBaseEntry> element to the value of the baseDN setting of your <ldapRegistry>. If you are using multiple <ldapRegistry> entries, add a <participatingBaseEntry> element for each <ldapRegistry> with the correct value set.

For more information, see Configuring LDAP user registries in Liberty in the IBM Knowledge Center.
To enable SPNEGO/Kerberos based authentication for the WebSphere Liberty Profile, add the following element after the <ldapRegistry> element:
```
<spnego
    id="mySpnego"
    krb5Config="<krb5.conf>"
    krb5Keytab=”<keytab_file>"
    servicePrincipalNames="HTTP/<PA_APP_HOST>@<PA_APP_REALM>"
    canonicalHostName="true"
    disableFailOverToAppAuthType="false"
/>
```
Remember: Replace <krb5.conf> and <keytab_file> with the path to the respective files created earlier.

Configure TM1 Web for WebSphere Liberty Profile security

In the server.xml file, find the TM1 Web application entry and modify it as shown in the following example:

<application id="tm1web"
    location="${wlp.user.dir}/../../webapps/tm1web"
    name="tm1web"
    type=”war” context-root=”tm1web”>
    <application-bnd>
        <security-role name="AllAuthenticated">
             <special-subject type="ALL_AUTHENTICATED_USERS" />
        </security-role>
    </application-bnd>
</application>

Save the server.xml file and back it up.

Add security constraints in the web.xml file of TM1 Web.

On the <PA_APP_HOST>, use a text editor to edit the <PA>/webapps/tm1web/WEB-INF/web.xml file.

Before the first <filter> element, add the following content:

<login-config>
    <auth-method>BASIC</auth-method>
    <realm-name>MYTM1SERVER.EXAMPLE.COM</realm-name>
</login-config>
<security-role> 
    <role-name>AllAuthenticated</role-name>
</security-role>
<security-constraint>
    <web-resource-collection>
        <web-resource-name>tm1web</web-resource-name>
        <url-pattern>/*</url-pattern>
        <url-pattern>/</url-pattern>
        <http-method>POST</http-method>
        <http-method>GET</http-method>
    </web-resource-collection>
    <auth-constraint>
        <role-name>AllAuthenticated</role-name>
    </auth-constraint>
</security-constraint>

Save the file.
Start the TM1 Application server service.
In a browser on a remote computer (not on <PA_APP_HOST>), open a Kerberos enabled browser and access the following address:
```
HTTP://<PA_APP_HOST>:9510/tm1web
```
When the TM1 Server instance is selected, you are authenticated without being prompted.

Configure security mode 2 or 3 to use websheets in Planning Analytics Workspace

If you set up TM1 Server, TM1 Web, and Planning Analytics Workspace Local using security mode 2 or 3 (integrated login), websheets cannot be used in Planning Analytics Workspace.

Note: Websheets will still work when accessed directly in TM1 Web.

To work around this limitation, you can choose to set up another instance of TM1 Web that is not configured for integrated login.

There are three possible scenarios:

If you plan to consume websheets only in Planning Analytics Workspace, you can use a single instance of TM1 Web that is not configured for integrated login.
If you plan to consume websheets only in TM1 Web and not Planning Analytics Workspace, you should set up a single instance of TM1 Web that is configured for integrated login.
If you need to consume websheets in both TM1 Web and Planning Analytics Workspace, you must set up two instances of TM1 Web as follows.
- One instance of TM1 Web must be configured for integrated login that will be accessed directly by users who use TM1 Web.
- A second instance of TM1 Web must be configured without integrated login, and Planning Analytics Workspace must be configured to use this instance of TM1 Web with the Planning Analytics Workspace administration tool or directly in the paw.env file. For more information, see Connect to TM1 and authentication servers. You must not provide this URL directly to users.

Troubleshoot

Make sure that your browser is correctly configured for SPNEGO/Kerberos. For more information, see Enable web browsers for integrated login and Configuring the client browser to use SPNEGO.
Access TM1 Web by host name. Accessing by IP address prevents Kerberos or SPNEGO authentication.
Make sure that the Windows user that you are testing with is not a domain administrator. Domain administrators cannot be delegated through Kerberos.
Make sure that testing is performed on a remote computer. If the browser is run on the same computer as TM1 Web, SPNEGO might fail.

Optional: Edit the logging settings to add output for WebSphere authentication and SPNEGO to WebSphere logs.

Edit the <logging> element in the WebSphere Liberty Profile server.xml file.

For example:

<logging
    consoleLogLevel="WARNING"
    traceSpecification="*=info:com.ibm.ws.security.spnego.
                        *=all:com.ibm.ws.security.wim.
                        *=all:com.ibm.websphere.security.wim.
                        *=all"
    logDirectory="${wlp.user.dir}/../../logs"
    messageFileName="tm1_messages.log"
    maxFiles="2"
    maxFileSize="20"
/>

Stop the TM1 Application service.
Empty the /logs folder.
Start the TM1 Application server to reproduce the issue.

Enable Kerberos logging for the JRE that is running WebSphere Liberty Profile.
1. Stop the TM1 Application Service.
2. In a text editor, open the <PA>/wlp/usr/server/tm1/jvm.options file.
3. Append the following lines:
```
-Dcom.ibm.security.jgss.debug=all
-Dcom.ibm.security.krb5.Krb5Debug=all
```
4. Save the file.
5. Restart TM1 Application Service and reproduce the issue.
Investigate errors with the kinit tool:
- Ensure krb5.conf is copied to the specified location.
- Run ping -4 <PA_APP_HOST> to learn the IP address returned by DNS. Then, run ping -4 -a <IP> to ensure that the IP resolves to the same host name used in PA_SPN.
- Ensure that the keytab file is showing the correct host name.
- Ensure the account that PA_SPN is mapped to was not altered (encryption modes, user login name). If it was altered, re-create keytab and try again.