Access token “clm” compression

To make self-contained (JWT-encoded) access tokens smaller and more efficient to pass around, the Connect2id server can compress the optional clm field that lists the names of the OpenID claims for release at the UserInfo endpoint.

Compression is based on a simple but highly effective dictionary algorithm. The Connect2id server determines which claim names to compress from a properties file that contains a numbered list of the claims:


The shipped default configuration lists all standard OpenID claim names:

0  = sub
1  = email
2  = email_verified
3  = phone_number
4  = phone_number_verified
5  = name
6  = family_name
7  = given_name
8  = middle_name
9  = nickname
10 = preferred_username
11 = profile
12 = picture
13 = website
14 = gender
15 = birthdate
16 = zoneinfo
17 = locale
18 = updated_at
19 = address

To add a new claim name to the compression list, simply give it a unique index number.

20 =

For optimal compression frequently requested claim names should be listed first. Rarely used claims should be put towards the end (larger index number). If you're not using a particular claim at all you may delete it from the list.

The compression list can also be specified via Java system properties. In that case prefix each claim name with, for example:

Claim names that are not in the list will still be included in the clm field of the JWT without compression.

How effective is the compression?

To illustrate, a JSON array consisting of all claim names listed above is compressed to the following bit set: "!__8P" (Base-64 encoded). That is a 98% space saving.