Recently, I have been reading the JWT' RFC and I'm struggling to understand the meaning of claim names collision.

The registered claim names are more or less clear. If I got it right, these are addressed to provide JWT specification with a set of claims out of the box. 1

However, when it comes to public and private claims, I don't see it so clearly. My question is regarding public and private claim names collision.


Claim Names can be defined at will by those using JWTs. However, in
order to prevent collisions, any new Claim Name should either be
registered in the IANA "JSON Web Token Claims" registry established
by Section 10.1 or be a Public Name: a value that contains a
Collision-Resistant Name
. In each case, the definer of the name or
value needs to take reasonable precautions to make sure they are in
control of the part of the namespace they use to define the Claim


Private Claim Names are subject to collision and should be used with caution.

What does collision mean in this context? How can claim names collide when there is only one authentication and authorization provider? Are not these providers aware of the claims they populate and verify?

Could it be possible that a secondary auth provider could change the JWT payload so that it could override some of these claims?

Probably, I'm missing something important regarding the authentication and the authorization workflow, but I don't know what. Or maybe I'm not getting the definition of collision because of my limited English skills.

1: I have checked out a couple of JWT APIs in Java and I have confirmed that these claims can be informed through dedicated methods/functions (unlike public o private claims whom are informed like a tuple key-value).

  • If I have a FooService that supplies private FooClaims, and you have a DifferentFooService that also supplies FooClaims, what exists to disambiguate those when they are stored in ConfusedUser's claim repo?
    – Caleth
    Commented Sep 8, 2017 at 8:44
  • So, let's say we have these 2 different services, and the auth server needs to inform a claim which name is the same in both services. So, the name should be collision name resistant. For example, using URIs or URN as claim name in order to allow each service to verify unambiguously its own claim.
    – Laiv
    Commented Sep 8, 2017 at 8:55
  • That's a public name: it is collision resistant (modulo bad faith actors)
    – Caleth
    Commented Sep 8, 2017 at 8:59
  • And how is a private one?
    – Laiv
    Commented Sep 8, 2017 at 9:10
  • When it isn't collision resistant, but you (presumably) don't care. I don't think there is a technical difference, but just one of nomenclature
    – Caleth
    Commented Sep 8, 2017 at 9:11

2 Answers 2


I think I finally got it.

The thing is that custom claim names (either public or private) should not match reserved claims names because it would break the interoperability between systems exchanging JWT for authorization. For example, we can not use a custom claim name exp (expire) and set something different than a timestamp because whoever validates the token will expect a timestamp. This is how "exp" claim is supposed to be set, formatted and validated and it's likely all the libs and implementations will do it that way.

Public custom claims names should also be validated and agreed by both, issuer and consumer since the consumer might have implemented different semantics and data formats for a given custom claim than those provided by the issuer. Say the issuer sets a custom public claim named role as a plain string, but the consumer validates role as URIs because this is how it validates this claim internally on its environments. 1

Finally, private custom claims should be named so that they don't collide either with custom public claims or reserver claims.

Related links

1: It's unlikely the issuer of the token changes its implementation for the custom claim. So, the consumer must ensure that the custom claim doesn't break the interoperability between the two systems. Special care must be taken if the consumer consumes others JWTs from 3rd parties. If any of those 3rd party JWTs implement the same custom claim, it could easily cause a claim collision.


How can claim names collide when there is only one authentication and authorization provider?

Here are the registered names.

The provider may need another name, and have two departments which are creating JWTs using the name of the primary contact:

"sub": "1234567890",
"department_lead": "Mickey Mouse"

"sub": "0987654321",
"department_lead": "Donald Duck"

Are not these providers aware of the claims they populate and verify?

Conway's Law would say otherwise based on anecdotal evidence


Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.