add examples

Author: tanya732

EXAMPLES.md

@@ -6,6 +6,7 @@
 - [Allowing clock skew for token validation](#allow-a-clock-skew-for-token-validation)
 - [Changing the OAuth response_type](#changing-the-oauth-response_type)
 - [HTTP logging](#http-logging)
+- [IPSIE session_expiry (upstream IdP session ceiling)](#ipsie-session_expiry-upstream-idp-session-ceiling)
 
 ## Including additional authorization parameters
 
@@ -231,3 +232,39 @@ Once you have created the instance of the `AuthenticationController`, you can en
 ```java
 authController.setLoggingEnabled(true);
 ```
+
+## IPSIE session_expiry (upstream IdP session ceiling)
+
+When an enterprise connection has **"Use ID Token for Session Expiry"**
+(`id_token_session_expiry_supported: true`) enabled, Auth0 adds a `session_expiry` claim to
+the ID token: an absolute Unix timestamp (seconds) that caps how long the session may live,
+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
+application's job.
+
+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:
+
+```java
+HttpSession session = request.getSession();
+Tokens tokens = new Tokens(null, null, null, "Bearer", null, null, null,
+        (Long) session.getAttribute("sessionExpiresAt"));
+
+if (tokens.isSessionExpired()) {
+    session.invalidate();
+    response.sendRedirect("/login");
+}
+```
+
+`isSessionExpired()` applies a 30s negative leeway for clock skew; pass
+`isSessionExpired(0)` for an exact comparison.

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

@@ -360,6 +360,17 @@ 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/RequestProcessor.java

@@ -49,6 +49,12 @@ class RequestProcessor {
     private static final String KEY_FORM_POST = "form_post";
     private static final String KEY_MAX_AGE = "max_age";
 
+    // Upper bound for a valid session_expiry (Unix seconds). Anything at/above this is treated as
+    // "no ceiling": it is almost certainly a milliseconds-since-epoch value emitted by mistake,
+    // which would otherwise read as a date thousands of years out and silently disable enforcement.
+    // Per the IPSIE Decision Log, reject anything >= 10,000,000,000.
+    private static final long MAX_SESSION_EXPIRY_SECONDS = 10_000_000_000L;
+
     private final DomainProvider domainProvider;
     private final String responseType;
     private final String clientId;
@@ -314,13 +320,16 @@ private Tokens getVerifiedTokens(HttpServletRequest request, HttpServletResponse
      * session ceiling on subsequent reads.
      * <p>
      * The claim is an integer Unix timestamp (seconds since epoch). When it is absent the tokens
-     * are returned unchanged (no ceiling). As a lockout guard, if the ceiling is already in the
-     * past relative to the token's {@code iat}, the login is rejected rather than producing an
-     * already-expired session.
+     * are returned unchanged (no ceiling). The value is developer-controlled (it may be stamped by a
+     * Post-Login Action), so it is validated rather than trusted: a non-numeric value, or one large
+     * enough to be milliseconds-since-epoch ({@code >= 10_000_000_000}), is treated as "no ceiling"
+     * rather than silently disabling enforcement with a date thousands of years out. As a lockout
+     * guard, if the ceiling is already in the past relative to the token's {@code iat}, the login is
+     * rejected rather than producing an already-expired session.
      *
      * @param tokens the merged tokens whose ID token is inspected.
      * @return the same tokens augmented with {@code sessionExpiresAt}, or {@code tokens} unchanged
-     * when no {@code session_expiry} claim is present.
+     * when no usable {@code session_expiry} claim is present.
      * @throws IdentityVerificationException if {@code session_expiry <= iat}.
      */
     private Tokens withSessionExpiry(Tokens tokens) throws IdentityVerificationException {
@@ -341,6 +350,13 @@ private Tokens withSessionExpiry(Tokens tokens) throws IdentityVerificationExcep
             return tokens;
         }
 
+        // 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;
+        }
+
         // 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)) {

src/test/java/com/auth0/RequestProcessorTest.java

@@ -574,6 +574,36 @@ public void shouldThrowWhenSessionExpiryIsAtOrBeforeIssuedAt() throws Exception
         assertThat(e.isSessionExpiryError(), is(true));
     }
 
+    @Test
+    public void shouldIgnoreSessionExpiryWhenValueIsInMilliseconds() throws Exception {
+        when(mockDomainProvider.getDomain(any())).thenReturn(DOMAIN);
+
+        long iat = nowSeconds() - 60;
+        // An Action that forgot to convert to seconds: a millisecond-scale value reads as a date
+        // thousands of years out and would silently disable enforcement. Treat as "no ceiling".
+        long millisecondValue = (nowSeconds() + 3600) * 1000L;
+        String idToken = signedIdToken(iat, millisecondValue);
+
+        Map<String, Object> params = new HashMap<>();
+        params.put("code", "abc123");
+        params.put("state", "1234");
+        MockHttpServletRequest request = getRequest(params);
+        request.setCookies(new Cookie("com.auth0.state", "1234"));
+
+        when(mockTokenHolder.getIdToken()).thenReturn(idToken);
+        when(mockTokenResponse.getBody()).thenReturn(mockTokenHolder);
+        when(mockTokenRequest.execute()).thenReturn(mockTokenResponse);
+        when(mockAuthAPI.exchangeCode(eq("abc123"), anyString())).thenReturn(mockTokenRequest);
+
+        RequestProcessor handler = createDefaultRequestProcessor();
+        RequestProcessor spy = spy(handler);
+        doReturn(mockAuthAPI).when(spy).createClientForDomain(anyString());
+
+        Tokens tokens = spy.process(request, response);
+
+        assertThat(tokens.getSessionExpiresAt(), is(nullValue()));
+    }
+
     // --- AuthorizeUrl Building Tests ---
 
     @Test