How can I set the "alg" header?

[leoneltrich]

I am trying to implement a token generator using JJWT and Java 21. But I can't seem to figure out, how to set the "alg" header. Everything else works just fine. I can add other headers, custom headers and claims. But as soon es I try to set a custom header to {"alg": "EC512"} it just sets the "alg" header top "none". I also can't find an option to set this header directly like for example the type or keyID. Any advice is highly appreciated! This is the code in question:

    protected JwtBuilder setHeaders() throws NullPointerException, Exception{
        return Jwts.builder()
                .header()
                .type("JWT")
                .add("alg", "EC512")
                .and();
    }

[lhazlewood]

Good question!

I'm assuming EC512 is not a typo for the RFC standard ES512 algorithm (ECDSA using P-521 and SHA-512), which JJWT natively supports via the Jwts.SIG.ES512 constant. So this implies that you're trying to implement your own custom signature (or key management) algorithm with a non-standard EC512 identifier. Based on that assumption:

The alg header is set automatically by JJWT based on the signature algorithm (for signed JWTs, aka JWSs) or key management algorithm (for encrypted JWTs, aka JWEs) specified during JWT building. For example, for JWSs:

Jwts.builder()
    .signWIth(key) // JJWT implicitly chooses the appropriate algorithm based on the key type and size, or:
   //.signWith(key, aSecureDigestAlgorithm) // you explicitly set the algorithm, usually via a Jwts.SIG.**** constant
  ...

JJWT will automatically set the JWS alg header to be the value returned from the implicit (or explicit) algorithm's .getId() method, e.g. aSecureDigestAlgorithm.getId().

For example, if a JWT was signed with the ES512 algorithm:

assert Jwts.SIG.ES512.getId().equals(aJws.getHeader().getAlgorithm());

Similarly, for JWEs, using JwtBuilder.encryptWith method variants will set the alg header value to be the output of the implied (or explicit) KeyAlgorithm's .getId() method. For example:

assert Jwts.KEY.RSA_OAEP_256.getId().equals(aJwe.getHeader().getAlgorithm());

So if you want the alg value header to be EC512 (which is not a standard JWA identifier), you must provide a custom SecureDigestAlgorithm that returns EC512 from it's .getId() implementation (and also satisfies the required signature and verification implementation logic), and then specify that during JWS or JWE construction. For example, for a JWS:

Jwts.builder()
   .signWith(key, myEc512AlgorithmInstance)
   ...

But since EC512 is not a JWA-standard algorithm identifier, the JJWT parser won't 'know' about it by default, so you have to add it to the parser's total set of supported algorithms. For example:

Jwts.parser()
    .sig().add(myEc512AlgorithmInstance).and()
   ...

And then the parser will use your algorithm for signature verification when encountering JWSs with an EC512 id.

If no signature or key management algorithm is specified via .signWith or .encryptWith method variants, no security is enabled at all, and per the JWS RFCs, the the alg value of none must be used to indicate such, so the JJWT builder sets this value automatically in these cases since it's an RFC requirement.

Finally, note that the enc and zip headers are set automatically by JJWT the same way because they indicate agreed-upon/identifiable logic (e.g. computational behavior that needs to be performed), and not just state (any random value). So that logic must be supplied to the JJWT builder (and parser) in the form of algorithm instances that perform said behavior, and each algorithm has a .getId() value that is used to set the appropriate header value automatically so that parsers can perform the associated (identified) logic.

I hope that helps!

[lhazlewood]

P.S.

Note that the JWT specifications suggest that you do not need set the JWT typ (type) header when you are certain what you're parsing is a JWT, for example a compact string in an HTTP authorization header or cookie or similar.

The type header is only really necessary if:

1. You are parsing an existing data structure (e.g. JSON), and
2. You expect that data structure to contain a JWT somewhere within, and
3. You try to find a typ value that indicates you should treat the associated structure as a JWT

It's not valuable for standalone compact (Base64Url period-delimited) strings, because nothing in the string can be inspected to know it's a JWT. You have to be reasonably sure it's a compact JWT first before you pass it to a JWT parser, at which point you don't need the typ header because you're already pretty sure.