Managing Sessions

Describes how to configure session parameters for the Control System and REST clients.

About this task

You can enable session replication to avoid having the client re-authenticate when routed to a different apiserver.

Enabling Session Replication for the Control System

About this task

When a client establishes a connection with an apiserver (node on which the Control System is installed), the session information is returned in the response. If you have set up multiple apiservers, you can configure the system to store the session information in a database for resending with further requests. For example, in the event of a node failure, you can send the session information with further requests so that the client uses the same session and does not re-authenticate when routed to a different apiserver.

To configure the host for session replication, perform the following steps on all the nodes running the apiserver:

Procedure

  1. Open the /opt/mapr/apiserver/conf/hazelcast.xml file and set the value for the com.mapr.admin.lib.JsonDbMapStore parameter to true.
    For example, your setting in the file for this parameter should look similar to the following (as shown in bold): 
    <map-store enabled="true">
   <class-name>com.mapr.admin.lib.JsonDbMapStore</class-name>
</map-store>
    By default, this is disabled (false) and the session information is not stored in the DB.
  2. Specify the hostname of the apiservers (cluster of nodes) where the session information can be sent with the request.
    For example, to specify the list of apiservers, modify the following in the /opt/mapr/apiserver/conf/hazelcast.xml file: 
    <network>
   <join>
      <multicast enabled="false"></multicast>
      <tcp-ip enabled="false">
         <member>hostname.example.com</member>
         <member>hostname.example.com</member>
      </tcp-ip>
   </join>
</network>
    The default value for both multicast and tcp-ip is false. If you set the value for multicast to true, all apiservers on the cluster are automatically added to the list of apiservers where re-authentication is not required once a connection is established. This is not recommended. Instead, set the value for tcp-ip to true and explicitly specify the hostnames of the apiservers (cluster of nodes) where re-authentication is not required once a session is established.

    For example, your entry in the file should look similar to the following (as shown in bold):

    <network>
   <join>
      <multicast enabled="false"></multicast>
      <tcp-ip enabled="true">
         <member>abc.example.com</member>
         <member>xyz.example.com</member>
      </tcp-ip>
   </join>
</network>
  3. Save and close the /opt/mapr/apiserver/conf/hazelcast.xml file.
  4. Open the /opt/mapr/apiserver/conf/web.xml file and specify the domain name of the cluster to cache using the cookie-domain parameter.
    For example, your setting in the file should look similar to the following (as shown in bold):
    <init-param>
   <param-name>cookie-domain</param-name>
   <param-value>.example.com</param-value>
</init-param
  5. Save and close the /opt/mapr/apiserver/conf/web.xml file.
  6. Restart the apiserver by running the following command: 
    service mapr-apiserver start

Configuring Sessions for REST Clients

About this task

This section describes how to get a session cookie, which can be used on subsequent requests. This cookie, valid for up to 30 minutes by default, contains the session ID and can be used to verify the identity of further API calls.

To get and save a cookie, which you can then use with subsequent requests, for:

  • Basic authentication, submit a request similar to the following: 
    curl -X POST -c <cookiefile-location>  https://<webserver-host>:8443/login -d 'username=root&password=mapr'
  • SPNEGO, submit a request similar to the following: 
    curl --negotiate -u : -b <cookiefile-location> -c <cookiefile-location> https://&lt;web server node>:8443/rest/&lt;API call> -k -v

The contents of the cookie file may look similar to the following:

cat /tmp/cookiejar.txt
    # Netscape HTTP Cookie File
    # https://curl.haxx.se/docs/http-cookies.html
    # This file was generated by libcurl! Edit at your own risk.

    #HttpOnly_<webserver-hostname>  FALSE  /  TRUE   1509486224  MAPR.APISERVER.JSESSIONID  node014ukard563rhu1ns8umn2s6uft3709.node0
    #HttpOnly_<webserver-hostname>  FALSE  /  FALSE  0	    MAPR.APISERVER.SESSIONID

Configuring Session Timeout

About this task

For a longer session, modify the value of the session-timeout parameter in the /opt/mapr/apiserver/conf/web.xml file. The value for this parameter is in minutes. The session-timeout parameter in the web.xml file is applicable for all clients. If no REST API calls are made for 30 minutes (default value) by a client, then the apiserver will terminate the session for that client.
IMPORTANT
The session-timeout parameter in the web.xml file is NOT related to the Session Rate setting in the Control System. The Session Rate setting in the Control System sets the idle timeout parameter for the Control System ONLY. If there is no activity on the Control System within this timeout period, the client sends a logout request to log out from the Control System.

Procedure

  1. Open the /opt/mapr/apiserver/conf/web.xml file.
  2. Change the value of the session-timeout parameter.

    For example, in the /opt/mapr/apiserver/conf/web.xml file, change the parameter shown in bold:

    <session-config>
   <cookie-config>
      <http-only>true</http-only>
      <max-age>86400</max-age>
      <name>MAPR.APISERVER.JSESSIONID</name>
      <!-- <secure>true</secure> -->
   </cookie-config>
   <session-timeout>30</session-timeout>
</session-config>