Session Management

Overview

A session in the context of DirX Access is a time-limited connection between the system and its user. The session is irreplaceable for the use of the single sign-on (SSO) mechanism. The session is representing an authenticated identity of the user which can be used for any interaction within the system. During its life-time, the session can collect further information and its termination represents the log-out of the user from the system.

The session representation (session token) is stored at the side of the user. When the token is sent with a request, this request is then processed with the authenticated user in the role of requestor. For the typical scenario of user interacting with the system via browser the token has the form of a string send via the Cookie header of HTTP request.

While this article describes the SSO sessions, the same mechanism is used also in other features of DirX Access, that require sessions (e.g., authentication sessions for Composite authentication methods).

Design

The current solution of session mechanism in DirX Access resembles closely the OAuth federation standard:

  • The whole solution is distributed as opposed to a centralized one, preventing from the centralized entity to represent the single point-of-failure.

  • User authentication leads to creation of new authenticated session and issuance of session token.

  • The session token is returned to the client of the user that performed the authentication and can be stored in the cookie storage.

  • In the typical use case, when the client is a web browser application, each subsequent request to the same domain is automatically enriched by the browser with the cookie containing the session token.

  • The session token is self-contained representation of the session. The user therefore owns the state of its own session.

  • At the server side, the Partial SSO Cache facilitates the logout functionality and enables storing of data unsuitable for the session token (confidential, large, etc.).

attachments/Session Processing
Figure 1. Session Processing

The session token is a JSON Web Token (JWT) formed according to the OAuth-related standard RFC#9068. Its security can be achieved via standard JSON Web Signature (RFC#7515) and JSON Web Encryption (RFC#7516).

Default DirX Access session is passed in the HTTP Cookie header. This header is populated automatically by the browser according to the domains and parameters configurable in DirX Access. Usage of the cookie is a difference to the OAuth protocol, where the token is passed via HTTP Authorization header (which is the competency of the OAuth client). This scenario can be, however, also achieved when configuring DirX Access in the Role of OAuth Resource Server.

Session-related Identifiers

The session is connected to multiple identifiers. This is in contrast to previous versions of DirX Access, where a single random string, named subject ID (or session ID), has been used as the session identifier and correlated directly to the entry in the session cache.

The current session relates to:

  • Session Token - the self-contained JWT representing the session.

  • Session Identifier - the identifier of the session. Is persistent for the duration of the session. This is in contrast to the session token, that can change (e.g., different last access time imprinted into the session token changes means two such tokens are not equivalent even if representing the same session).

  • Token Identifier - identifying the session token. Defined as jti parameter of the JWT, according to the RFC#9068.

Life-cycle

  • Creation

    • Session is created after successful initial authentication of the user. The response to this successful authentication contains the session token, representing the session.

  • Update

    • Each request to the DXA can update the session with correlated information. E.g., request containing step-up SAML authentication will enrich the session with the inbound SAML Assertion, request at the resource protected by risk-based authentication will enrich the session with user-specific data, etc. As the session is a compound information counted from session token and Partial SSO Cache, it is highly configurable where to store this updated information. As a rule of thumb, the large and potentially rarely-used data are stored in the Partial SSO Cache.

    • The session token has an inbuilt iat parameter referencing the time at which it has been issued. Combining this to the PEPs configuration parameter “Session idle timeout”, this means the session token itself expires after the “Session idle timeout” interval since its issuing. From this reason, DirX Access exchanges the session token for a fresh one (with fresh “iat” value) for a new one upon interaction with the user, depending on the “SSO update subject after seconds” parameter. This parameter lets the session token exchange to be performed at least after given number of seconds, to prevent overflooding with new sessions in bulk requests.

    • All issued session tokens that are valid (according to its expiration parameters) can be used within a request.

  • Logout

    • The logout is an action explicitly requested either by the user represented by the session, or by some of interconnected service providers. The logout action corresponds to the removal of the session from the Partial SSO Cache. The Partial SSO Cache is queried with every request at the DXA Server, and if the session doesn’t have its internal representation in it, it is considered being logged out (or expired). The fact the user has logged out is not deducible from the session token itself, as this is valid for its preconfigured validity period.

      DirX Access Server currently has the ability to withstand a short period of DXA Cache Server component outage. During this period, however, all the information in Partial SSO Cache is not available, including the fact the session has been terminated. Therefore, the session validity during this period is determined purely based on the validity of the session token.

  • Expiration

    • Session expiration in DirX Access is bound predominantly to two parameters:

      • Session lifetime

        • The maximum time in seconds since an initial or federated authentication may elapse before the system closes an SSO session created during the authentication.

        • In the session token, the lifetime can found in the DXA-specific claim - sessionExp.

      • Session idle timeout

        • The maximum idle time in seconds since the last processed SSO request that may elapse before the system closes an SSO session created during an initial or federated authentication.

        • In the session token, the idle timeout can be found in the standard JWT expiration claim - exp.

    • For the token to be valid, both of these expiration parameters have to be valid.

    • It may be possible to access SSO Service without getting an access token back. As a result, the requestor may be left with a timed-out token, even though the session has been refreshed. In this case, the token may still be used if it references a valid, accessible session in partial SSO cache.

