Skip to content
Connect2id

Access token "clm" compression

To reduce the size of self-contained (JWT-encoded) access tokens and refresh tokens the Connect2id server is configured to compress the optional clm token field that lists the names of the OpenID claims for release at the UserInfo endpoint.

The compression uses a simple, highly effective dictionary-based algorithm. The claim names to compress are determined by a properties file that contains a numbered list of the claims:

WEB-INF/claimsCompression.properties

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, for example:

20 = https://c2id.com/claims/roles

The compression list can be alternatively specified via Java system properties. Prefix the claim name with op.claims.compressionDictionary., for example:

-Dop.claims.compressionDictionary.20=https://c2id.com/claims/roles

Claim names not in the list will be included in the clm of the JWT as they are, without compression.

How effective is the compression? To illustrate, a JSON array of all nineteen claim names listed above compresses to "!__8P". That’s a space saving of 98%.

Tips for further compression optimisation:

  • List the frequently used claim names first, rarely used ones at the end (larger index number).
  • Claims that are not used may be removed from the list.
  • Avoid gaps in the index (sparseness).

Do not change the existing indexing of claim names after going live with a Connect2id server deployment. Doing so may produce different authorised claims than the originally intended when a token issued before the change is consumed.