Some widget use cases require validated data integrity from your backend to prevent misuse by end-users or malicious actors. In such cases, you need to create and sign a JSON Web Token (JWT) using a public/private key pair, and pass that token to widgets as properties (see props in SIR).

The following use cases require JWT:

• Audio/Video integration into Live Match Tracker.
• Login into Virtual Stadium.

How to create and use JWT

1. Generate a pair of RSA keys

You can generate a pair of RSA keys using the openssl toolkit, for example:

openssl genrsa -out rsa-private.pem 2048
openssl rsa -in rsa-private.pem -pubout -outform PEM -out rsa-public.pem

You need to send the public key to us via your sales or client setup representative, and we will configure our systems to validate tokens that were signed by you. The private key is used on your backend at runtime.

2. Create JWT for each logged-in user

Every logged-in user requires their unique personal JWT. You can either create the token on the fly for every full page request or cache them on your backend until they are close to expiration.

Here are required claims in token payload:

{
    sub: '<id>',
    scope: 'av',
    iat: 1681718850
}

Token claims:

1. sub - Unique end-user ID. You can use the actual user ID from your system, or if you do not want to expose user IDs, use a derivation such as a salted hash of the actual ID.
2. scope - Space-separated list of permissions granted to this end-user. For example, only users with av in their scope can use the video stream in Live Match Tracker.
3. iat - Time at which the JWT was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T00:00:00Z as measured in UTC. It is often added automatically by libraries when signing the token. We use this to limit the maximum validity time, with a default duration of 16 hours. You can also add the exp claim to limit the expiration time further.

Sign the token with the private key from step 1. Here is an example using Node.js:

// call with `PRIVATE_SIGNING_KEY=$(cat rsa-private.pem) node <filename>.js
import jwt from 'jsonwebtoken';
const token = jwt.sign(
    {
        sub: '<id>',
        scope: 'av',
    },
    process.env.PRIVATE_SIGNING_KEY,
    { algorithm: 'RS256' }
);

3. Pass JWT to widgets

Pass the generated JWT from your backend to your frontend application and set it as a property when adding the widget:

SIR('addWidget', '#my-widget', 'widget_name_here', { jwt: generated_jwt_here });

Key rotation

If you need to rotate your private signing key, generate a new one and send the new public key to us. We will add it to your configuration and notify you when it is enabled. During this time, both old and new keys will be operational. After you complete the rotation on your end, notify us so that we can disable the old key.