Session management

Sessions track user interactions with a resource over a given period. For example, the resource may be an application (app), or identity provider (IDP)—a service that creates, manages, and stores digital identities like Mosaic. By managing sessions, you can allow your users to securely access your application, without needing to re-authenticate for every request. This provides an enhanced identity experience that doesn't compromise on security.

Application sessions

An application session (also known as a local session) is created by the app when the user logs in. By default, a session ends when the user leaves the website or closes the browser. However, an app can extend the session by storing information in a cookie so the user won't need to authenticate each time they return. The session lifetime is managed by the app. Once the application session is over, the user must re-authenticate.

IDP sessions

An IDP session is created by Mosaic when a user logs into the app. Each IDP session is bound to a specific user. The IDP session is active until it expires, unless terminated before.

Mosaic approaches IDP session management in several ways, depending on how the user is authenticated:

  • OIDC-based sessions (frontend sessions)—created when authentication occurs via hosted or redirect-based flows leveraging OIDC protocol.
  • Backend-initiated sessions (backend sessions)—created when authentication is initiated programmatically by your backend using Mosaic APIs or Journeys .
  • SSO service sessions —created when authentication occurred via SSO Service & Federation .

All session types establish a valid user context, issue tokens, and follow the lifecycle rules for expiration and termination.

Note

In our documentation, sessions will refer exclusively to IDP sessions unless stated otherwise.

How sessions determine access

Both application sessions and IDP sessions are used to determine if the user is authenticated whenever access is requested. Once the application session is over, authentication is always required. Authentication is also required if the session doesn't fulfill the session criteria. Once the IDP session is over, the app may continue using existing access token until it expires, but refresh tokens can no longer be used to obtain new access tokens — Mosaic blocks token renewal unless the user re-authenticates and a new IDP session is created.

Implement session management

When implementing session management, take into account:

  • A session remains valid until it expires, the user logs out, or it’s revoked via API.
  • Even if an access token expires, new tokens can be issued within the session’s lifetime.
  • Logout operations should clear both local and Mosaic-managed sessions to ensure full termination.

By understanding OIDC-based (frontend), backend-initiated, and SSO Service session types and identifying their differences, you can design authentication flows that balance security, flexibility, and user convenience across all applications integrated with Mosaic.

OIDC-based sessions (frontend)

  • Created when a user authenticates via a standard OpenID Connect flow like Login with email OTP or Login with Google . Such flows are usually initiated from the browser.
  • The session is valid for 14 days.
  • A browser cookie stores the session state, maintaining continuity across OIDC-enabled apps that share the same tenant.
  • Tokens ( access_token and id_token ) are returned as part of the API response. refresh_token is returned optionally if offline_access was requested.
  • The session remains active until it expires, the user logs out, or it’s terminated.
    • Termination using Terminate sessions API revokes all frontend sessions for the user but does not revoke valid access tokens and refresh tokens.
    • Revoke sessions API revokes all frontend sessions for the user as well as all refresh tokens for the user. Session termination does not invalidate access tokens.

For more, see How frontend sessions work and Manage frontend sessions.

Backend-initiated sessions (backend)

  • Created when authentication is initiated programmatically from your backend through Mosaic’s backend authentication APIs or Journeys . For example, see these use cases: Login with PIN and Login with password .
  • The session is valid for 14 days.
  • The session is managed entirely on the server side.
  • For backend authentication calls, tokens ( access_token , id_token , and refresh_token ) and session ID are returned as part of the API response. In journeys, tokens and session ID are available via user context ( @policy.userContext() ).
  • The session can be re-authenticated by its session ID.
  • The session remains active until it expires, the user logs out, or it’s terminated.
    • Termination using Logout sessions API removes the session and invalidates refresh tokens.
    • Revoke sessions API removes all the sessions from the user and also invalidates refresh tokens. Session termination does not invalidate access tokens.

For more, see How backend sessions work and Manage backend sessions.

SSO Service sessions

  • Created when authentication is performed through Mosaic’s SSO Service .
  • The session is valid for 14 days.
  • A browser cookie stores the session state. SSO service sessions correlate with SSO Clients-Group making it possible to maintain multiple sessions in the browser and authenticate to clients of different groups, each maintaining its own session context.
  • Tokens ( access_token and id_token ) are returned as part of the API response. refresh_token is returned optionally if offline_access was requested.
  • The session remains active until it expires, the user logs out, or it’s terminated.

For more, see SSO Service session management.