jwt-authn

Appendix - Converting Public Key to PEM Format

2021-09-30T00:00:00-05:00

jwt-authn

Changing public key generated with ssh-keygen (instructions in appendix) into PEM format

*You need to do this so it’s in the right format to use as the public key to verify a signed JWT.

# reads from file jwtRS256.key.pub
ssh-keygen -f jwtRS256.key.pub -e -m pem

or with openssl

# reads from file jwtRS256.key.pub
openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub

Appendix - Generating RSA256 Private and Public Key Pairs

2021-09-30T00:00:00-05:00

link to npm

jwt-authn

Generating RSA256 private and public key pair

Full Documentation

with javascript

import crypto from "crypto";

const { publicKey, privateKey } = crypto.generateKeyPairSync(
  "rsa",
  {
    modulusLength: 4096,
    publicKeyEncoding: {
      type: "spki",
      format: "pem",
    },
    privateKeyEncoding: {
      type: "pkcs8",
      format: "pem",
      cipher: "aes-256-cbc",
      passphrase: "top secret", // this creates an encrypted private key. Make sure to pass it in when trying to sign a JWT. Omit for an unencrypted private key.
    },
  }
);

or from a bash shell

ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS256.key

Appendix - What is a JWT?

2021-09-30T00:00:00-05:00

link to npm

jwt-authn

What is a JWT?

Full Documentation

A JWT (JSON Web Token), pronounced like “jot”, passes along information in the form of claims. It’s often used because it’s url safe and compact. Its components are also in the form of JSON objects, a popular way to read information across the internet. The cryptographic mechanisms of a JWS provide integrity protection as well.

Resources:

RFC 7519 JSON Web Token (JWT)

RFC 7515 JSON Web Signature (JWS)

RFC 6749 The OAuth 2.0 Authorization Framework

Utility Methods - Base64URL Encode

2021-09-30T00:00:00-05:00

link to npm

jwt-authn

base64URLEncode(json)

Full Documentation

json: the input in JSON object format.

Use to create the base64url encoding of the the input.

import { base64urlEncode } from "jwt-authn";

const payload = {
  iss: "joe",
  exp: 1300819380,
  "http://example.com/is_root": true,
}

base64URLEncode(payload);

// expected output:
// eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ

CLI - Base64URL Encoding

2021-09-30T00:00:00-05:00

link to npm

jwt-authn

CLI - Base64URL Encoding

Full Documentation

Use the -b flag and a string to base64url encode the string

jwt-authn -b "hello"

# expected output
# aGVsbG8

Or use the –base64url flag and a string to base64url encode the string

jwt-authn --base64url "hello"

# expected output
# aGVsbG8

Contributing

2021-09-30T00:00:00-05:00

link to npm

jwt-authn

Contributing

Full Documentation

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

Decoding JWTs

2021-09-30T00:00:00-05:00

link to npm

jwt-authn

Decoding a JWT

Full Documentation

jwtDecode(jwt)

*Decoding example taken from RFC 7515 JSON Web Signature (JWS).

// Decoding
import * as jwtAuthn from "jwt-authn";

jwtAuthn.jwtDecode("eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk");

/*
* Output is an object that looks like this:
*
* {
*   header: { alg: "RS256" },
*   payload: {
*     iss: "joe",
*     exp: 1300819380,
*     "http://example.com/is_root": true,
*   },
*   signature: "cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZmh7AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjbKBYNX4BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHlb1L07Qe7K0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZESc6BfI7noOPqvhJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AXLIhWkWywlVmtVrBp0igcN_IoypGlUPQGe77Rw",
* };
*
*/

Encoding JWTs

2021-09-30T00:00:00-05:00

link to npm

jwt-authn

Encoding a JWT

Full Documentation

jwtEncode(header, payload, key[, options])

where options contains:

keyFormat - format of the rs256 private key
passphrase - if using an encrypted private key, passphrase is also required

*Encoding example taken from RFC 7515 JSON Web Signature (JWS).

import * as jwtAuthn from "jwt-authn";

jwt.jwtEncode(
  '{"typ":"JWT",\r\n "alg":"HS256"}',
  '{"iss":"joe",\r\n "exp":1300819380,\r\n "http://example.com/is_root":true}',
  'AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow'
);

// returns
"eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"

License

2021-09-30T00:00:00-05:00

link to npm

jwt-authn

License

Full Documentation

MIT-Modern-Variant

MIT

Signing with HS256

2021-09-30T00:00:00-05:00

link to npm

jwt-authn

hs256Sign(headerPayload, key)

Full Documentation

headerPayload: The combined base64url(header) and base64url(payload) separated by a “.”.
key: The signing key or passphrase.

import { hs256Sign, createHeaderPayload } from "jwt-authn";

const decodedHeader = { typ: "JWT", alg: "HS256" };
const decodedPayload = {
  iss: "joe",
  exp: 1300819380,
  "http://example.com/is_root": true,
};
const passphrase =
  "AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow";

const headerPayload = createHeaderPayload(
  decodedHeader,
  decodedPayload
);

const sig = hs256Sign(headerPayload, passphrase);

// expected output
// "lliDzOlRAdGUCfCHCPx_uisb6ZfZ1LRQa0OJLeYTTpY"