JSON Web Token (JWT)

What is JSON Web Token?

JSON Web Token (JWT) is an open, industry standard RFC 7519 method for representing claims securely between two parties. You can enable JWT in MegaNode and send requests with JWT to ensure only authorized requests are available.

How to use it?

It's easy to enable JWT and send requests with JWT in MegaNode, you just need to follow the below instructions:

Generate RSA-256 keys

Generate your own RSA-256 public and private key with 2048 length. Below is the example using OpenSSL.

# generate rsa key
openssl genrsa -out jwtRSA256-private.pem 2048
openssl rsa -in jwtRSA256-private.pem -pubout -outform PEM -out jwtRSA256-public.pem

Enable JWT in MegaNode

• Login -> Dashboard -> Account
• Enable the JTW and input the public key generated in previous step.
• You will get the public key ID after clicking "Add"

Generate the JWT

Once you've enabled the JWT, it's required to add the JWT in all the requests header. Below is the example of generating JWT using https://jwt.io/

You need HEADER, PAYLOAD, & SIGNATURE to generate a JWT.

Header

You can use your terminal to encode the header.

# To encode a header
header=`echo -n '{"alg": "RS256","typ": "JWT","kid": "c6a5278e-ce1d-4f54-b7fa-f8d90f8b5756"}' | base64 | sed s/\+/-/ | sed -E s/=+$//`

Payload

{% hint style="info" %}
You can convert a human-readable timestamp to epoch by command below.

date -j -f "%Y-%m-%d %H:%M:%S" "2022-07-10 15:58:50" "+%s"

Make sure your expiration time is no longer than current time + 24 hours.
{% endhint %}

You can encode your payload by command below.

#To encode a payload
payload=`echo -n '{"aud": "nodereal.io","exp": "1657461530"}' | base64 | sed s/\+/-/ | sed -E s/=+$//`

Signature

To create the signature part you have to take the encoded header, the encoded payload, a secret, the algorithm specified in the header, and sign that.

# To encode a signature
sig=`echo -n "$header.$payload" | openssl dgst -sha256 -binary -sign jwtRSA256-private.pem  | openssl enc -base64 | tr -d '\n=' | tr -- '+/' '-_'`

JWT

Your JWT is the combination of your encoded header.payload.signature.

# JWT = header.payload.signature
jwt=`echo $header.$payload.$sig`
echo $jwt

Verify your jwt by the debugger.

Send request with JWT

After generating the JWT, you would need to add the JWT as a part of your request header -H "Authorization: Bearer entry.

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $jwt" \
--data '{"jsonrpc": "2.0", "id": 1, "method": "eth_blockNumber", "params": []}' \
"https://bsc-mainnet.nodereal.io/v1/<YOUR-API-KEY>"

What if the JWT is incorrect ?

If you have enabled the JWT but sending requests without JWT or with incorrect JWT, you will receive a http 401 error status code and also below response.

{
    "jsonrpc": "2.0",
    "id": 1,
    "error": {
        "code": -32002,
        "message": "This function is unavailable due to security setting."
    }
}

You should either disable the JWT setting or send requests with correct JWT.

Do you support key rotation?

Yes, MegaNode now support up to 3 keys, you could rotate your key by uploading a new one.

Reference

You can also check how to encrypt & sign the payload with the keys on github repo here.