HTTP authentication

To use the TM1 REST API, your client application needs to authenticate to the TM1 server.

When you make a request without the appropriate authentication, the TM1 server returns a 401 Unauthorized response code and sets the WWW-Authenticate header to indicate the authentication method that is supported by the server.

The IntegratedSecurityMode parameter that is set in the tms1.cfg file for each server specifies which authentication modes are supported by that server.

For more information about the IntegratedSecurityMode parameter, see the IBM Cognos TM1 Installation and Configuration Guide.

You can use the Logger entity to retrieve and update tm1s-log.properties file settings. For more information, see TM1 settings.

Supported security modes

The following security modes are supported for TM1 REST API clients:

Basic IntegratedSecurityMode=1

Standard TM1 authentication is mapped to HTTP Basic authentication where the user name and password are passed on to the TM1 server.

WWW-Authenticate: Basic Realm="TM1"

The server expects an Authorization header in the following format:

Authorization: Basic base64(user:password)

Mixed (Windows Integrated Authentication and Basic) IntegratedSecurityMode=2

This mode mixes both TM1 standard authentication with Windows Integrated Authentication (WIA).

To be able to indicate to the client that both modes are supported, the server returns two WWW-Authenticate headers. Because it is the preferred authentication mode in this case, the header the Windows Integrated Authentication mode is returned first, and then, the header that provides basic TM1 authentication is returned.

Windows Integrated Authentication (Microsoft Windows only) IntegratedSecurityMode=3

The server supports Windows Integrated Authentication (WIA) only. In this case, the server follows SPNEGO-based Kerberos and NTLM HTTP Authentication as outlined in RFC-4559. The WWW-Authenticate response header is similar to the following example:

WWW-Authenticate: Negotiate

To authenticate, the server expects an Authorization header to start the authentication sequence in the following format:

Authorization: Negotiate base64(token)

The authentication process might require multiple round-trips to complete the authentication sequence. Intermittent results are returned with a 401 Unauthorized again, setting the WWW-Authenticate header again to Negotiate, but this time followed by the base64 encoded token to be used to continue the authentication process.

IBM Cognos BI or Cognos Authentication Manager (CAM) authentication (IntegratedSecurityMode=4 or 5)

When the TM1 Server uses CAM authentication or a combination of CAM and Native authentication, the server authentication fault response header includes a CAM client URI for the client to use to obtain an authentication token (CAM Passport). This approach eliminates the need to return the security mode to set up authentication negotiation.

If the server security mode is set to CAM, the WWW-Authenticate headers returned on an HTTP request where authentication fails or is not present include the ClientCAMURI that is specified in tm1s.cfg file, which is necessary to log in.

The TM1 server supports CAM authentication that is based on a CAM passport or CAM credentials (a namespace, user name and password pair). Therefore, the server returns a WWW-Authenticate header as in:

WWW-Authenticate CAMPassport http://sottprismdev1.canlab.ibm.com:8080/ibmcognos/cgi-bin/cognos.cgi, CAMNamespace

The URI passed as a parameter for CAMPassport is the ClientCAMURI as configured for that TM1 server. This URI must point to a Cognos BI instance that can be used to authenticate against by following the URI. For more information about authenticating against CAM and how to integrate with it, see the IBM Cognos BI Software Development Kit.

After successful authentication, the cam_passport can be passed to TM1 for authentication by using the following Authorization header format:

Authorization: CAMPassport cam_passport

If you know how to log in to CAM with credentials, you can send an Authorization header that contains a base64-encoded user name, password and CAM namespace pair such as:

Authorization: CAMNamespace base64(user:password:namespace)

The TM1 server validates the passport or the CAM namespace credentials against the URL specified by ServerCAMURI in the tm1s.cfg file.

Session management

A browser cookie that contains a session ID gets set during the authentication process. This session ID cookie must be passed back to the server on every subsequent request in the HTTP request header.

By default, authenticated sessions time out after 20 minutes of inactivity. Setting the HTTPSessionTimeoutMinutes parameter in the tm1s.cfg file on the TM1 server changes the default timeout value. If a session times out, requests made with the previous session ID return 401 Unauthorized.

Closing a session

To close a session, call the Close action on the Session object. If you are using 10.2.2 Fix Pack 5 or later, you can use the ActiveSession singleton as the Session object.

If you are using a version earlier than 10.2.2 Fix Pack 5, you can log out of the current session (specified by the TM1SessionID cookie) by using the following request:

GET /api/logout

When the Close action or the logout request succeeds, the client must re-authenticate to access protected resources.

Note: In your browser, you might get the impression that the logout never happened. Browsers cache the credentials and re-authenticate automatically when the next "401 Unauthorized" response is returned by the server, which makes the re-authentication seamless.