Skip to content

fix: read typed JWT claims from the raw claim value - #2029

Merged
johanandren merged 2 commits into
akka:mainfrom
efgpinto:fix/jwt-claims-typed-getters
Oct 12, 2026
Merged

johanandren merged 2 commits into
akka:mainfrom
efgpinto:fix/jwt-claims-typed-getters

Conversation

@efgpinto

@efgpinto efgpinto commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Problem

JwtClaims.expirationTime(), issuedAt() and notBefore() return empty for standard tokens.

Every typed getter in JwtClaimsImpl parses getString(name). getString calls the runtime getStringClaim, which returns a value only for JSON strings. Numeric, boolean, object and array claims therefore return empty.

Example payload:

{"iss":"my-issuer-123","sub":"user-1","iat":1760000000,"exp":4102444800}
  • asMap() returns exp: "4102444800".
  • expirationTime() returns Optional.empty.

getBoolean also always returns empty, because it ignores the result of its if/else.

The getString javadoc says non-string claims return their JSON encoding. The runtime does not do this.

Fix

  • getString returns the string value for string claims and the JSON encoding for other claims, as its javadoc says.
  • Typed getters read the raw claim (getRawClaim) instead of getString.
  • getBoolean returns the parsed value.

Reproduced on SDK 3.6.6 with runtime 1.6.17.

Behaviour change

getString on a non-string claim returns its JSON text instead of empty. This includes audience() when aud is an array, which returns ["a","b"]. A JSON null claim is treated as absent by all getters.

Typed getters parsed getString, which the runtime only fills for string
claims, so numeric, boolean, object and array claims were always empty.
This made expirationTime, issuedAt and notBefore empty for standard tokens.
getString now returns the JSON encoding for non-string claims, as documented.
getBoolean also always returned empty.

@johanandren johanandren left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

with some 🤖 feedback:

Should fix

  1. String-encoded objects and lists stop working. In the old code, the only input that worked for getObject and get*List was a string claim whose content was JSON, such as "roles": "[\"a\",\"b\"]". That was because getStringClaim only returns JSON strings. Now getObject filters on isObject, and listClaim tries to read the JSON string itself as a list, so both return empty for that input. scalarClaim keeps string-encoded values on purpose, so the PR is also inconsistent here. Either:

    • parse the text of a textual node as JSON in claimNode and listClaim, or
    • drop the support on purpose and mention it in the release notes.
  2. A JSON null claim makes the list getters throw an NPE. For {"x": null}, readValue("null", listType) returns null, and Some(null).toJava then throws. The old code had the same bug, but listClaim is now the single place to fix it: Option(JsonSupport.getObjectMapper.readValue(...)).

  3. Fractional NumericDates still return empty. RFC 7519 section 2 allows non-integer values, such as "exp": 1760000000.5. Jackson reads this as a DoubleNode with asText "1.7600000005E9", so Long.parseLong fails. Give getNumericDate its own path, for example claimNode(name).filter(_.isNumber).map(n => Instant.ofEpochSecond(n.longValue)).

  4. Document the behaviour change in the release notes. getString on a non-string claim now returns its JSON text where it used to return empty. That includes audience() when aud is an array: it returns ["a","b"]. It also includes null claims, which return "null". Consider a note in the audience() javadoc as well.

Nits

  • Mark JwtClaimsImpl as @InternalApi private[akka] final class, to match the other impl/http classes. Only SdkRunner and HttpRequestContextImpl construct it.

  • Move the private helpers (claimNode, scalarClaim, listClaim) to the bottom of the class, instead of between getString and hasClaims.

  • Keep Scala Option throughout the internal helpers and call .toJava once in each getter. Right now claimNode returns Option, while scalarClaim and listClaim return Optional.

  • Simplify the scalar getters with the standard library. This removes four try/catch blocks, and toBooleanOption ignores case like the old equalsIgnoreCase check:

    scalarClaim(name).flatMap(_.toIntOption).map(Int.box).toJava
  • listClaim could reuse claimNode and call convertValue on the node instead of parsing the raw text again. This would give one place for the fixes in should-fix items 1 and 2.

  • Missing tests:

    • nbf
    • a string-encoded "42" read by getInteger (the case the scalarClaim comment exists for)
    • getBoolean returning false
    • getObject on a non-object claim
    • a null claim

    The test's Map.of call already has 10 entries, which is the maximum. Adding nbf needs Map.ofEntries.

…ms as absent

BREAKING CHANGE: JwtClaims.getString returns the JSON text of a non-string
claim instead of empty. This includes audience() when aud is an array.
All getters treat a JSON null claim as absent.
@efgpinto efgpinto changed the title fix: read typed JWT claims from the raw claim value fix!: read typed JWT claims from the raw claim value Oct 9, 2026
@efgpinto

efgpinto commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author

Applied should-fix 1, 3 and 4 and all nits in 369056f. The PR title now has !, and the description has a "Behaviour change" section.

Not addressed: should-fix 2. A JSON null claim does not cause an NPE. In Scala 2.13, RichOption.toJava uses Optional.ofNullable (scala/jdk/OptionConverters.scala), so Some(null).toJava returns an empty Optional. The code before this PR could throw, through Java Optional.of(readValue(...)), but only for a string claim with the text "null". listClaim now filters on isArray and wraps the result in Option(...), so a null claim never reaches convertValue. shouldReturnClaimsEncodedAsStringsAndFractionalDates covers a null claim.

@johanandren johanandren changed the title fix!: read typed JWT claims from the raw claim value fix: read typed JWT claims from the raw claim value Oct 12, 2026
@johanandren
johanandren merged commit 06ddb32 into akka:main Oct 12, 2026
34 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants