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.

NOTE: A single session in the XAPI is mapped to one “API User”. This means that if there is more than one application logging into the XAPI, each application should use its own ePASS “API User” account. This is because when a XAPI login occurs, any previous logins are cancelled and replaced with the next session information.

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.

What’s Next?

Link#1

Link #2