JSON entity mapping

The Nimbus JOSE+JWT library applies an intuitive mapping between JSON entities and their natural Java class counterparts.

JSON	Java
string	java.lang.String
number	java.lang.Number
true / false	java.lang.Boolean
JSON array	java.util.List<Object>
JSON object	java.util.Map<String, Object>
null	null

This mapping is applied when the underlying JSON library (GSon) serialises and parses JSON entities in JOSE headers and payloads / JWT claims sets.

Don't serialise instances of other classes, even if GSon is able to do that, as it can lead to unpredictable results. Convert such Java objects to one of the mappings above and then pass them to a JWTClaimsSet or where needed.

When dealing with a JWTClaimSet and standard claims, such as iss or exp, aim to use the standard typed getters / setters.

JWTClaimsSet claimsSet = new JWTClaimsSet.Builder()
    .issuer("https://example.com")
    .expirationTime(Date.from(Instant.now().plusSeconds(60)))
    .build();

When a standard typed setter isn't available, use the general JWTClaimsSet.Builder claim method. The claim value must map to its JSON entity.

Example JWT claims set building:

String stringClaim = "string";

long intClaim = 10L;

double decimalFractionClaim = 3.14;

boolean boolClaim = true;

List<Object> jsonArrayClaim = Arrays.asList((Object)"a", true, 66);

Map<String, Object> jsonObjectClaim = new HashMap<>();
jsonObjectClaim.put("member-1", "a");
jsonObjectClaim.put("member-2", true);
jsonObjectClaim.put("member-3", 66);

// Construct the JWT claims
JWTClaimsSet claimsSet = new JWTClaimsSet.Builder()
    .claim("string", stringClaim)
    .claim("int", intClaim)
    .claim("decimal_fraction", decimalFractionClaim)
    .claim("bool", boolClaim)
    .claim("json_array", jsonArrayClaim)
    .claim("json_object", jsonObjectClaim)
    .build();

// Serialise to JSON
String json = claimsSet.toString();

System.out.println(json);

The serialised JSON:

{
  "string": "string",
  "bool": true,
  "int": 10,
  "decimal_fraction": 3.14,
  "json_array": [
    "a",
    true,
    66
  ],
  "json_object": {
    "member-1": "a",
    "member-2": true,
    "member-3": 66
  }
}

To parse the above JWT claims set back:

// Parse the JWT claims
JWTClaimsSet claimsSet = JWTClaimsSet.parse(json);

// Extract the individual claims
String stringClaim                  = claimsSet.getStringClaim("string");
Long intClaim                       = claimsSet.getLongClaim("int");
Boolean boolClaim                   = claimsSet.getBooleanClaim("bool");
Double decimalFractionClaim         = claimsSet.getDoubleClaim("decimal_fraction");
List<Object> jsonArrayClaim         = claimsSet.getListClaim("json_array");
Map<String, Object> jsonObjectClaim = claimsSet.getJSONObjectClaim("json_object");

// Extract the json_object members
String memberA  = JSONObjectUtils.getString(jsonObjectClaim, "member-1");
boolean memberB = JSONObjectUtils.getBoolean(jsonObjectClaim, "member-2");
long memberC    = JSONObjectUtils.getLong(jsonObjectClaim, "member-3");