Project

General

Profile

Wiki » Documentation » Installation Configuration and Administration Guide » Administration REST API »

Session Management API

This API provides a way to fully control the sessions which are created by the server, ranging from getting information about to deleting one or all of them. Furthermore, it provides a way to enable session-locking, which tells the server to ignore incoming session requests.

The work on this feature was implemented in #9355.

Configuration

Session Management API is a sub-module of Administration_REST_API. In order to enable the session support in FWD, the global REST API must be enable. Please see the REST API Setup/Configuration. There are no additional requirements for this sub-module.

Add Permissions for the Session Admin API

In order to have access to the session administration API, you need to add permissions. This is done via ACLs in the following manner:

<node class="container" name="security">
  <node class="container" name="acl">
    <node class="container" name="webservice">
      <node class="container" name="000100">
        <node class="resource" name="resource-instance">
          <node-attribute name="reference" value="ADMIN:GET:/admin/sessions"/>
          <node-attribute name="reftype" value="FALSE"/>
        </node>
        <node class="webServiceRights" name="rights">
          <node-attribute name="allow" value="true"/>
        </node>
        <node class="strings" name="subjects">
          <node-attribute name="values" value="restAdmin"/>
        </node>
      </node>
      <node class="container" name="000200">
        <node class="resource" name="resource-instance">
          <node-attribute name="reference" value="ADMIN:GET:/admin/sessions/.*"/>
          <node-attribute name="reftype" value="FALSE"/>
        </node>
        <node class="webServiceRights" name="rights">
          <node-attribute name="allow" value="true"/>
        </node>
        <node class="strings" name="subjects">
          <node-attribute name="values" value="restAdmin"/>
        </node>
      </node>
      <node class="container" name="000300">
        <node class="resource" name="resource-instance">
          <node-attribute name="reference" value="ADMIN:DELETE:/admin/sessions"/>
          <node-attribute name="reftype" value="FALSE"/>
        </node>
        <node class="webServiceRights" name="rights">
          <node-attribute name="allow" value="true"/>
        </node>
        <node class="strings" name="subjects">
          <node-attribute name="values" value="restAdmin"/>
        </node>
      </node>
      <node class="container" name="000400">
        <node class="resource" name="resource-instance">
          <node-attribute name="reference" value="ADMIN:DELETE:/admin/sessions/.*"/>
          <node-attribute name="reftype" value="FALSE"/>
        </node>
        <node class="webServiceRights" name="rights">
          <node-attribute name="allow" value="true"/>
        </node>
        <node class="strings" name="subjects">
          <node-attribute name="values" value="restAdmin"/>
        </node>
      </node>
      <node class="container" name="000500">
        <node class="resource" name="resource-instance">
          <node-attribute name="reference" value="ADMIN:PUT:/admin/sessions/lock"/>
          <node-attribute name="reftype" value="FALSE"/>
        </node>
        <node class="webServiceRights" name="rights">
          <node-attribute name="allow" value="true"/>
        </node>
        <node class="strings" name="subjects">
          <node-attribute name="values" value="restAdmin"/>
        </node>
      </node>
    </node>
  </node>
</node>

For the definition of admin-rest FWD user, please see the REST API Setup/Configuration.

By setting these, you will allow requests of the following types at the following paths:

  • GET at /admin/sessions, which is used for listing all the active sessions.
  • GET at /admin/sessions/<session_id>, for listing the information of the given session.
  • GET at /admin/sessions/lock, which is used to enable session-locking.
  • GET at /admin/sessions/unlock, which is used to disable session-locking.
  • DELETE at /admin/sessions/all, which is used for deleting all active sessions.
  • DELETE at /admin/sessions, which is used for deleting only the given sessions.

Double-check the paths leading to the options in order for the server to read them correctly!

API routes

The Session Management API has the following capabilities:
  • Login: the login and logout operations are provided by the main module. For an example of how this is achieved, take a look at REST Admin Authentication.
  • List all sessions: by performing a GET request at /admin/sessions. The header must contain the FwdSessionId token. No body is required.
    • The response body will be a JSON containing all the active sessions.
    • The endUser property reports the authenticated end user name as supplied by the SSO authenticator. It is useful for telling end users apart when clients are spawned under a shared OS account, in which case osUser would be identical for all of them. It is null unless the SSO authenticator populates it: to populate it, the authenticator needs at least a setEndUser call on the authentication result it returns (otherwise the framework falls back to the OS user provided at login).
    • Example:
    • Raw request/response:
  • List a single session: by performing a GET request at /admin/sessions/<session_id>. The header must contain the FwdSessionId token. No body is required.
    • The response body will be a JSON containing the information of the given session, or an empty JSON if the session does not exist.
    • The <session_id> which needs to be provided is always equal to the sessionTokenID property of a session. It can be retrieved by performing a GET all.
    • Example:
    • Raw request/response:
  • Get Session Locking Status: by performing a GET request at /admin/sessions/lock. The header must contain the FwdSessionId token. No body is required.
    • The response body will be a JSON containing current status of the lock. TRUE if no more sessions can be launched by the FWD server or FALSE otherwise.
    • Example:
    • Raw request/response:
  • Enable/Disable session-locking: performing a PUT request at /admin/sessions/lock. The header must contain the FwdSessionId token. The body should contain: { "lock" : true } for locking or { "lock" : false } for unlocking the sessions.
    • The response body will be a JSON containing current status of the lock. FALSE if the FWD server can launch new sessions or TRUE otherwise.
    • Example:
    • Raw request/response:
  • Delete all sessions: by performing a DELETE request at /admin/sessions. The header must contain the FwdSessionId token. No body is required.
    • The response body will be a JSON containing the sessions which could be successfully terminated. The ids returned match the sessionTokenID property.
    • Example:
    • Raw request/response:
  • Delete a specific session: by performing a DELETE request at /admin/sessions/<session-id>. The header must contain the FwdSessionId token. The body is ignored and is recommended to be empty.
    • The response body will be a JSON containing the sessions which could be successfully terminated.
    • Example:
    • Raw request/response:
  • Delete given sessions: by performing a DELETE request at /admin/sessions. The header must contain the FwdSessionId token. The body must be a JSON that follows this pattern:
    {
    "sessions": [session_token_ID1, session_token_ID2]
}

    where the session token ids are integers that match the sessionTokenID property. This can be retrieved by performing a GET all.
    • The response body will be a JSON containing the sessions which could be successfully terminated.
    • Example:
    • Raw request/response:
      Note: By comparing the ids sent with the ids received, you can find out the sessions which could not be killed.

© 2024-2025 Golden Code Development Corporation. ALL RIGHTS RESERVED.