Session Management and Configuration

Understading session management and configuring xAPI settings.
Tags:
Categories:

Session Management

The External API (XAPI) uses a token-based access model in order to authorize access to its endpoints. Understanding the security and session management architecture ensures that the least disruptions occur while using the XAPI.

Users, Tokens, and Sessions

The three main components of the XAPI security framework are:

  1. EPASS Users
  2. Web Tokens
  3. Web Sessions

EPASS Users

The user name and password to be used to login to the XAPI are maintained within EPASS. The users are maintained in the same area as all of the standard EPASS users except that they must be of type: “API User”. This “API User” type is permitted access to the XAPI; however, it cannot be used to login to the EPASS Windows application.

EPASS XAPI accounts are configured in the standard admin area of EPASS:

epass_userscreen.png

JSON Web Tokens

The XAPI uses JSON Web Tokens (JWT) to permit access to its web methods. In summary, an application logs into the XAPI using the EPASS user and password and then receives a JWT token. Subsequent calls to the XAPI require the calling application to pass the JWT token in the BEARER authorization header.

The session process involves two tokens: the session token (referred to just as the token), and the refresh token. As far as the application is concerned the session token is the only token; however, in the case that the token expires the application can quickly re-establish itself with a new session token without having to resent the user/password credentials.

More about JWT Tokens

More about Refresh Tokens

Below is a drawing showing the processes involved with managing the token states.

tokens_overview.png

Web Sessions

An XAPI session is simply a high-level abstraction of the XAPISession table, session token, and refresh tokens. Each session has a corresponding row in the XAPISession table of which there are some details about the session. At any given point, deleting a record in the XAPISession table will result in the immediate invalidation of the session and all access will be revoked, including the ability to use the refresh token.

Configuration

The EPASS External API (XAPI) is configured through a single JSON config file: “appsettings.json”. This file is located in the root of the installation folder and contains a variety of important settings.

appsettings.json

{
  ...
  "XAPI": {
    "LogEnabled": true,
    "LogInfo": true,
    "LogErrors": true,
    "LogDebug": true,
    "LogFileLocation": "",
    "TokenExpiryInMinutes": 1440,
    "RefreshExpiryInMinutes": 1440,
    "TrackStatistics": true,
    "TrackStatisticsSize": 500,
    "TrackStatisticRequest": true,
    "TrackStatisticResponse": true,
    "CachedLookupsThreshold": {
      "base": 1000,
      "varAR": 1000,
      "Branch": 1000,
      "Misc": 1000,
      "ModelEcoFee": 1000
    },
    "CachedLookupsTimeInSeconds": 3600
  },
  "Licensing": { ignore },
  "ConnectionStrings": {
    "DBName": "Server=<IP>;Port=<port>;User=<dbuser>;Password=<dbpassword>;Namespace=<dbname>;Max Pool Size = 5;Min Pool Size = 1;"
  }
}

xAPI Object

Logging

Attribute Type Description
Log Enabled boolean Set to ‘true’ if you want to enable logging. If the value is ‘false’, all other logging settings are simply ignored. The system will write log entries to the “ErrLog” table in the EPASS database; however, if the database cannot be accessed then the error is written to a log file in the root of the WebAPI installation folder.
LogFileLocation string The name of the file that a log entry is written to only if the application cannot access the database. This log file should typically be empty or non-existent.

Token/Session

Attribute Type Description
TokenExpiryinMinutes Integer When a user logs into the XAPI they are granted a session token. This value dictates the duration of time that the session token is valid. After a token expires, the refresh token can be used to generate another token. It is recommended that this is a fairly short-lived token. The actual number of minutes is relative to the risk of a data breach.
RefreshExpiryInMinutes integer This indicates the number of minutes a refresh token should be valid. This can be a long duration and should be considerably longer than the TokenExpiryInMinutes value. This token is explained more in the Session Management section of this wiki.

Statistics

The statistics feature allows the recording of requests and responses which provides programmers with the ability to view the raw request data that was received by an endpoint and the raw response data sent back to the caller. The ‘track statistics’ feature is not intended for production usage but rather for debugging a particular issue.

Attribute Type Description
TrackStatistics boolean Enable or disables the tracking feature.
TrackStatisticsSize integer The maximum number of rows allowed to exist in the statistics table. Rows oldest are deleted as this limit is reached.
TrackStatisticRequest boolean Writes the quest raw data to the XapiSessionStatistic row.
TrackStatisticResponse boolean Writes the response raw data to the XapiSessionStatistic row truncated to 1,500 characters.

Cached LookUps

To reduce stress on the database and increase access speed, the system can locally cache the data for commonly used tables containing data that doesn’t change very often. You can designate which data tables should get cached by including their name in appsettings.json. The tables that support caching are mostly found in EPASS under System Maintenance > Tables.

Attribute Type Description
CachedLookupThreshold string:integer The table names that the system should cache and the threshold amount. If the amount of records returned from the table exceed the threshold amount, the data won’t be cached.
CachedLookupsTimeinSeconds integer The window of time (in seconds) that the xAPI extracts data from the cache rather than the database. Once this time limit expires, the xAPI re-caches data from the database at the next request.

ConnectionStrings Object

The ConnectionStrings sections may have an unlimited number of databases configured. During the login process, the calling application supplies a user, password, and organization id (known as the database name). Each database name must be unique. The following is a sample database string for a database called “DEMO”:

"DEMO": "Server=127.0.0.1;Port=12345;User=User1;Password=abcdef;Namespace=DEMO;Max Pool Size = 5;Min Pool Size = 1;"

Server: IP address to DNS Name of the database server.

Port: Port number permitted for connections to the database server.

User: This is a database user and not an EPASS user.

Password: The password field is unique; it allows a person to type in a plain text password such as “MyPassword123” and once the application starts it will encrypt the password and write the cipher text back into this connection string.

Max Pool Size: This will throttle the maximum number of database connections permitted by the XAPI application. If this number is reached, subsequent requests will be delayed while waiting for a free connection.

Min Pool Size: This is the initial size of the application pool. This will only make a difference in situations where the application is requiring quick responsiveness after an application restart.