Session Lifecycle

Session objects and when they are created

/launch request
    │
    ├─ SmartLaunchSession created (iss, launchToken)
    ├─ PkceParameters generated (codeVerifier, codeChallenge, state, nonce)
    └─ Both stored in HttpSession

/callback request
    │
    ├─ PkceParameters read from session (codeVerifier, state)
    ├─ State verified (constant-time)
    ├─ Token exchange (code + verifier → access_token, refresh_token)
    ├─ id_token validated
    ├─ SmartLaunchContext built (patientId, encounterId, tokens, expiry)
    └─ SmartLaunchContext stored in HttpSession

/dashboard, /api/** requests
    │
    ├─ SmartSecurityFilter: reads SmartLaunchContext from session
    ├─ TokenRefreshFilter: refreshes if < 120s remaining
    └─ Controllers: use SmartLaunchContext to build FhirClient

SmartLaunchContext fields

Field	Type	Source
accessToken	String	Token response access_token
refreshToken	String	Token response refresh_token
patientId	String	Token response patient extra
encounterId	String	Token response encounter extra (may be null)
needPatientBanner	boolean	Token response need_patient_banner extra
scope	Set<String>	Token response scope (split by space)
expiresAt	Instant	now() + expires_in seconds
fhirBaseUrl	String	iss from the launch request
userProfile	UserProfile	Extracted from id_token claims

Redis readiness

All session objects implement java.io.Serializable with pinned serialVersionUID:

public class SmartLaunchContext implements Serializable {
    private static final long serialVersionUID = 1L;
    // ...
}

public class PkceParameters implements Serializable {
    private static final long serialVersionUID = 1L;
    // ...
}

To enable Redis session storage, add to application.yml:

spring:
  session:
    store-type: redis
  data:
    redis:
      host: ${REDIS_HOST:localhost}
      port: ${REDIS_PORT:6379}
      password: ${REDIS_PASSWORD:}

And add to pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.session</groupId>
    <artifactId>spring-session-data-redis</artifactId>
</dependency>

With Redis enabled, multiple application instances share session state — a clinician's session survives a pod restart or load-balancer redirect to a different instance.

Token refresh timing

  Token issued
  │
  │◄───────── expires_in (e.g. 3600 s) ─────────►│
  │                                               │ Token expires
  │                             │◄── 120 s ──────►│
  │                             │                 │
  │                             │ TokenRefreshFilter fires here
  │                             │ (on next /api/** request)

TokenRefreshService.refreshIfNeeded():

public void refreshIfNeeded(SmartLaunchContext ctx) {
    Instant refreshThreshold = ctx.getExpiresAt()
        .minusSeconds(120);
    if (Instant.now().isAfter(refreshThreshold)) {
        refresh(ctx);
    }
}

If the refresh token itself is expired, the user is redirected to /launch?error=session_expired.

---

← Security Model · Overview