JWT Signature/Claims Set validation order

[marcgreenstock]

Hey @panva,

Thanks for this repo, I have a few suggestions that I would appreciate your feedback on.

My use-case requires parsing of the JWT claims prior to JWS validation, for instance, with a JWT signed using an OpenID Connect Discovery 1.0 JWK:

await jose.jwtVerify(token, async (protectedHeader, token) => {
  const payload = JSON.parse(jose.base64url.decode(token.payload));
  const openIdConfig = await fetch(payload.iss + '/.well-known/openid-configuration').then((res) => res.json());
  return jose.createRemoteJWKSet(openIdConfig.jwks_uri)(protectedHeader, token);
}, {
  requiredClaims: ['sub', 'iss', 'aud', 'exp'],
});

In the above example, the server will make two fetch requests, one to get the OpenID configuration and another to get the JWKs.

The main problem is that jose will perform these fetch requests prior to validation of the claims.

I propose jwtVerify performs the jwtPayload verification prior to compactVerify so it doesn't needlessly execute the getKey function if the claims are invalid.

It would also be great, since the payload will already be decoded, if the get key function signature provided the claims on the object in the second argument. e.g.

export interface JWTVerifyGetKey
  extends GenericGetKeyFunction<
    JWTHeaderParameters,
    FlattenedJWSInput & { claims: JWTPayload },
    KeyLike | JWK | Uint8Array
  > {}

With this, the OpenID Connect Discovery example would be a little simpler:

await jose.jwtVerify(token, async (protectedHeader, token) => {
  const openIdConfig = await fetch(token.claims.iss + '/.well-known/openid-configuration').then((res) => res.json());
  return jose.createRemoteJWKSet(openIdConfig.jwks_uri)(protectedHeader, token);
}, {
  requiredClaims: ['sub', 'iss', 'aud', 'exp'],
});

[wparad]

Why not just parse the token directly and use that before calling jwtVerify?

const payload = jose.decodeJwt(token)

[wparad]

Okay, I'm curious is there a reason why you would want to verify the claims first in a token? What problem does that help solve?

[marcgreenstock]

Consider a service that receives thousands of requests per second that must be authorized by validating a JWT signed by an OpenID issuer.

With every request the server must obtain the JWKs by fetching the OpenID config from the token's issuer, then the JWKs, the URL of which is found in the OpenID config. That's two sequential network requests that may be slow to respond. This puts load on the network and compute environment (Load balances scaling up because of response time or more serverless function instances).

Caching will help here, but it can also be a costly operation, especially in distributed systems.

If a token is deemed invalid by its claims (e.g. expired) prior to validating the signature there is no need to put this load on the network or cache. The server can simply reject request without needing to obtain the JWKs.

[panva]

Consider a service that receives thousands of requests per second that must be authorized by validating a JWT signed by an OpenID issuer.

With every request the server must obtain the JWKs by fetching the OpenID config from the token's issuer, then the JWKs, the URL of which is found in the OpenID config. That's two sequential network requests that may be slow to respond. This puts load on the network and compute environment (Load balances scaling up because of response time or more serverless function instances).

Caching will help here, but it can also be a costly operation, especially in distributed systems.

If a token is deemed invalid by its claims (e.g. expired) prior to validating the signature there is no need to put this load on the network or cache. The server can simply reject request without needing to obtain the JWKs.

Sounds like premature optimization, considering that MOST of the token calls will be valid and you absolutely NEED to cache the JWKS from known issuers. If this is a resource server you're implementing you ought to look at oauth4webapi instead of rolling your own. Alternatively, openid-client if the role you're solving is not a resource server but rather a client (relying party).

[wparad]

Hmm, interesting.

