Generate a JWT

JSON Web Tokens (JWTs) used for authentication by AI Document Assistant can be generated with one of the many open source libraries that are available and listed on jwt.io.

Token Requirements

  • It has to include the standard claim "exp", which sets the deadline for the validity of the token. This needs to be a non-negative number using the Unix “Seconds Since the Epoch” timestamp format.

  • Additionally, you can restrict the documents and sessions a user can access.

    • "document_ids" are the identifiers of a Document Engine document. This field is an optional array of strings with each document a user should have access to. If this claim is omitted, the user can access any document held on Document Engine.

    • "session_ids" is an array of session IDs. These IDs define the sessions a user can access. If this claim is omitted, the user can access any session data. This ID is a unique string passed to the PSPDFKit for Web configuration

  • It’s also possible to throttle a user’s usage. Important: It’s only possible to limit a user’s usage if the optional userId is set in the PSPDFKit for Web configuration, as this is used for usage tracking.

    • "request_limit" is an optional object that defines the maximum number of requests a user can make in a given time period. If this claim is omitted, the user can make an unlimited number of requests.

      • "requests" is the maximum number of requests a user can make in the given time period.

      • "time_period_s" is the time period in seconds in which the user can make the maximum number of requests.

Generating Tokens

The following example shows the creation of a JWT in JavaScript using the jsonwebtoken library.

  1. Create a key via ssh-keygen:

ssh-keygen -t rsa -b 4096 -f jwtRS256.key
# Enter your passphrase.

# Get the public key in PEM format:
openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256_pub.pem

# If the above command fails because newer versions of `ssh-keygen` output a different format,
# convert the key to PEM like this and then repeat the `openssl` command.
ssh-keygen -p -m PEM -t rsa -b 4096 -f jwtRS256.key
openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256_pub.pem

The private key (jwtRS256.key) is used to sign the tokens you hand out to the clients.

The public key (jwtRS256_pub.pem) needs to be added as a JWT_PUBLIC_KEY in AI Document Assistant’s configuration so that the server will be able to validate the tokens’ signatures but won’t be able to create valid signatures. This example assumes you chose the RS256 algorithm as the JWT_ALGORITHM in AI Document Assistant’s configuration.

Information

If you want to quickly test PSPDFKit for Web with your application, you can also use the key from our example apps (passphrase: _secret_). Make sure to change to a self-generated key before going into production.

  1. Install the jsonwebtoken dependency:

npm install --save jsonwebtoken

  1. Read the private key so that it can be used to sign JWTs. In the claims, pass the set of permissions you want to have, along with the expiration. You can then use the resulting token in your application:

const fs = require("fs");
const jwt = require("jsonwebtoken");
const key = fs.readFileSync("./jwtRS256.key");
const token = jwt.sign({ document_ids: ["abc"] }, {
    key,
    passphrase: "YOUR_PASSPHRASE_GOES_HERE"
}, {
  algorithm: "RS256",
  expiresIn: 60 * 60 // 1 hour — this will set the `exp` claim for us.
});