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
Unauthorized response code and sets the
WWW-Authenticate header to
indicate the authentication method that is supported by the server.
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.
Supported security modes
The following security modes are supported for TM1 REST API clients.
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
Authorizationheader in the following format:
Authorization: Basic base64(user:password)
- Mixed (Windows Integrated Authentication and Basic)
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-Authenticateheaders. 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)
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-Authenticateresponse header is similar to the following example:
To authenticate, the server expects an
Authorizationheader 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 Unauthorizedagain, setting the
WWW-Authenticateheader 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-Authenticateheaders returned on an HTTP request where authentication fails or is not present include the
ClientCAMURIthat 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-Authenticateheader as in:
WWW-Authenticate CAMPassport http://sottprismdev1.canlab.ibm.com:8080/ibmcognos/cgi-bin/cognos.cgi, CAMNamespace
The URI passed as a parameter for
ClientCAMURIas 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_passportcan be passed to TM1 for authentication by using the following
Authorization: CAMPassport cam_passport
If you know how to log in to CAM with credentials, you can send an
Authorizationheader 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
ServerCAMURIin 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.
- 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.
- The server authenticates the credentials of the administrator, verifying that the requester is an administrator and therefore allowed to impersonate another user.
- The server makes the specified client the active client on that session.
- If the impersonation fails, you get an error and the administrator is not logged on.
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.
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  DEBUG 2019-07-02 12:17:06.246 TM1.Login User Sa authenticated, attempting to impersonate user Planner 140485855258368  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  DEBUG 2019-07-02 14:28:27.793 TM1.Login Login attempt by CAM account: CAMID("TM1QA:u:4cbd362ce23ee1438d84d004eb4cf345") 7852  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  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
Server changes the default
timeout value. If a session times out, requests made with the previous session ID return
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
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:
Close action or the
logout request succeeds, the
client must re-authenticate to access protected resources.