User Sessions

User sessions represent a period during which the login of user is valid and still sufficiently reliable.

Session versus Authorization

A session represents the period during which the recognition of a user with a registered user profile is trusted. The term “trusted” in this case means that the chances that the user is no longer present or that a person has taken over their session is considered low.

Being authenticated means that the user is recognized and that the user proved to be the holder of the user profile. It does not mean that the user should get access to everything. The policy of an application / resource server / service provider may say that basic access is allowed for any authenticated user. In that case, being authenticated is sufficient for basic access.

If the policy of the application, however states that a number of supplementary conditions need to be met (e.g. certain attributes need to have a certain value and/or a certain persona must be present and selected), then being authenticated is not sufficient. This means that during a session, authorization must be requested for every advanced need and TrustBuilder will evaluate the applicable policy every time advanced access is needed. Please refer to Dynamic Authorization | Intra session decisions for more explanations.

Session state

As said, a session is defined as ‘the period during which TrustBuilder trusts the authentication of a specific user and that the user is still present’. TrustBuilder may use the session to issue id_tokens, as well as to take authorization decisions and produce access tokens. A session can ‘grow’ by means of re-authentication and step-up authentication. TrustBuilder only counts on the sessions it maintains in its own Authentication Server database, and TrustBuilder will not rely on a cookie or other elements stored client-side.

A sessions is represented by a session state. The session state maintained by TrustBuilder contains the following (anonymous) information. Note that a session state may be changed through login or logout activities of other clients.

CODE

{
  "session_id": "BBADE42AAC43",
  "user_id": "B67425562B52417FAB73",
  "user_agent": {
    "IP": 184.92.3.1",
    "OS": "MacOS_X",
    "app": "hr_admin_v11"
  },
  "started_at": "2022-07-22T13:29:01Z",
  "last_seen_at": "2022-07-22T15:12:05Z",
  "authentications": [
    { "amr": "pwd", "acr": "AAL1", "last_supplied_at": "2022-07-22T13:29:01Z" },
    { "amr": "itsme", "acr": "AAL3", "last_supplied_at": "2022-07-22T13:29:45Z" },    
  ],
  "personas": [
    "client_id": "<a_client_id>",
    "persona_id": "AA7425562B52417CAB72",
    "selected_at": "2022-07-22T15:12:05Z"
  ],
  "risk_score": 0,
  "status": "active"
}

Herein is:

session_id = unique id to identify an individual session state
user_id = the unique user-id of the user who has been authenticated and as known by the tenant of the Identity Management
user_agent.IP = IP address of the device used for authentication
user_agent.OS = OS and version of the device used for authentication
user_agent.app = refers to the app or browser and its version that was used during authentication
started_at = the moment that the session for the user on the given device has been created, i.e. the first time the user authenticated for this session
last_seen_at = the last moment where an interaction between TrustBuilder and the client app was observed
amr = authentication method references, i.e. all mechanisms with which the user has been authenticated. For every identity provider, an amr is assigned (by default by TrustBuilder, and can be overridden by the customer)
acr = authentication class reference, i.e. the level of assurance of the process with which the user has been authenticated. For every identity provider, an acr is assigned (by default by TrustBuilder, and can be overridden by the customer)
last_supplied_at = the moment that the user has last been authenticated with the given method, possibly after re-authentication and/or step-up authentication
client_id = client_id of the client at which the user has selected a persona
persona_id = the id of the persona last selected by the user, and if the user has not explicitly selected one it is the default persona indicated with is_preferred
selected_at = the moment the current persona has been selected starting with started_at
risk_score = an indication of the risk level determined for this session for this user at this moment - the default is 0
status = indicates whether the session is pending, active or has been closed. A session is closed (and cannot be reopened) when there is user interaction observed, and one of the conditions described in the “Session closure” section below is met.

The session_stateis persistently stored in the Authentication Server database. The JSON representation is for rendering purposes only and reflects its equivalence with an OIDC id token. In other words, it only represents the session state rendered in JSON but is not the id_token itself.

A user may have several sessions in parallel on different devices. The different devices are referred to in the session using a combination of device parameters: user_agent.IP, user_agent.OS and user_agent.app. This way, TrustBuilder can show the user all the devices he is currently logged in, and geolocation of the last login. By keeping the history of session_state, TrustBuilder can determine when a login is being done on a device with a new set of device parameters, so as to optionally alert the user. The device parameters are obtained by the Web Components embedded in the client app. Client apps that do not use these Web Components need to supply these parameters themselves, if possible. The SAML Connector of TrustBuilder, for example, does not obtain these parameters.

