Acquiring a Json Web token (JWT)

The JWT is an open standard, and creating a JWT can be performed in a number of ways, if you have an infrastructure set up for it. Examples of JWT issuers can be Azure AD or KeyCloak among many others.

If you do not have an identity token issuer already, we have described a method below for generating a JWT yourselves, for testing purposes. In the integration itself, you should generate a new JWT for each request. You may, however, use the keys generated below, if you don't have another solution set up.

Step 1: Generating a key pair

JWTs are based on key pairs, which consist of a private and a public key. The private key is your own secret, and needs to be kept safe. The public key is meant for sending to collaborators (e.g. Avida) so that we can verify signatures created with your private key.

The keys should be:

RSA
At least 4096 bits long

The examples below are in bash (on Linux or similar operating systems), but you can easily perform the same tasks with other tools. You can download all the files described below from here:

To generate a key pair, you can run the following commands [create-key.sh] :

This will give you files similar to these:

avida-key.pem:

-----BEGIN RSA PRIVATE KEY-----
MIIJKQIBAAKCAgEAvsOyT9P0d8lJUgbsQiSds2nmxAabf6FpdtRwE+43dkIiSn11
w0zBkWSlf6oI/YwMtMKE5CfAW30PVZfaN/w0mdr+0h9TYNgYOOBSGE0ImFbKAYo9
(...)
gu9nPHBuntCpQNBy0kv6pI7dPBZo1QIQwL8uqyDDpj3G7cweUHT930ynCyn0V9E5
PU8eGdtqQPSYs3aWtdqIrJXRYSvrSh11Gs0AkFZdETGETSsNxq9djWC8SUH+tBcy
BAZtQT5wXoKs1ovpMsE+bpYe6H+xhZWnS1erUO3pBTW+MKc+csz8dUgzNIduh1bT
a2X6IOSUN1l3COouV6SI5vYoaz4L3dv8GadMpP48H6xxtepmdY4UIHVOHKfZgX5e
dN9wnsLuNoUj9Sv30XUd76W6pMqjjVrYyfb5qPJAcQtFzd5QJ+neAKcPGPE+
-----END RSA PRIVATE KEY-----

avida-key-public.pem:

Remember to store the file avida-key.pem in a safe place.

Step 2: Using the keys to create a JWT (for testing)

You need a token with the following header and payload:

Header

Save this as [header.json]. Replace:

kid with a chosen key id. This is something to easily identify the key, e.g. super-agent-key-1

We will use the kid to look up the public key we will use to validate the JWT on our side.

Payload

Save this as [payload.json]. Replace:

iss with a chosen issuer name, e.g. super-agent-issuer

The values in iat, nbf, and exp should be in unix time format, as described in the RFC 7519 standard.

Generating the JWT

Given that you have saved the files above in a folder along with your key file, you can run the following script to generate a valid JWT [create-jwt.sh] :

This token will be valid for 30 days, but you can adjust this as desired.

Validating the token

There are several tools online you can use to validate the tokens. A couple of examples are:

Here you can verify that everything worked as planned, and see which information you send to us.

Step 3: Sending the public key to Avida for verification

When done, make sure you:

Store the private key in a safe and private place
Send the public key to Avida (this can be sent by email)
Generate a sample JWT (not the one you will be using) and send by email, so that we can verify.