Security

The session token architecture closely resembles the OAuth JWT access token architecture which is a proven de facto standard.

We shall consider these major security aspects:

  • Integrity

    • The session token is a self-contained representation of a DirX Access SSO session. Therefore, DirX Access has to be able to verify its origin and integrity. This is achieved in the standard way by the JSON Web Token Signing (JWS) mechanism. The session tokens MUST be signed. How to configure the signing can be found in the #Configuration section.

  • Data privacy and Confidentiality

    • Depending on the configuration, the session token might contain private or confidential information. To achieve confidentiality of such tokens, the session tokens shall be encrypted, using the standard JSON Web Token Encryption (JWE) mechanism. How to configure the encryption can be found in the #Configuration section.

    • The encryption might be a performance-demanding feature. The administrator has to balance out the advantage of having the tokens encrypted with the system throughput.

  • Transport security and client-storage security

    • The session tokens are stored and transported using the HTTP Cookie mechanism. As such, there are several configuration parameters that shall be considered:

      • HTTPOnly flag

        • DXA’s parameter “Do set the 'HttpOnly' flag“ of the PEP configuration object makes use of the HTTPOnly flag for given cookie.

      • Secure flag

        • DXA’s parameter “Do require SSL/TLS for cookie transfer” of the PEP configuration object makes use of the Secure flag for given cookie.

      • Scope limitation

        • “Cookie domain name“ and “Cookie path for single sign-on“ enable limiting the requests in which the cookie will be sent.

Content

The content of the JWT consists of mandatory and configurable claims.

Mandatory Claims

The session token JWT contains always following standard parameters

  • iss

    • the issuer of the JWT

    • equal to the “Cluster → Authentication Authority” configuration parameter,

  • aud

    • the audience of the JWT

    • equal to the “Cluster → Authentication Authority” configuration parameter,

  • sub

    • the subject of the JWT

    • equal to the unique name of the authenticated subject

  • iat

    • the timestamp in seconds at which the JWT has been issued

  • exp

    • the timestamp in seconds at which the JWT shall expire

  • jti

    • the unique identifier of this JWT (not the session identifier!)

    • valid only for this given JWT

The session token JWT contains always following DXA-specific parameters

  • sessionId

    • the session identifier

    • the same for all JWTs describing one authenticated session

  • sessionExp

    • the timestamp in milliseconds at which the session shall expire

Configurable Claims

The configuration system of DirX Access enables to imprint any injectable parameter into the session token. The parameters are configured in the following way:

  • In “Subjects → External representation → Request injection”, there can be configured the templates and values to reference the intended content of the claims. To be applicable on the JWT, the “Request injection template” has to be of type “JwtToken”.

  • The configured Request injection templates have to be assigned to the PEP issuing the JWT via the “Request injection template identifiers” parameter.

The configured claims rewrite the mandatory claims if the Keyword parameter equals the identifier of corresponding mandatory claim.

Example

The example of the JWT in its encoded form