A session’s risk_score can be applied to implement a two-tier session system. A two-tier session system has two states—one for a short period immediately after a user logs in (low session.risk_score), and another that keeps users logged in but with a lower access level (higher session.risk_score). Users can have access basic for a longer period of time, but when trying to access more privileged areas, the user may need to authenticate again possibly using the Continuous Access Evaluation Protocol (see above). After reauthentication, a new session is created with low session.risk_score for a short period of time and then degrades to a lower level session again. The risk_score is not continuously updated: it is only updated when its is being consulted. It is primarily introduced to simplify the declaration of authorization policies, see Dynamic Authorization. The risk can also be obtained from external sources, such as lists of suspected users and fraud score services.

Session lifecycle

While a user has a session, the user may be providing additional authentication assurance, or conversely, the risk context of the session may degrade over time. As such, a TrustBuilder session has a lifecycle and the session state changes over time.

Note that while the Authentication Server is called upon when the user needs a session (wants to or is requested to logon), multiple authorization decisions may be requested during a single session from the Authorization Server, in the form of an OAuth2 access token request or in the form of a XACML3 policy decision request.

The session state could evolve as follows:

CODE

at moment 1
{
  "session_id": "BBADE42AAC43",
  ...
  "started_at": "2022-07-22T13:29:01Z",
  "last_seen_at": "2022-07-22T13:29:01Z",
  "authentications": [
    { "amr": "pwd", "acr": "AAL1", "last_supplied_at": "2022-07-22T13:29:01Z" }
  ],
  "persona.name": "employee",
  "selected_at": "2022-07-22T13:29:01Z",
  "risk_score": 1,
  "status": "active"
}

at moment 2
{
  "session_id": "BBADE42AAC43",
  ...
  "started_at": "2022-07-22T13:29:01Z",
  "last_seen_at": "2022-07-22T15:12:05Z",
  "authentications": [
    { "amr": "pwd", "acr": "AAL1", "last_supplied_at": "2022-07-22T13:29:01Z" }
  ],
  "persona.name": "employee",
  "selected_at": "2022-07-22T13:29:01Z",
  "risk_score": 2,
  "status": "active"
}

at moment 3
{
  "session_id": "BBADE42AAC43",
  ...
  "started_at": "2022-07-22T13:29:01Z",
  "last_seen_at": "2022-07-22T14:12:25Z",
  "authentications": [
    { "amr": "pwd", "acr": "AAL1", "last_supplied_at": "2022-07-22T13:29:01Z" }
    { "amr": "itsme", "acr": "AAL3", "last_supplied_at": "2022-07-22T14:12:25Z" }
  ],
  "persona.name": "hr_manager",
  "selected_at": "2022-07-22T16:02:31Z",
  "risk_score": 0,
  "status": "active"
}

at moment 4
{
  "session_id": "BBADE42AAC43",
  ...
  "started_at": "2022-07-22T13:29:01Z",
  "last_seen_at": "2022-07-22T18:13:20Z",
  "authentications": [
    { "amr": "pwd", "acr": "AAL1", "last_supplied_at": "2022-07-22T13:29:01Z" }
    { "amr": "itsme", "acr": "AAL3", "last_supplied_at": "2022-07-22T14:12:25Z" }
  ],
  "persona.name": "hr_manager",
  "selected_at": "2022-07-22T16:02:31Z",
  "risk_score": 1,
  "status": "active"
}

at moment 5
{
  "session_id": "BBADE42AAC43",
  ...
  status": "closed"
}

at moment 6
{
  "session_id": "BBADE42AB941",
  ...
  "started_at": "2022-07-23T09:00:01Z",
  "last_seen_at": "2022-07-23T09:00:01Z",
  "authentications": [
    { "amr": "pwd", "acr": "AAL1", "last_supplied_at": "2022-07-23T09:00:01Z" }
  ],
  "persona.name": "employee",
  "selected_at": "2022-07-23T09:00:01Z"
  "risk_score": 1,
  "status": "active"
}

Notes:

TrustBuilder will only recalculate the session state when a policy decision requires a most accurate view of the session state.

The session state may be reflected in the access token sent to the client app in case it is being refreshed or in case a new access token is requested.

Moment #2 ‘user is away for too long’ may be evaluated using contextual information:

duration of the session in absolute terms
change of IP address of the device
a period of inactivity of the user observed by lack of access token requests.

Moment #4 ‘2FA is no longer valid’ may be related to a policy set (max_duration) by the customer for its corresponding given identity provider / authentication factor.

