Modify docs

Author: tanya732

EXAMPLES.md

@@ -226,6 +226,10 @@ String rotatedRefreshToken = tokens.getRefreshToken();
 
 The refresh-token grant does not return an ID token, so `tokens.getIdToken()` is typically `null`.
 
+> **Session ceiling:** if the connection emits the IPSIE `session_expiry` claim, pass the persisted
+> ceiling via `withSessionExpiresAt(...)` so the refresh is gated against it. See
+> [IPSIE session_expiry](#ipsie-session_expiry-upstream-idp-session-ceiling).
+
 ### Using MRRT with Multiple Custom Domains
 
 When using a `DomainResolver`, pass the domain explicitly so the grant targets the correct tenant. This is required because a refresh can occur outside of an HTTP request:
@@ -395,29 +399,93 @@ independent of the `exp` token lifetime.
 
 This library does not own a session. It reads and validates the claim at login, exposing it
 via `Tokens.getSessionExpiresAt()` (seconds, or `null` when absent) and
-`Tokens.isSessionExpired()`. Persisting the value and enforcing the ceiling is the
+`Tokens.isSessionExpired(...)`. Persisting the value and enforcing the ceiling is the
 application's job.
 
+> :warning: **The claim must be an integer number of seconds since the epoch.** The value is
+> emitted by your tenant, so the most common mistake is emitting
+> **milliseconds** (a `getTime()` without the `/ 1000`). A millisecond-scale value is **not**
+> enforced as a date thousands of years out — it is out of range, so the library treats it as
+> "no ceiling" and enforcement is silently **off**. Any non-numeric, zero, or negative value is
+> likewise ignored (fails open to "no ceiling") rather than locking users out. 
+
 Persist it at login alongside the tokens (`null` means "no ceiling", store as-is):
 
 ```java
 Tokens tokens = authenticationController.handle(request, response);
 request.getSession().setAttribute("sessionExpiresAt", tokens.getSessionExpiresAt());
 ```
 
-On every session read, rebuild a `Tokens` and check the ceiling. When it returns `true`,
-drop the session and fall through to your existing redirect-to-login path:
+**Login can now fail on this claim.** When the connection option is on and the emitted
+`session_expiry` is at or before the token's issued-at time (already expired), `handle()` throws
+an `IdentityVerificationException` for which `isSessionExpiryError()` returns `true` — a new error
+out of `handle()` that apps enabling the option weren't previously catching. Send the user back to
+log in:
+
+```java
+try {
+    Tokens tokens = authenticationController.handle(request, response);
+    request.getSession().setAttribute("sessionExpiresAt", tokens.getSessionExpiresAt());
+} catch (IdentityVerificationException e) {
+    if (e.isSessionExpiryError()) {
+        response.sendRedirect("/login");
+        return;
+    }
+    throw e;
+}
+```
+
+On every session read, check the persisted ceiling directly with the static helper (no need to
+reconstruct a `Tokens`). When it returns `true`, drop the session and fall through to your existing
+redirect-to-login path:
 
 ```java
 HttpSession session = request.getSession();
-Tokens tokens = new Tokens(null, null, null, "Bearer", null, null, null,
-        (Long) session.getAttribute("sessionExpiresAt"));
+Long sessionExpiresAt = (Long) session.getAttribute("sessionExpiresAt");
 
-if (tokens.isSessionExpired()) {
+if (Tokens.isSessionExpired(sessionExpiresAt, Tokens.DEFAULT_SESSION_EXPIRY_LEEWAY)) {
     session.invalidate();
     response.sendRedirect("/login");
 }
 ```
 
-`isSessionExpired()` applies a 30s negative leeway for clock skew; pass
-`isSessionExpired(0)` for an exact comparison.
+The leeway is a 30s clock-skew allowance that treats the session as expired slightly *early*; pass
+`0` for an exact comparison. (When you hold a live `Tokens` instance, the instance methods
+`tokens.isSessionExpired()` / `tokens.isSessionExpired(0)` do the same thing against its own
+ceiling.)
+
+### Enforcing the ceiling on refresh
+
+The ceiling must be honored on **refresh**, not just on session reads: renewing an access token past
+the ceiling defeats the point of the upstream session limit. If you use this library's refresh-token
+grant (see [Refresh Token Grant (MRRT)](#refresh-token-grant-mrrt)), hand the persisted ceiling to
+`withSessionExpiresAt(...)` and the SDK enforces it for you — `execute()` throws
+`SessionExpiredException` **before** calling the token endpoint when the ceiling has passed, and
+carries the same ceiling forward onto the returned `Tokens` (the refresh grant returns no ID token,
+so there is no fresh `session_expiry` to re-read):
+
+```java
+Long sessionExpiresAt = (Long) session.getAttribute("sessionExpiresAt");
+try {
+    Tokens tokens = authenticationController.renewAuth(refreshToken, domain)
+            .withSessionExpiresAt(sessionExpiresAt)
+            .execute();
+    // ceiling is preserved on the result — persist it as-is for the next refresh
+    session.setAttribute("sessionExpiresAt", tokens.getSessionExpiresAt());
+} catch (SessionExpiredException e) {
+    session.invalidate();
+    response.sendRedirect("/login");
+}
+```
+
+If instead you refresh tokens **outside** this SDK, run the same check yourself **before** calling
+the token endpoint with `grant_type=refresh_token`:
+
+```java
+if (Tokens.isSessionExpired(sessionExpiresAt, Tokens.DEFAULT_SESSION_EXPIRY_LEEWAY)) {
+    // do not refresh — re-authenticate instead
+}
+```
+
+Either way, the ceiling is fixed at login and does **not** advance on refresh, so carry the original
+value forward.

src/main/java/com/auth0/AuthenticationController.java

@@ -361,17 +361,6 @@ public Tokens handle(HttpServletRequest request, HttpServletResponse response) t
         return requestProcessor.process(request, response);
     }
 
-    // TODO(IPSIE Req 3 — refresh-token ceiling): this branch has no renew/refresh-token API, so the
-    // session_expiry ceiling is only stamped at login (see RequestProcessor#withSessionExpiry). When
-    // the refresh-token grant (renewAuth) is merged from the MRRT work, it must:
-    //   1. Gate the refresh: refuse to exchange grant_type=refresh_token once the persisted ceiling
-    //      has passed (Tokens#isSessionExpired()) and surface a0.session_expired instead of calling
-    //      /oauth/token — the renewed access token must never outlive the IdP session ceiling.
-    //   2. Preserve the ceiling: a refresh response without a fresh session_expiry claim must carry
-    //      forward the original sessionExpiresAt rather than dropping it to null (no ceiling). Only a
-    //      newly-emitted, valid session_expiry should replace it.
-    // Until then, enforcement is login-time only; the example-app demonstrates the gate manually.
-
     /**
      * Pre builds an Auth0 Authorize Url with the given redirect URI using a random state and a random nonce if applicable.
      *

src/main/java/com/auth0/RenewAuthRequest.java

@@ -5,6 +5,8 @@
 import com.auth0.json.auth.TokenHolder;
 import com.auth0.net.TokenRequest;
 
+import static com.auth0.Tokens.DEFAULT_SESSION_EXPIRY_LEEWAY;
+
 /**
  * Class to exchange a refresh token for a new set of {@link Tokens}, optionally targeting a
  * specific {@code audience} and/or {@code scope}. This exposes Auth0's refresh-token grant,
@@ -27,6 +29,7 @@ public class RenewAuthRequest {
     private final String issuer;
     private String audience;
     private String scope;
+    private Long sessionExpiresAt;
 
     RenewAuthRequest(AuthAPI client, String refreshToken, String domain, String issuer) {
         this.client = client;
@@ -62,18 +65,59 @@ public RenewAuthRequest withScope(String scope) {
         return this;
     }
 
+    /**
+     * Supplies the upstream IdP session ceiling ({@code session_expiry}, see the IPSIE SL1 profile)
+     * that the application persisted at login from {@link Tokens#getSessionExpiresAt()}. The library
+     * is stateless and does not remember it across requests, so it must be handed back here for the
+     * ceiling to be enforced on refresh.
+     * <p>
+     * When set, {@link #execute()} enforces the ceiling in two ways:
+     * <ul>
+     *   <li><strong>Gate:</strong> if the ceiling has already passed, {@link #execute()} throws a
+     *   {@link SessionExpiredException} <em>before</em> contacting the token endpoint, so a renewed
+     *   access token can never outlive the session ceiling.</li>
+     *   <li><strong>Carry-forward:</strong> the refresh-token grant returns no ID token (hence no
+     *   fresh {@code session_expiry}), so the returned {@link Tokens} carries this same ceiling
+     *   forward via {@link Tokens#getSessionExpiresAt()} rather than dropping it to {@code null}
+     *   ("no ceiling"). Only a newly-emitted, valid {@code session_expiry} in the response replaces
+     *   it.</li>
+     * </ul>
+     * Passing {@code null} (the default) means "no known ceiling": no gate is applied and the
+     * returned tokens carry no ceiling unless the response itself provides one.
+     *
+     * @param sessionExpiresAt the persisted {@code session_expiry} ceiling (Unix seconds), or
+     *                         {@code null} for no ceiling.
+     * @return this request instance for fluent chaining.
+     */
+    public RenewAuthRequest withSessionExpiresAt(Long sessionExpiresAt) {
+        this.sessionExpiresAt = sessionExpiresAt;
+        return this;
+    }
+
     /**
      * Executes the refresh-token grant against Auth0 and returns the resulting tokens.
      * <p>
      * The refresh-token grant does not return an ID token, so {@link Tokens#getIdToken()} is
      * typically null. When refresh-token rotation is enabled, the returned
      * {@link Tokens#getRefreshToken()} is a new refresh token that supersedes the one used here;
      * the application is responsible for persisting it.
+     * <p>
+     * When a session ceiling was supplied via {@link #withSessionExpiresAt(Long)}, it is enforced:
+     * an already-passed ceiling short-circuits with a {@link SessionExpiredException} before any
+     * network call, and the ceiling is carried forward onto the returned tokens (see that method).
      *
      * @return the {@link Tokens} obtained from the grant, including the granted scope.
-     * @throws Auth0Exception if the request to the Auth0 server failed.
+     * @throws SessionExpiredException if the supplied session ceiling has already passed.
+     * @throws Auth0Exception          if the request to the Auth0 server failed.
      */
-    public Tokens execute() throws Auth0Exception {
+    public Tokens execute() throws Auth0Exception, SessionExpiredException {
+        // Gate: never refresh past the IdP session ceiling — the renewed access token must not
+        // outlive the session. Checked before the network call so no token is minted.
+        if (Tokens.isSessionExpired(sessionExpiresAt, DEFAULT_SESSION_EXPIRY_LEEWAY)) {
+            throw new SessionExpiredException(
+                    "The session_expiry ceiling has passed; the refresh token must not be exchanged. Re-authenticate instead.");
+        }
+
         TokenRequest request = client.renewAuth(refreshToken);
         if (audience != null) {
             request.setAudience(audience);
@@ -82,7 +126,13 @@ public Tokens execute() throws Auth0Exception {
             request.setScope(scope);
         }
         TokenHolder holder = request.execute().getBody();
+
+        // Carry-forward: prefer a fresh, valid ceiling from the response (rare — the grant has no
+        // ID token), otherwise re-stamp the supplied ceiling so a refresh never silently drops it.
+        Long freshCeiling = RequestProcessor.parseSessionExpiry(holder.getIdToken());
+        Long ceiling = freshCeiling != null ? freshCeiling : sessionExpiresAt;
+
         return new Tokens(holder.getAccessToken(), holder.getIdToken(), holder.getRefreshToken(),
-                holder.getTokenType(), holder.getExpiresIn(), holder.getScope(), domain, issuer);
+                holder.getTokenType(), holder.getExpiresIn(), holder.getScope(), domain, issuer, ceiling);
     }
 }

src/main/java/com/auth0/RequestProcessor.java

@@ -565,38 +565,71 @@ private Tokens getVerifiedTokens(HttpServletRequest request, HttpServletResponse
      */
     private Tokens withSessionExpiry(Tokens tokens) throws IdentityVerificationException {
         String idToken = tokens.getIdToken();
-        if (idToken == null) {
+        Long sessionExpiresAt = parseSessionExpiry(idToken);
+        if (sessionExpiresAt == null) {
             return tokens;
         }
 
-        DecodedJWT decoded = JWT.decode(idToken);
-        Claim sessionExpiryClaim = decoded.getClaim("session_expiry");
-        if (sessionExpiryClaim.isMissing() || sessionExpiryClaim.isNull()) {
-            return tokens;
+        // Lockout guard: a session that would already be expired on its first read must not be
+        // persisted. Applies the same leeway as Tokens#isSessionExpired so a ceiling that clears
+        // login isn't immediately bounced by the very next read. When the token carries an iat we
+        // anchor the check to it (the canonical "session started at" instant); if it somehow has no
+        // iat we fall back to wall-clock now, using the same leewayed comparison, so an already-past
+        // ceiling can't slip through unguarded.
+        Date issuedAt = JWT.decode(idToken).getIssuedAt();
+        long referenceSeconds = issuedAt != null
+                ? Math.floorDiv(issuedAt.getTime(), 1000L)
+                : Math.floorDiv(System.currentTimeMillis(), 1000L);
+        if (sessionExpiresAt <= referenceSeconds + Tokens.DEFAULT_SESSION_EXPIRY_LEEWAY) {
+            throw new IdentityVerificationException(SESSION_EXPIRY_IN_PAST_ERROR,
+                    "The session_expiry claim is within the expiry leeway of the token's issued-at time; the session is already expired.");
         }
 
+        return new Tokens(tokens.getAccessToken(), tokens.getIdToken(), tokens.getRefreshToken(),
+                tokens.getType(), tokens.getExpiresIn(), tokens.getScope(), tokens.getDomain(), tokens.getIssuer(), sessionExpiresAt);
+    }
+
+    /**
+     * Reads and validates the IPSIE {@code session_expiry} claim from an ID token, returning the
+     * ceiling as a Unix timestamp in seconds, or {@code null} when there is no usable ceiling.
+     * <p>
+     * A {@code null} ID token, an absent/null/non-numeric claim, a non-positive value
+     * ({@code <= 0}), or a value large enough to be milliseconds-since-epoch
+     * ({@code >= 10_000_000_000}) all yield {@code null} — meaning "no ceiling" — rather than an
+     * exception, so a malformed or nonsensical value fails open instead of locking the user out, and
+     * absence is never mistaken for an expired session. The lockout guard (rejecting a valid ceiling
+     * already in the past at login) is applied separately by the caller, since it only applies to the
+     * login path.
+     *
+     * @param idToken the ID token to inspect, or {@code null}.
+     * @return the validated {@code session_expiry} in seconds since epoch, or {@code null}.
+     */
+    static Long parseSessionExpiry(String idToken) {
+        if (idToken == null) {
+            return null;
+        }
+        Claim sessionExpiryClaim = JWT.decode(idToken).getClaim("session_expiry");
+        if (sessionExpiryClaim.isMissing() || sessionExpiryClaim.isNull()) {
+            return null;
+        }
         Long sessionExpiresAt = sessionExpiryClaim.asLong();
         if (sessionExpiresAt == null) {
             // Present but not a numeric value — ignore rather than fail, matching "no ceiling".
-            return tokens;
+            return null;
+        }
+        // Fail open on non-positive values: 0 or a negative is not a real ceiling, so treat it as
+        // "no ceiling" rather than an already-expired session that would lock the user out. This
+        // keeps every nonsensical value (malformed, out-of-range, non-positive) behaving uniformly.
+        if (sessionExpiresAt <= 0) {
+            return null;
         }
-
         // Range guard: reject milliseconds-since-epoch (or any absurdly large value). A value
         // accidentally emitted in milliseconds would read as a date ~thousands of years out and
         // silently switch off enforcement, so treat anything at/above this bound as "no ceiling".
         if (sessionExpiresAt >= MAX_SESSION_EXPIRY_SECONDS) {
-            return tokens;
+            return null;
         }
-
-        // Lockout guard: a session that is already past its ceiling at login must not be persisted.
-        Date issuedAt = decoded.getIssuedAt();
-        if (issuedAt != null && sessionExpiresAt <= Math.floorDiv(issuedAt.getTime(), 1000L)) {
-            throw new IdentityVerificationException(SESSION_EXPIRY_IN_PAST_ERROR,
-                    "The session_expiry claim is at or before the token's issued-at time; the session is already expired.");
-        }
-
-        return new Tokens(tokens.getAccessToken(), tokens.getIdToken(), tokens.getRefreshToken(),
-                tokens.getType(), tokens.getExpiresIn(), tokens.getScope(), tokens.getDomain(), tokens.getIssuer(), sessionExpiresAt);
+        return sessionExpiresAt;
     }
 
     /**

src/main/java/com/auth0/SessionExpiredException.java

@@ -0,0 +1,25 @@
+package com.auth0;
+
+/**
+ * Raised when a refresh-token exchange is attempted after the upstream IdP session ceiling
+ * ({@code session_expiry}, see the IPSIE SL1 profile) has already passed.
+ * <p>
+ * The library is stateless and does not own the session, so it cannot know the ceiling on its own:
+ * the application persists {@link Tokens#getSessionExpiresAt()} at login and hands it back via
+ * {@link RenewAuthRequest#withSessionExpiresAt(Long)}. When that ceiling has passed,
+ * {@link RenewAuthRequest#execute()} throws this exception <em>before</em> calling the token
+ * endpoint, so a renewed access token can never outlive the session ceiling. The application should
+ * treat this as a "must re-authenticate" outcome rather than retrying the refresh.
+ *
+ * @see RenewAuthRequest#withSessionExpiresAt(Long)
+ * @see Tokens#isSessionExpired()
+ */
+@SuppressWarnings("WeakerAccess")
+public class SessionExpiredException extends IdentityVerificationException {
+
+    static final String SESSION_EXPIRED = "a0.session_expired";
+
+    SessionExpiredException(String message) {
+        super(SESSION_EXPIRED, message, null);
+    }
+}