eyJ4LXBhcnQiOjI3NiwiYWxnIjoiUlMyNTYiLCJ4NXQjUzI1NiI6InNqRHdOQTdXaTgyRkh5b283TnNNY2FfQUdoTGJfaXhRUWo4T1NLVUlBU0UifQ.eyJhdWQiOiJEaXJYIEFjY2VzcyIsInN1YiI6IkRpclhBY2Nlc3NBZG1pbiIsImlzcyI6IkRpclggQWNjZXNzIiwic2Vzc2lvbkV4cCI6MTY4NTQ3MjI1MzU0NiwiYXNzdXJhbmNlTGV2ZWwiOiIwIiwic2Vzc2lvbklkIjoiOTEwLWdleXRpLW95bHh6dnF1aXg3dGo1NTdzdHFpd2w0eWJvbzc1d3BsZm5sYjdoNHlyZXJqY2E1cGY3dnBlIiwiYXV0aG5UaW1lIjoiMTY4NTQyOTA1MzUxNSIsImF1dGhuTWV0aG9kcyI6IkJhc2ljIEF1dGhlbnRpY2F0aW9uIiwiZXhwIjoxNjg1NDcyMjc3LCJpYXQiOjE2ODU0MjkwNzcsImp0aSI6Im9tYXJ3cjN5aWlhanhhNnFtemY2eTNlaWs0cDJidjN5eWp4enFudnhoZ3F3a2d6emVoamZrZjR6aG1oM3ltN2dndmVtcjdnNmZkY2o3bDd6ZnJsZHN0Y3E1aWhyaGRqcXB3aG4zY2kifQ.FCPjOPN2G3q4lSOSKmxdFIkJcX2Wvi47vulW2ANTFe7um5RZYn3GXjRP7ctxGNsIGZwNOzrJy6citk3won8DF2a_Tr6PJk5a_X3mTtppIz4Aea8ey_OVWGYmzizIbeSCyXS5A73Oz8bk3L6R1RvTuDf8hCp_gWQNFECEx0us7OFkBKlv3KNrXzRr6b9bqPScwT9ws_z1kXz7Nbv5dnhtwdgv5SqF2l8478M_DA8Q0iStmpMa4TPJfDdozpdHQPWGjUMiqJeS1eNra8_YoD7lmebynz4O0FRK_-oSFouyvokRP_zNNc7_A2qo6ee07n_V51sY-mLc7JSgohmGn_On8Q

followed by an example content of the JWT payload

{
  "aud": "DirX Access",
  "sub": "DirXAccessAdmin",
  "iss": "DirX Access",
  "sessionExp": 1685472253546,
  "assuranceLevel": "0",
  "sessionId": "910-geyti-oylxzvquix7tj557stqiwl4yboo75wplfnlb7h4yrerjca5pf7vpe",
  "authnTime": "1685429053515",
  "authnMethods": "Basic Authentication",
  "exp": 1685472277,
  "iat": 1685429077,
  "jti": "omarwr3yiiajxa6qmzf6y3eik4p2bv3yyjxzqnvxhgqwkgzzehjfkf4zhmh3ym7ggvemr7g6fdcj7l7zfrldstcq5ihrhdjqpwhn3ci"
}

Configuration

Contemporary infrastructure (browsers, load balancers, etc.) typically limit the size of the HTTP Cookie header to 4kB. Please, be aware of this when configuring the content of the JWT.

Content

For more information, please, see the Configurable Claims section.

Signing and Encryption

The signing and encryption is configurable via the “Cluster → Crypto container identifiers” parameter.

  • For the signing to be configured, there has to be at least one Crypto container referenced with entry of type SIGNING_KEY_PAIR and corresponding entry of type VERIFICATION_CERTIFICATE.

  • For the encryption to be configured, there has to be at least one Crypto container referenced with entry of type DECRYPTION_KEY_PAIR and corresponding entry of type ENCRYPTION_CERTIFICATE.

HTTP Cookie

The PEP configuration object enables to configure the Cookie-specific parameters. For more information, please, see the #Security section.

For security reasons, please, don’t use the URL rewriting feature.

JWT compression

DirX Access provides an option to compress JSON Web Tokens, found under the “SSO Service” tab of “Cluster” configuration, in order to minimize the impact of bloated tokens. The “JWT compression mode” is disabled by default and has two modes. Compressed tokens are always accepted and decompressed regardless of which option is selected.

  • The ENCRYPTED mode only applies to encrypted tokens according to RFC#7516 and RFC#1951. The header is enriched with "zip": "DEF" parameter.

  • When ALL mode is selected, encrypted tokens are compressed in the same way, but unencrypted tokens are also compressed with a custom method and enriched with "zip": "CST" parameter.

Only the payload is compressed, header always remains uncompressed in order to be readable. Compression is expected to shorten tokens by ~20%, increasing to ~50% for very large tokens. This varies depending on the payload data complexity.

It must be emphasized that the best way to keep JWTs short is to minimize the amount of data saved in the payload. Remove unnecessary claims when possible and keep keywords short.

DirX Access in the Role of OAuth Resource Server

DirX Access Server can also take on the role of an OAuth 2.0 Resource Server (RS), providing an alternative to the cookie-based SSO session described above: instead of a session cookie, the requestor subject is resolved from a bearer JWT access token transported via the HTTP Authorization header, following the standard OAuth architecture and flows (RFC#6750, RFC#9068).

For the architecture, request-processing/subject-resolution mechanics, and configuration reference, see DirX Access in the Role of OAuth Resource Server.