Authenticating and managing sessions

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 Planning Analytics Local Installation and Configuration documentation.

You can use the Logger and ServerSettings entities to retrieve and update TM1 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® Analytics 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, 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 Analytics server 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 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.

Impersonating a user

With TM1 version 11.1.0 or later, an administrator can create a session impersonating another user. After the session is created, it appears as if that user is connected to the TM1 Server and all requests that are made on that session are executed in that user's context. TM1 Server versions 11.0.0 or earlier silently ignore this header/query option.

  1. On the first/initial request on a new connection, you pass an HTTP header named "TM1-Impersonate" or a query option named "!impersonate" with the value of the user you want to impersonate.
    Note: Don't pass a session cookie for an already authenticated session.
  2. The server authenticates the credentials of the administrator, verifying that the requester is an administrator and therefore allowed to impersonate another user.
  3. The server makes the specified client the active client on that session.
  4. If the impersonation fails, you get an error and the administrator is not logged on.

Logging impersonation

With TM1 Server version 11.5.0 or later, when an administrator uses impersonation mode in the TM1 REST APIs to log in as another user in a session, an entry is recorded in the TM1.Login logger.

The log entry in the TM1.Login logger indicates that the administrator has successfully authenticated and is impersonating another user. The next message in the log indicates that the user has successfully logged in.

All actions performed in the session reflect the impersonated user's transactions and object security.

Example TM1.Login

In the following example, the log shows user SA impersonating user Planner. The first entry in the log identifies the impersonation. After this point, TM1 Server treats every subsequent action as if user Planner is logged in.

140485855258368   [3]   DEBUG   2019-07-02 12:17:06.246   TM1.Login   User Sa authenticated, attempting to impersonate user Planner
140485855258368   [3]   DEBUG   2019-07-02 12:17:06.249   TM1.Login   Login Success: User Planner

Example TM1.Login with Cognos Authentication Manager (CAM) authentication

In the following example, the log shows an impersonation example using Cognos Authentication Manager (CAM) authentication.

7852   [2]   DEBUG   2019-07-02 14:28:27.793   TM1.Login   Login attempt by CAM account: CAMID("TM1QA:u:4cbd362ce23ee1438d84d004eb4cf345")
7852   [2]   DEBUG   2019-07-02 14:28:27.794   TM1.Login   User TM1QA/_CAMID(_TM1QA_u_4cbd362ce23ee1438d84d004eb4cf345_) authenticated, attempting to impersonate user TM1QA/_CAMID(_TM1QA_u_629a98019c3c8a4688a09d42269f2eab_)
7852   [2]   DEBUG   2019-07-02 14:28:27.830   TM1.Login   Login Success: User TM1QA/_CAMID(_TM1QA_u_629a98019c3c8a4688a09d42269f2eab_)

Managing a session

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.