JWT authentication

a helper JWT package is available to validate and authenticate webhooks

What are JWT tokens

From jwt.io:

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.

In short, JWT tokens allow you to easily authenticate incoming HTTP (or any other data) requests.

Setting up signing secret

Both RSA and HMAC signature verification algorithms will need to have a key based on which to validate the tokens.

Avoid specifying them directly in your function, create a config variable:

specifying jwt signing secret in the config variables

If you are using RSA public key, first encode it using base64.

Authenticating HTTP requests

Most applications use a standard bearer token format when sending HTTP requests. This involves setting an Authorization header:

    Authorization: Bearer <token>

Webhook Relay's jwt package knows where to find it, so you only need to supply the signing key:

jwt = require('jwt') -- Importing jwt helper package

local err = jwt.authenticate(cfg:GetValue("jwt-signing-key")) -- Your secret
if err then error(err) end

r:SetRequestBody("authenticated")

Testing authentication

You can use https://jwt.io to create a valid JWT token with the same secret that you have added to the config variables. Add the token as a header, click on the "+" sign and then click on the "send" button:

JWT authentication testing

If you change the secret either in the config variables or on the jwt generator, you should see an error:

Failed authentication on webhook

Once an error happens, webhook will not be forwarded further.

Custom JWT validation

If your token is not set in the Authorization header, you can use a different function:

jwt = require('jwt')

local err = jwt.validate("your-jwt-token-value-here", cfg:GetValue("jwt-signing-key"))
if err then error(err) end

r:SetRequestBody("authenticated")

Supported algorithms

Webhook Relay's JWT package supports:

• HS - HMAC using SHA256/SHA384/SHA512

• RS - RSASSA-PKCS-v1.5 using SHA-256/SHA-384/SHA-512

• ECDSA using P-256 and SHA-256

• ECDSA using P-384 and SHA-384

• ECDSA using P-521 and SHA-512

• RSASSA-PSS using SHA256 and MGF1-SHA256

• RSASSA-PSS using SHA384 and MGF1-SHA384

• RSASSA-PSS using SHA512 and MGF1-SHA512