Automatic key rotation

[Cyberbeni]

Please summarize your feature request

Automatic key rotation

Describe the functionality you're seeking in more detail

I am in the process of upgrading my authentication service to use JWTs and I came to the decision that I want to rotate the signing keys periodically (as opposed to creating a new one at every app start, or creating one at first start and writing it to a file then reusing that same one forever). I think this logic could be implemented inside JWTKit as this is a pretty common use case. It would have parameters for the location of the folder to store the persisted files in, frequency of rotation, number of older public keys to keep for verification, algorithm to use for the key. It should be able to handle changes to the algorithm (as in when the app is updated and this key rotation is initialized again, we would create a new key immediately and continue to verify JWTs with the previous keys).

Have you considered any alternatives?

Implementing in the app using JWTKit.

[ptoffy]

Hi @Cyberbeni, so I think that implementing key rotation might be a bit awkward in JWTKit because we'd have to implement the lifecycle of a collection, which might be a bit out of scope for the library and should instead be handled by the service using it (Vapor app etc), since the collection itself already has methods to add and remove keys from the collection using KIDs. I was therefore considering writing up a tutorial, either in the docs or as a blog post, to implement this feature using JWTKit instead of adding the feature in the package directly. What do you think?

[Cyberbeni]

I noticed a couple issues when thinking through how I would implement key rotation:

https://github.com/vapor/jwt-kit/blob/main/Sources/JWTKit/JWTKeyCollection.swift#L52

You can't update the default signer when adding the new private key.

Overwriting a private key that is the default signer with its public key will still keep the private key as the default signer. (Not a blocker, since adding the new default would come first)

https://github.com/vapor/jwt-kit/blob/main/Sources/JWTKit/JWTKeyCollection.swift#L270

If you want to use the default signer, its kid won't be added to the header.

[Cyberbeni]

If the doc/blog post would contain all the code that people can just copy paste and run then having that code in a package would be better because it also supports swift package update. If versioning or some other reason makes it inconvenient to be this repository, a separate repository is also fine.

Just the overall big picture wouldn't really be helpful because it's a really simple concept that is already explained several times all over the internet.

[Cyberbeni]

There is also no remove signer option.

I guess setting up a whole new key collection and also manually remembering the current signing key's kid would be the solution to implement key rotation with the current JWTKit API.

[ptoffy]

The default signer is meant to be used by users who just have one key. If more than a key is used in the collection, specifying it with a kid is best, and that's what should be done in key rotation as well.
I've opened #240 to add removal APIs as those are indeed needed.

Vending a key rotation API is complex because its specifics are very much project dependent: algorithm, rotation mechanism and timing, number of active/expired keys and more are all parameters that we'd have to be generic about, and it's easier to just provide the needed primitives and an example (vapor/examples#1), rather than building something that is not straightforward to use just to try please every user who might have different needs.

[ptoffy]

Hey @Cyberbeni, I'll close this as we have the needed APIs now. If you want an example for rotation you can find it at https://github.com/vapor/examples/tree/main/jwt-key-rotation