+ * When set, {@link #execute()} enforces the ceiling in two ways: + *
@@ -69,11 +101,23 @@ public RenewAuthRequest withScope(String scope) { * 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. + *
+ * 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,10 @@ public Tokens execute() throws Auth0Exception { request.setScope(scope); } TokenHolder holder = request.execute().getBody(); + + + // the ceiling is fixed at login and does not advance on refresh, so the supplied value is always re-stamped unchanged. 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, sessionExpiresAt); } } diff --git a/src/main/java/com/auth0/RequestProcessor.java b/src/main/java/com/auth0/RequestProcessor.java index 8dcb591..f776f4a 100644 --- a/src/main/java/com/auth0/RequestProcessor.java +++ b/src/main/java/com/auth0/RequestProcessor.java @@ -8,6 +8,8 @@ import com.auth0.exception.PublicKeyProviderException; import com.auth0.jwt.JWT; import com.auth0.json.auth.BackChannelTokenResponse; +import com.auth0.jwt.interfaces.Claim; +import com.auth0.jwt.interfaces.DecodedJWT; import com.auth0.json.auth.TokenHolder; import com.auth0.net.TokenRequest; import com.auth0.jwk.Jwk; @@ -24,6 +26,7 @@ import jakarta.servlet.http.HttpServletResponse; import java.security.interfaces.RSAPublicKey; import java.util.Arrays; +import java.util.Date; import java.util.List; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ConcurrentMap; @@ -50,6 +53,9 @@ class RequestProcessor { private static final String KEY_MAX_AGE = "max_age"; private static final String CIBA_GRANT_TYPE = "urn:openid:params:grant-type:ciba"; + // Upper bound for a valid session_expiry (Unix seconds) + private static final long MAX_SESSION_EXPIRY_SECONDS = 10_000_000_000L; + private final DomainProvider domainProvider; private final String responseType; private final String clientId; @@ -532,7 +538,86 @@ private Tokens getVerifiedTokens(HttpServletRequest request, HttpServletResponse throw new IdentityVerificationException(API_ERROR, "An error occurred while exchanging the authorization code.", e); } // Keep the front-channel ID Token and the code-exchange Access Token. - return mergeTokens(frontChannelTokens, codeExchangeTokens); + Tokens tokens = mergeTokens(frontChannelTokens, codeExchangeTokens); + return withSessionExpiry(tokens); + } + + /** + * Reads the IPSIE {@code session_expiry} claim from the verified ID token and stamps it onto + * the returned {@link Tokens} so the application can persist it and enforce the upstream IdP + * session ceiling on subsequent reads. + *
+ * The claim is an integer Unix timestamp (seconds since epoch). When it is absent the tokens + * 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 usable {@code session_expiry} claim is present. + * @throws IdentityVerificationException if {@code session_expiry <= iat + leeway}. + */ + private Tokens withSessionExpiry(Tokens tokens) throws IdentityVerificationException { + String idToken = tokens.getIdToken(); + Long sessionExpiresAt = parseSessionExpiry(idToken); + if (sessionExpiresAt == null) { + return tokens; + } + + // Applies the same leeway as Tokens#isSessionExpired so a ceiling that just clears login isn't immediately bounced by the very next read. + 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. + *
+ * 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 null; + } + // A zero or negative isn't a real ceiling, so we fail open rather than lock the user out. + if (sessionExpiresAt <= 0) { + return null; + } + // A milliseconds value reads as a far future date and silently turns enforcement off. + if (sessionExpiresAt >= MAX_SESSION_EXPIRY_SECONDS) { + return null; + } + return sessionExpiresAt; } /** diff --git a/src/main/java/com/auth0/SessionExpiredException.java b/src/main/java/com/auth0/SessionExpiredException.java new file mode 100644 index 0000000..7d0d36f --- /dev/null +++ b/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. + *
+ * 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 before 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); + } +} diff --git a/src/main/java/com/auth0/Tokens.java b/src/main/java/com/auth0/Tokens.java index fa02682..a87a693 100644 --- a/src/main/java/com/auth0/Tokens.java +++ b/src/main/java/com/auth0/Tokens.java @@ -10,6 +10,7 @@ *
+ * Equivalent to calling {@link #Tokens(String, String, String, String, Long, String, String)} + * with a {@code null} {@code sessionExpiresAt} (no upstream IdP session ceiling). * * @param accessToken access token for Auth0 API * @param idToken identity token with user information @@ -50,11 +62,14 @@ public Tokens(String accessToken, String idToken, String refreshToken, String ty * @param issuer the issuer URL from the ID token */ public Tokens(String accessToken, String idToken, String refreshToken, String type, Long expiresIn, String domain, String issuer) { - this(accessToken, idToken, refreshToken, type, expiresIn, null, domain, issuer); + this(accessToken, idToken, refreshToken, type, expiresIn, null, domain, issuer, null); } /** - * Full constructor including the granted scope. + * Full constructor including the granted scope and domain information. + *
+ * Equivalent to calling {@link #Tokens(String, String, String, String, Long, String, String, String, Long)} + * with a {@code null} {@code sessionExpiresAt} (no upstream IdP session ceiling). * * @param accessToken access token for Auth0 API * @param idToken identity token with user information @@ -67,6 +82,27 @@ public Tokens(String accessToken, String idToken, String refreshToken, String ty * @param issuer the issuer URL from the ID token */ public Tokens(String accessToken, String idToken, String refreshToken, String type, Long expiresIn, String scope, String domain, String issuer) { + this(accessToken, idToken, refreshToken, type, expiresIn, scope, domain, issuer, null); + } + + /** + * Full constructor including the upstream IdP session ceiling. + * + * @param accessToken access token for Auth0 API + * @param idToken identity token with user information + * @param refreshToken refresh token that can be used to request new tokens + * without signing in again + * @param type token type + * @param expiresIn token expiration + * @param scope the scope granted for the access token, or null if not provided + * @param domain the Auth0 domain that issued these tokens + * @param issuer the issuer URL from the ID token + * @param sessionExpiresAt the value of the {@code session_expiry} ID token claim + * (Unix timestamp, seconds since epoch), or {@code null} when the + * claim is absent. A {@code null} value means "no session ceiling" + * and must never be treated as an already-expired session. + */ + public Tokens(String accessToken, String idToken, String refreshToken, String type, Long expiresIn, String scope, String domain, String issuer, Long sessionExpiresAt) { this.accessToken = accessToken; this.idToken = idToken; this.refreshToken = refreshToken; @@ -75,6 +111,7 @@ public Tokens(String accessToken, String idToken, String refreshToken, String ty this.scope = scope; this.domain = domain; this.issuer = issuer; + this.sessionExpiresAt = sessionExpiresAt; } /** @@ -153,4 +190,87 @@ public String getDomain() { public String getIssuer() { return issuer; } + + /** + * Getter for the upstream IdP session ceiling, taken from the {@code session_expiry} claim + * of the ID token at login (see the IPSIE SL1 profile). The value is an absolute point in + * time expressed as a Unix timestamp in seconds since the epoch — not a + * duration, and distinct from {@link #getExpiresIn()} (which bounds the access token). + *
+ * This value is fixed at login and is not updated by a token refresh. It is {@code null} + * when the connection did not emit the claim, in which case there is no session ceiling and + * existing behavior is unchanged. + *
+ * The library does not own a session, so it does not enforce this ceiling on your behalf. + * The application must persist this value alongside the session and, on every session read, + * treat the session as expired once {@link #isSessionExpired()} returns {@code true} — + * redirecting the user to log in again. The same check must run before any refresh-token + * exchange (see {@link #isSessionExpired()}). + * + * @return the {@code session_expiry} value in seconds since epoch, or {@code null} if the + * claim was not present. + */ + public Long getSessionExpiresAt() { + return sessionExpiresAt; + } + + /** + * Convenience equivalent to {@link #isSessionExpired(long)} using + * {@link #DEFAULT_SESSION_EXPIRY_LEEWAY}. + * + * @return {@code true} if the upstream IdP session ceiling has been reached, {@code false} + * otherwise (including when no ceiling is present). + */ + public boolean isSessionExpired() { + return isSessionExpired(DEFAULT_SESSION_EXPIRY_LEEWAY); + } + + /** + * Whether the upstream IdP session ceiling ({@code session_expiry}) has been reached. + *
+ * Call this on every session read and, critically, before + * exchanging a refresh token: once the ceiling has passed the application must not call the + * token endpoint with {@code grant_type=refresh_token}, and should surface a "session + * expired" outcome and re-authenticate instead. + *
+ * When no {@code session_expiry} was emitted ({@link #getSessionExpiresAt()} is {@code null}),
+ * this always returns {@code false} — absence of the claim means "no ceiling" and must never
+ * be treated as an expired session. The comparison is performed entirely in integer seconds.
+ *
+ * @param leewaySeconds a leeway, in seconds, applied so the session is treated as expired
+ * slightly before the wall-clock ceiling to absorb clock skew. Pass
+ * {@code 0} for an exact comparison. A negative value is clamped to
+ * {@code 0}: leeway may only move the effective ceiling earlier,
+ * never later, so it can never extend the session past its ceiling.
+ * @return {@code true} if a ceiling is present and {@code now >= sessionExpiresAt - leeway},
+ * {@code false} otherwise.
+ */
+ public boolean isSessionExpired(long leewaySeconds) {
+ return isSessionExpired(sessionExpiresAt, leewaySeconds);
+ }
+
+ /**
+ * Whether the given session ceiling has been reached, using the same rules as
+ * {@link #isSessionExpired(long)} but against a caller-supplied value rather than the ceiling
+ * held on a {@code Tokens} instance. This lets an application check a persisted
+ * {@code session_expiry} without reconstructing a {@code Tokens} — for example on a session read,
+ * or before running its own refresh-token exchange (which must not renew past the ceiling).
+ *
+ * @param sessionExpiresAt the {@code session_expiry} ceiling (Unix seconds), or {@code null} for
+ * "no ceiling".
+ * @param leewaySeconds a leeway, in seconds, applied so the session is treated as expired
+ * slightly before the wall-clock ceiling to absorb clock skew. A negative
+ * value is clamped to {@code 0} so leeway can never extend the session
+ * past its ceiling.
+ * @return {@code true} if a ceiling is present and {@code now >= sessionExpiresAt - leeway},
+ * {@code false} otherwise (including when {@code sessionExpiresAt} is {@code null}).
+ */
+ public static boolean isSessionExpired(Long sessionExpiresAt, long leewaySeconds) {
+ if (sessionExpiresAt == null) {
+ return false;
+ }
+ long effectiveLeeway = Math.max(0L, leewaySeconds);
+ long nowSeconds = Math.floorDiv(System.currentTimeMillis(), 1000L);
+ return nowSeconds >= sessionExpiresAt - effectiveLeeway;
+ }
}
diff --git a/src/test/java/com/auth0/RenewAuthRequestTest.java b/src/test/java/com/auth0/RenewAuthRequestTest.java
index 5f6dbf5..1e8b677 100644
--- a/src/test/java/com/auth0/RenewAuthRequestTest.java
+++ b/src/test/java/com/auth0/RenewAuthRequestTest.java
@@ -3,6 +3,8 @@
import com.auth0.client.auth.AuthAPI;
import com.auth0.exception.Auth0Exception;
import com.auth0.json.auth.TokenHolder;
+import com.auth0.jwt.JWT;
+import com.auth0.jwt.algorithms.Algorithm;
import com.auth0.net.Response;
import com.auth0.net.TokenRequest;
import org.junit.jupiter.api.BeforeEach;
@@ -12,6 +14,7 @@
import static org.hamcrest.MatcherAssert.assertThat;
import static org.hamcrest.core.Is.is;
+import static org.hamcrest.core.IsNull.nullValue;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.mockito.Mockito.never;
import static org.mockito.Mockito.verify;
@@ -100,4 +103,79 @@ public void shouldPropagateAuth0Exception() throws Exception {
assertThrows(Auth0Exception.class, request::execute);
}
+
+ @Test
+ public void shouldGateRefreshWhenSessionCeilingHasPassed() throws Exception {
+ RenewAuthRequest request = new RenewAuthRequest(mockClient, REFRESH_TOKEN, DOMAIN, ISSUER);
+
+ assertThrows(SessionExpiredException.class,
+ () -> request.withSessionExpiresAt(nowSeconds() - 3600).execute());
+
+ verify(mockTokenRequest, never()).execute();
+ }
+
+ @Test
+ public void shouldNotGateRefreshWhenSessionCeilingIsInFuture() throws Exception {
+ RenewAuthRequest request = new RenewAuthRequest(mockClient, REFRESH_TOKEN, DOMAIN, ISSUER);
+
+ request.withSessionExpiresAt(nowSeconds() + 3600).execute();
+
+ verify(mockTokenRequest).execute();
+ }
+
+ @Test
+ public void shouldNotGateRefreshWhenNoSessionCeilingSupplied() throws Exception {
+ RenewAuthRequest request = new RenewAuthRequest(mockClient, REFRESH_TOKEN, DOMAIN, ISSUER);
+
+ request.execute();
+
+ verify(mockTokenRequest).execute();
+ }
+
+ @Test
+ public void shouldCarryForwardSuppliedCeilingWhenResponseHasNone() throws Exception {
+ when(mockTokenHolder.getIdToken()).thenReturn(null);
+ long ceiling = nowSeconds() + 3600;
+
+ RenewAuthRequest request = new RenewAuthRequest(mockClient, REFRESH_TOKEN, DOMAIN, ISSUER);
+
+ Tokens tokens = request.withSessionExpiresAt(ceiling).execute();
+
+ assertThat(tokens.getSessionExpiresAt(), is(ceiling));
+ }
+
+ @Test
+ public void shouldLeaveCeilingNullWhenNoneSuppliedAndResponseHasNone() throws Exception {
+ when(mockTokenHolder.getIdToken()).thenReturn(null);
+
+ RenewAuthRequest request = new RenewAuthRequest(mockClient, REFRESH_TOKEN, DOMAIN, ISSUER);
+
+ Tokens tokens = request.execute();
+
+ assertThat(tokens.getSessionExpiresAt(), is(nullValue()));
+ }
+
+ @Test
+ public void shouldKeepSuppliedCeilingEvenWhenResponseCarriesADifferentOne() throws Exception {
+ // The ceiling is fixed at login (write-once): a session_expiry in the refresh response must
+ // not move it. The response token is also unverified here, so its claims must not be trusted.
+ long suppliedCeiling = nowSeconds() + 3600;
+ when(mockTokenHolder.getIdToken()).thenReturn(idTokenWithSessionExpiry(nowSeconds() + 7200));
+
+ RenewAuthRequest request = new RenewAuthRequest(mockClient, REFRESH_TOKEN, DOMAIN, ISSUER);
+
+ Tokens tokens = request.withSessionExpiresAt(suppliedCeiling).execute();
+
+ assertThat(tokens.getSessionExpiresAt(), is(suppliedCeiling));
+ }
+
+ private static long nowSeconds() {
+ return Math.floorDiv(System.currentTimeMillis(), 1000L);
+ }
+
+ private static String idTokenWithSessionExpiry(long sessionExpiry) {
+ return JWT.create()
+ .withClaim("session_expiry", sessionExpiry)
+ .sign(Algorithm.none());
+ }
}
diff --git a/src/test/java/com/auth0/RequestProcessorTest.java b/src/test/java/com/auth0/RequestProcessorTest.java
index d76610e..2e37c83 100644
--- a/src/test/java/com/auth0/RequestProcessorTest.java
+++ b/src/test/java/com/auth0/RequestProcessorTest.java
@@ -3,6 +3,9 @@
import com.auth0.client.auth.AuthAPI;
import com.auth0.exception.APIException;
import com.auth0.exception.Auth0Exception;
+import com.auth0.jwt.JWT;
+import com.auth0.jwt.JWTCreator;
+import com.auth0.jwt.algorithms.Algorithm;
import com.auth0.json.auth.BackChannelTokenResponse;
import com.auth0.json.auth.TokenHolder;
import com.auth0.jwk.JwkProvider;
@@ -884,6 +887,181 @@ public void shouldThrowOnProcessIfIdTokenRequestDoesNotPassIdTokenVerification()
assertThat(e.getMessage(), is("An error occurred while trying to verify the ID Token."));
}
+ // --- IPSIE session_expiry Tests ---
+
+ @Test
+ public void shouldStampSessionExpiryFromVerifiedIdToken() throws Exception {
+ when(mockDomainProvider.getDomain(any())).thenReturn(DOMAIN);
+
+ long iat = nowSeconds() - 60;
+ long sessionExpiry = nowSeconds() + 3600;
+ String idToken = signedIdToken(iat, sessionExpiry);
+
+ Map