jwt-tools
v1.0.2
Published
A command-line tool for working with JSON web tokens
Downloads
2
Readme
JWT Tools
A command-line parser for JSON web tokens
because I needed one.
Installing
npm install -g jwt-tools
Usage
Signing
Signing a token is easy. Just give it a payload and a secret
jwt-tools sign -s verysecret '{ "sub": 1234567890, "name": "Mr Bigglesworth", "iat": 1544889736, "exp": 1544896936 }'
Output:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjEyMzQ1Njc4OTAsIm5hbWUiOiJNciBCaWdnbGVzd29ydGgiLCJpYXQiOjE1NDQ4ODk3MzYsImV4cCI6MTU0NDg5NjkzNn0.l0YJqpInkK70lrSmy1KXtdXL2g4uHZS_vK-D4PnrrlA
Parsing
Now let's parse the token we just created:
jwt-tools parse eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjEyMzQ1Njc4OTAsIm5hbWUiOiJNciBCaWdnbGVzd29ydGgiLCJpYXQiOjE1NDQ4ODk3MzYsImV4cCI6MTU0NDg5NjkzNn0.l0YJqpInkK70lrSmy1KXtdXL2g4uHZS_vK-D4PnrrlA
Output:
{
"header": {
"alg": "HS256",
"typ": "JWT"
},
"payload": {
"sub": 1234567890,
"name": "Mr Bigglesworth",
"iat": 1544889736,
"exp": 1544896936
},
"signature": "l0YJqpInkK70lrSmy1KXtdXL2g4uHZS_vK-D4PnrrlA"
}
Verifying
Verifying with our secret is easy as well
jwt-tools verify -s verysecret eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjEyMzQ1Njc4OTAsIm5hbWUiOiJNciBCaWdnbGVzd29ydGgiLCJpYXQiOjE1NDQ4ODk3MzYsImV4cCI6MTU0NDg5NjkzNn0.l0YJqpInkK70lrSmy1KXtdXL2g4uHZS_vK-D4PnrrlA
Output:
{
"sub": 1234567890,
"name": "Mr Bigglesworth",
"iat": 1544889736,
"exp": 1544896936
}
whereas
jwt-tools verify -s verysecretive eyJhbG
ciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjEyMzQ1Njc4OTAsIm5hbWUiOiJNciBCaWdnbGVzd29ydGgiLCJpYXQiOjE1ND
Q4ODk3MzYsImV4cCI6MTU0NDg5NjkzNn0.l0YJqpInkK70lrSmy1KXtdXL2g4uHZS_vK-D4PnrrlA
gives
token not valid!
invalid signature
Patching
Sometimes it is useful to be able to simply update one of the token claims and re-sign with the shared secret. For example, to extend the life of the token we may want to push the exp
claim out by a couple of hours:
jwt-tools patch -s verysecret -p '$.exp=1544904136' eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjEyMzQ1Njc4OTAsIm5hbWUiOiJNciBCaWdnbGVzd29ydGgiLCJpYXQiOjE1NDQ4ODk3MzYsImV4cCI6MTU0NDg5NjkzNn0.l0YJqpInkK70lrSmy1KXtdXL2g4uHZS_vK-D4PnrrlA
Output:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjEyMzQ1Njc4OTAsIm5hbWUiOiJNciBCaWdnbGVzd29ydGgiLCJpYXQiOjE1NDQ4ODk3MzYsImV4cCI6MTU0NDkwNDEzNn0.cD6gaA7mOwwB_1spZWhZsVwyzXuOO6Rj3uQYwnqX70M
A shortcut command to perform refreshing a token is refresh.
Note the syntax $.exp
to target the exp
field of the JWT's payload. In general, the -p option accepts any JSON path expression to reference one or more fields in the payload. For example to change the identity of the claimed subject,
jwt-tools patch -s verysecret -p `$.sub=1234567891, $.name=Fat Bastard` eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjEyMzQ1Njc4OTAsIm5hbWUiOiJNciBCaWdnbGVzd29ydGgiLCJpYXQiOjE1NDQ4ODk3MzYsImV4cCI6MTU0NDg5NjkzNn0.l0YJqpInkK70lrSmy1KXtdXL2g4uHZS_vK-D4PnrrlA
Refresh
Use refresh
to simply refresh a token with an issued-at (iat
) and expiration (exp
) claim. For example, lets capture a new token in an environment variable TOKEN
export TOKEN=$(jwt-tools sign -s verysecret '{ "sub": 1234567890, "name": "Mr Bigglesworth", "iat": 1544889736, "exp": 1544896936 }')
We can easily verify that the token is expired
jwt-tools verify -verysecret $TOKEN
Output:
token not valid!
jwt expired
Now let's refresh the token
TOKEN=$(jwt-tools refresh -s verysecret $TOKEN)
Running verify again now returns the payload
{
sub: 1234567890,
name: 'Mr Bigglesworth',
iat: 1546714663,
exp: 1546721863
}
and we can see the timestamps have been updated (at time of this writing) with expiration set to the same 2 hour lifetime from the original token.
Development
To set up a local development environment from a clone of this project, run a build with
npm build
then symlink to the local bin script with
npm link
from the project directory. The command jwt-tools
should be on your PATH
now
which jwt-tools
and should ultimately resolve to ./lib/cli.js
.
Any changes you make for development will now be reflected when you invoke the jwt-tools
command from a terminal.
Issues
Feel free to raise any issues on GitHub.