Share this page
Session Management
Although RESTful applications are ideally stateless, the ALM platform requires sessions to manage locking, client lifetime, and perform other basic tasks. Session management is performed using a cookie named QCSession. ALM returns a QCSession cookie in response to your first authenticated REST call.
Your application should wait for the first QCSession cookie to return before allowing subsequent server calls. Failure to do so may result in your application having several sessions open. After a session is established, always pass the most recently returned QCSession cookie in the header of all actions.
Having more than one session open by an application may interfere with activities that require session-dependent functionality, such as entity locking. In addition, the overhead of opening and maintaining sessions affects server performance.
The same session can be used to access resources of different projects in a site.
Sessions are automatically replaced with new sessions when they expire. The new session is of the same type as the expired session. If a session expires, locks and other session-dependent functionality expire with it.
An application can keep a session alive with periodic calls to the site-session resource. A QCSession cookie is returned by a POST on the site-session resource. The session type can be any application-defined string. You can create a session type for your application and specify a timeout different from the default in the POST operation on the site-session resource.
To protect from Cross-Site Request Forgery (CSRF) attacks:
Create a session type rather than using the default.
Send the X-XSRF-Token header with all requests. See Send X-XSRF-TOKEN header with all requests.
The time-out for a REST Client session is set with the site administration parameter REST_SESSION_MAX_IDLE_TIME. The default is 60 minutes. Other types of clients can use a custom site administration parameter to set a default time-out.
Open a session
Authenticate the user. See Authenticate.
After authentication, get the site-session. For non-default attributes, you can POST a session-parameters XML. See the site-session reference.
POST /qcbin/rest/site-session Cookie: LWSSO_COOKIE_KEY={cookie}; Path=/ Server returns the new session cookie.
HTTP/1.1 200 OK Set-Cookie: QCSession={cookie}; Path=/ Set-Cookie: XSRF-TOKEN={token]; Path =/
A new session in a browser must have a client type that enforces XSRF token validation if there is already an open session in the same browser that enforces XSRF token validation. Add an X-XSRF-TOKEN header to each request with the value from the XSRF-TOKEN cookie returned by the site session creation.
Extend a session
A Get or Put on the site-session resets the session timer.
GET or PUT /qcbin/rest/site-session Cookie: LWSSO_COOKIE_KEY={cookie}; Path=/ Cookie: QCSession={cookie]; Path=/ Server resets the timer. No value is returned.
Close a session
A DELETE on the site-session ends the session.
DELETE /qcbin/rest/site-session Cookie: LWSSO_COOKIE_KEY={cookie}; Path=/ Cookie: QCSession={cookie]; Path=/ Server returns confirmation.
HTTP/1.1 200 OK Set-Cookie: QCSession; Expires...
See also:
