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.

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

DirX Access in the Role of OAuth Resource Server

DirX Access Server does provide multiple endpoints via its REST APIs. To provide the standard approach to protection of REST APIs, DirX Access Server can take on the role of OAuth Resource Server enabling to follow the standard OAuth architecture and flows. The OAuth Authorization Server in this scenario can (but don’t need to) be provided by the DirX Access Server itself. The client applications can (but don’t need to) be also of DirX Access origin - e.g., all Single-page applications, such as DirX Access Manager and Credentials Manager.

attachments/Untitled Diagram-1685442946555.drawio
Figure 2. DirX Access server as OAuth Resource Server

Following diagram depicts the DirX Access in the role of OAuth Resource Server in the scenario with DXA Manager.

attachments/Untitled Diagram-1685443565137.drawio
Figure 3. DirX Access in the role of OAuth Resource Server in the scenario with DXA Manager

The OAuth Resource Server PEPs protecting the DXA Services container can take on the role of OAuth Resource Server. This role is enabled by configuring a reference to any “OAuth RS authentication method identifier”. If such a reference exists for given PEP, it behaves as a standalone OAuth Resource Server with a resource identifier equal to the “Resource URI” parameter of the corresponding authentication method. The whole algorithm of request processing by such PEPs is then highly dependent on the authentication method configuration.

The access token is transported via the Authorization header or as a Form-encoded body parameter, according to the RFC#6750. Although the Authorization Header theoretically does not impose a size limit on the JWT, in practice the browsers do limit this element on 8KB.

If the “OAuth Resource Server Authentication Method” is configured, the resolution mechanism that assigns a requestor subject to the request is altered comparing to the standard processing. The most influencing part of the configuration is represented by the “Sessionless” property:

  • If switched off, the JWT is used for the primary subject resolution, while the request processing still includes the standard SSO mechanism with the subject resolution via the session cookie and authentication mechanism via existing policies. The standard SSO mechanism can also provide the complete subject resolution when no JWT is in place. Furthermore, the complete subject (including the part resolved from JWT; for example, JWT roles) is imprinted into the session cookie later and can be used during the whole session lifetime.

  • If switched on, the JWT is the only source of the subject. No SSO session is created and the JWT must be present upon each request. Even in this case the internal subject can incorporate additional information. The sub parameter can be used for retrieval of the persisted user data from the user repository, if the “Do correlate user account” and “User account correlation field” properties are configured appropriately. Furthermore, the roles and groups from the JWT can be translated into internal roles and groups, if the “Imprint roles” and “Imprint groups” properties are switched on.

In both cases, if there’s no means to resolve the subject, DirX Access responds with the 401 response according to the RFC#6750: WWW-Authenticate: Bearer header with realm equal to the resource URI that shall be imprinted into the “audience” property of the JWT.

The JWT validation process follows the RFC#9068. Namely, the encrypted JWTs are decrypted, signed JWTs verified. Subsequently, the audience element is compared to the resource URI parameter configured for corresponding authentication method. The scopes parameter is not determining for the validation process.

OAuth Protected Resource Metadata

In certain scenarios, there’s a necessity for OAuth 2.0 Clients or authorization servers to retrieve the metadata of an OAuth Protected Resource. DirX Access facilitates this functionality by enabling the publication of metadata for each protected resource at the well-known address corresponding to the resource’s endpoint.

This implementation adheres to the specifications outlined in the draft documented in OAuth 2.0 Protected Resource Metadata. However, it’s important to note that this specification is currently in a draft state and subject to potential changes.

DirX Access supports the following metadata paths for protected endpoints:

  • /.well-known/oauth-protected-resource - The metadata for each resource is made available at the specific address of the protected endpoint under this path. For instance, an example of such an address could be https://my-server.my-company.example:10116/odata4/config/.well-known/oauth-protected-resource .

  • /.well-known/oauth-protected-resource/jwks.json - path, where information about the public keys of the resource can be accessed. This address is part of the server’s metadata.

It’s crucial to acknowledge that at the time of composing this section, the URI ./oauth-protected-resource isn’t an officially registered well-known URI at the IANA registry. However, it’s anticipated that this path will likely be registered in the future once the draft progresses and is published as an RFC.

For scenarios where the metadata needs to be available without authorization to any clients or servers, it’s recommended to incorporate the /.well-known/oauth-protected-resource path to the exclusion resource filter of the PEP protecting the resource. Additionally, consider also including /.well-known/oauth-protected-resource/jwks.json path.

Configuration

PEP

To enable the role of OAuth Resource Server, the concerned resources have to be protected by a PEP with configured “OAuth RS authentication method identifier”. The rest of the configuration is done via the referenced authentication method.

OAuth Authentication Method

  • Do sessionless SSO

    • Whether or not this authentication method enforces the internal subject to be part of an SSO session or not. If true, any request bound to this authentication method (typically via the PEP) takes the data about the requestor from the JWT and does not perform the traditional SSO in the sense that:

      • SSO session is not taken into account even though existing and part of the request (e.g., in the form of session cookie),

      • no new SSO session is created. The requestor data can be enriched from other sources (e.g., with persisted user account data) no matter the value of this parameter.

  • Protected resource URI

    • URI identifying the Resource Server that has to be present in the received access token in the aud claim.

  • OAuth Authorization Server Metadata Ids

    • List of trusted Authorization Servers

  • Do imprint roles

    • Whether or not to imprint roles from the OAuth token into the roles assigned to internal subject.

  • Do imprint groups

    • Whether or not to imprint groups from the OAuth token into the roles assigned to internal subject.

  • User Correlation

    • When “Do correlate user accounts“ is switched on, the fields “User account correlation“ and “User profile correlation” have to be configured in a way that the former refers to the LDAP attribute while the latter to the access token claim. The equality of values of these two then result in assigning the persisted user account (LDAP) attributes to the session.

  • Crypto Containers

    • The list of Crypto containers that shall contain (depending on the rest of the configuration):

      • VERIFICATION_CERTIFICATE to enable verification of the access token signature,

      • DECRYPTION_KEY_PAIR to enable decryption of the access token.

  • Do require signing

    • If true, the access tokens have to be signed, otherwise invalid.

  • Do require encryption

    • If true, the access tokens have to be signed, otherwise invalid.