JWT (JSON Web Token)

JWT (JSON Web Token)

Users can be authenticated into the Dashboard in a completely passwordless and API free way using JWT authentication. A JWT is a cryptographically signed bundle of data which can be passed via HTTP and if it contains the relevant claims it can log a user into the Dashboard.

Advantages:

  • Totally passwordless (user and admin)

  • No interaction with the API required

  • Fully open and cross platform

  • High level of security

    • Does not require a shared secret such as an admin password

    • Contains no sensitive data

    • Is impervious to impersonation (unless the private key is compromised)

    • Contains an embedded expiry

    • Will fail validation if any alteration is made

Setup:

  • You will need an RSA private/public key pair with which to sign your JWT

  • You will need to provide the Base 64 String version of your PUBLIC key to the Dashboard (one line, no spaces) via the "JWT Auth Public Key" field on the Settings screen in the configuration area.

Usage:

  1. Generate a JWT using any compliant platform and libraries (see http://jwt.io for help)

    1. Use a private claim of either "pi:dashboard_email" or "pi:dashboard_username"

    2. Set a short expiry time to ensure an intercepted token has limited usefulness

    3. Sign the JWT using an RSA algorithm (eg RS256, RS384 or RS512)

      • Note that signing in this way does not encrypt the contents however the JWT does not contain confidential data. The signature is applied to ensure the JWT can be verified as authentic and unchanged.

  2. Provide the JWT to the Dashboard

    1. You can include the jwt in a URL eg server:port/pi?jwt=abc

    2. You can include the jwt as a parameter on a POST request

      • This option is preferred because the JWT is not included in the URL

  3. If the Dashboard is able to validate the JWT as authentic and within it's expiry window and a claim is found matching a Dashboard user, the session will be logged in as that user

You can find a worked example here;

https://github.com/Panintelligence/api-embed-example/tree/main/jwt_auth