While session state may evolve, it is the actual real-time state that is used by the Authorization Server to evaluate policies and derive policy decisions and access tokens, as illustrated on Policy Model | Authorization Policy.

Session start

TrustBuilder sets up a session after TrustBuilder has verified that the user has been successfully authenticated. This event starts:

either by the user choosing to login, e.g. pressing the Login button
or because user wants to do something that requires a login, e.g. the app presents a login screen
or the client app logs in the user after he identified himself using the device’s PIN, fingerprint or face-id.

The fact “successful authentication” means on the one hand that:

either a user has been authenticated by an identity provider in a federated way, meaning that the identity provider passes on the proof-of-authentication using a SAML or OIDC token
or a user is authenticated using the TrustBuilder OIDC service, meaning the user supplied a valid user-id/password combination against the TrustBuilder user-id/password
or a user is passwordless authenticated using an authentication factor of the TrustBuilder Service Catalog.

On the other hand, the session creation policy must also be satisfied in terms of risk level. So before a session is actually created, the Policy Engine will evaluate the Authentication Policy, defined on Policy Model | Authentication Policy.

Once these conditions are fulfilled, TrustBuilder will set up a session. It may, however, be that an application (or in general, the Service Provider) requires a higher level of authentication assurance. In this case, the user has still a session but the user’s client app will not receive an access token needed for the application. This is in fact determined by the Authorization Policy - see Policy Model | Authorization Policy.

Session closure

A session may cease to exist under the following conditions:

the session duration has exceeded the max_session_duration or max_idle_time
the user has issued a Single Logout request
the user changed the credential used to start the session
the risk_score of the session has exceeded the max_session_risk, e.g. when the user has been blocked in the mean time.

The termination of a session actually means that TrustBuilder sets the session record in its database to non-active and the session record will no longer be used to produce tokens. Tokens that have already been issued can still be used, even though the TrustBuilder introspection endpoint will invalidate the tokens.

Single Logout (SLO) is in fact the counterpart to Single Sign On (SSO). SSO improves usability by minimizing the number of re-authentications and enabling the user to have authenticated sessions at different clients without having to provide the credentials every time. SSO also improves security. This argument is even more true for SLO. By supporting an SLO protocol a user can initiate a logout and get all sessions terminated without having to actively logout from every client. As a result, implementing SLO protects its users and their data across a whole system because it ensures that there are no active sessions left from an SSO session that may be hijacked or otherwise misused.

A Single Logout only kills the session on the device the user is working on, referred to by the device_OS and device_ip. To logout from all devices (Global Logout, e.g. when credentials are changed) or from devices selectively, the user must be presented with all sessions that refer to his user_id (query into the session state database) and must provide the user with the option to kill one or more of those sessions. In case the user changed the credential used to start any of these sessions, those should be killed as well.

TrustBuilder supports back-channel logout (as standardized in Final: OpenID Connect Back-Channel Logout 1.0) across client applications listed with a client_id in the session by:

calling the backchannel_logout_uri of those clients, as configured in the admin portal, and
sending them a logout_token, as counterpart of the id_token.

It is of course up to the clients and their server platforms to appropriately react to a logout request from TrustBuilder. TrustBuilder can obviously not be responsible for clients that keep the session open at their layer, their Service Provider Session.

The decoded logout JWT may look like:

CODE

{
  "iss": "https://auth.trustbuilder.com",
  "session_id": "BBADE42AAC43",
  "jti": "3ad8805d-6fc0-4699-a33f-a75d45b24e4d",
  "iat": "2022-07-23T09:00:01Z",
  "aud": "s6BhdRkqt3",
  "user_id": "B67425562B52417FAB73",
  "events": { "http://schemas.openid.net/event/backchannel-logout": {} }
}

Notes:

A ‘local logout’ is the act of signing the user out of the app (or Service Provider in general) and terminating the Service Provider Layer session. The TrustBuilder session may still be active, and other application sessions aren't affected by terminating a specific local application session. Local logout is managed by the app. If the user wants to access the app again, the user is automatically authenticated through the active TrustBuilder session into the app, and the app creates a new session for the user.

A ‘Single Logout’, however, is the act of signing the user out of TrustBuilder and signing out of all the apps with the same credentials. This results in ending the TrustBuilder session and all the associated application sessions for the user.

Even though the TrustBuilder session has been terminated, active application sessions for the user can still persist without the TrustBuilder session, depending on the restrictive nature of those applications. For example, a user can still browse through a catalog of vacation experiences and add to their cart. When this user is ready to check out and make a payment, the app can enforce a TrustBuilder access workflow and redirect the user to re-authenticate with TrustBuilder to secure a TrustBuilder session.