The RPS isn't relevant as so much is the RPS of tokens with invalid claims. Unless there is another one, let's assume that it is just the exp claim. If we assume clients do the right thing in every case except for refreshing until they hit a 401 response (Down below I'll get to why we can make this assumption *1), then that means for a token lifetime of an hour, the worst flood you could see is 1 request per hour per client. If we assume that everyone of your RPS is from a different client, that's a max of 5000 clients => 5k requests per hour, or essentially, one abuse request per second.

In an RPS of thousands, a 0.03% of those having an expired exp claim is negligible, and with caching totally irrelevant.

Are you getting more than a 1 RPS of tokens that are expired?

*1: The likelihood seems so small in comparison, it seems like not a case that really needs to be considered, right? Because if those requests weren't expired, then you would have still deal with the same load. Load shedding these doesn't really offer any benefit. And if there is a larger benefit, than that would point to the fact that the clients are doing something more wrong other than sending an expired token, and there isn't anything that could be done during token verification, right?

[marcgreenstock]

I acknowledge one could consider it an unnecessary optimization, I personally prefer to over-optimize rather than under; not being prepared for unforeseen eventualities can leave systems open to attack. But I think the topic of optimization in software architecture is a little out-of-scope for this discussion to be honest. Apologies for raising it, it was just one example that I had in mind.

As to the suggestion of other libraries, they are good suggestions (❤️ oauth4webapi) and I appreciate the advice, however there are circumstances that prevent their use, hence why I opened the discussion here.

But to continue, expiry is just one example, there are also expected claims (or headers) that a token is required to contain in order to identify the client.

Consider client_secret_jwt and private_key_jwt client assertions for instance. The iss, sub, aud, jti and exp claims are all required. The iss or sub claims are used lookup the client in the database, which means validation needs to occur.

So at a minimum we need to validate sub upfront:

const claims = jose.decodeJwt(token)
if (typeof claims.sub !== 'string') {
  throw new Error('missing or invalid "sub" from token')
}
const client = lookupClientById(claims.sub)
jose.jwtVerify(token, TextEncoder().encode(client.secret), {
  requiredClaims: ['iss', 'sub', 'aud', 'exp', 'jti'],
  algorithms: ['HS256', 'HS384', 'HS512'],
  subject: client.id,
  issuer: client.id,
  audience: 'https://exmaple.com/oauth/token',
  maxTokenAge: 60,
})

Is it a big problem? No, not particularly, there is some duplication of validation and inconsistency in error messages, but it's not that big of a deal.

I simply think it would be a "nice to have" to not have to re-implement the validation when this library already has perfectly good validation built-in (albeit inaccessible without prior JWS validation).

[panva]

@marcgreenstock thank you for taking the time to post a discussion

As per the specification the order of JWT validation steps is not significant which in the end supports your wish. However, the validity or invalidity of the JWT Claim Set prior to signature validation should not be used to make ANY decisions without consideration.

And because of the invalidity part, in a general JWT validation case, one must first do the signature validation to be able to discern between a JWT that's invalid because it has unexpected claims and one that fails to pass authenticity validation.

This order that's present in jose now is a deliberate choice that ensures that JWT Claims Set validation errors don't mean two distinct possibilities but rather just one and therefore action can be taken upon handling those errors by the recipient. Consider, a server side component that calls a routine to refresh a session when a JWT it received is expired. With claims set validation done prior to signature validation (your proposal) the recipient would be mistaken to trigger this routine with a forged token. With claims set validation done after signature validation (current behaviour) the server component will properly recognize a forged token. That's the preferred behaviour as far as I'm concerned and also why the JWTVerifyGetKey interface documentation warns you about the fact that the claims you might want to work with have not been validated.

As an aside, I would strongly suggest you use a certified openid client instead of handrolling OpenID Connect integration.

[marcgreenstock]

Thanks @panva,

I see the problem. In your example routine, the rejection of the jwtVerify call would be a "token expired error" instead of an "invalid signature error", leading to the routine issuing a fresh token without verifying the signature.

Would you see an opportunity to extend decodeJwt to receive verify options as a second argument?

const payload = jose.decodeJwt(token, {
  requiredClaims: ['sub', 'iss', 'aud', 'exp'],
});

Or alternatively would you consider exposing https://github.com/panva/jose/blob/main/src/lib/jwt_claims_set.ts in the modules exports?

[panva]

It is a deliberate choice not to. From the many years in the JOSE ecosystem I often find developers thinking that decode means verify, ergo - having no options for any validation in this method is by design.