Authentication

The JSON Web Token (JWT) is signed with a private key on your server and verified with the public key on PSPDFKit Processor.

JSON Web Token (JWT)

PSPDFKit Processor uses the JWT standard for authentication. Your backend signs a JWT asserting that the holder of the token is allowed to process certain documents using certain operations. Next, it passes the JWT to your client apps. Your app then passes its token to the PSPDFKit Processor HTTP API to prove it’s allowed to process the document.

You can generate a token with one of the many open source libraries that are available and listed on jwt.io.

Requirements

  • The JWT 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.
  • The JWT has to be signed using an asymmetric cryptographic algorithm. PSPDFKit Processor supports the algorithms RS256, RS512, ES256, and ES512. See RFC 7518 for details about specific algorithms.

Optional Claims

We provide two optional claims that give you control over which documents can be processed and which operations can be applied to the document. You can use this to ensure the JWTs you create are only used on certain documents, with certain attachments, and to apply certain operations.

  • "allowed_files" — This controls which documents the operations may be applied to. You can use this if you want the JWT to only be used to process a specific set of documents, or to limit which attachments can be used. There are multiple options you can use.
    • "any" or not specified at all — There’s no limitation on the documents that can be processed, meaning this token works on all documents and with all attachments.
    • A JSON object containing the following:
      • Required — file — One of:
        • "any" — Any file can be processed.
        • A list of SHA-256 hashes of the documents that can be processed.
      • Required — url — One of:
        • "any" — Any URL can be processed.
        • A list of URLs documents can be processed from.
      • Required for every attachment — An object with the same name as the attachment containing one of:
        • "any" — Any attachment is allowed.
        • A list of SHA-256 hashes allowed for the attachment with the given name.
  • "allowed_operations" — This controls which document operations may be applied. You can use this if you want this JWT to only be used for applying a specific set of operations, or to only permit specific operation types. Possible options:
    • "any" or not specified at all — There’s no limitation on the operations that are applied, meaning all operations are allowed.
    • A JSON object containing one or both:
      • "operationTypes" — A JSON array containing a list of all document operations permitted. Every document operation that’s not part of this list will be rejected unless explicitly permitted by a list of operations, as described below.
      • "operations" — A JSON array containing a list of operations sets that are allowed. Keep in mind that this needs to match the specified operations exactly. Even if an operation isn’t permitted by operationTypes, as long as the operation set matches, the operation will be permitted.

To give you a better understanding how the JWT should look, check out the Usage Examples guide, which contain multiple configurations.

Generating Tokens

The following example shows the creation of a JWT in a Node/Express app using the jsonwebtoken library. It assumes you chose the RS256 algorithm and have created a pair of private and public keys.

To create a key, use openssl:

Copy
1
2
3
4
openssl genrsa -out jwtRS256.key 4096

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

Now use the private key to sign the tokens you hand out to the clients and add the public key to the server’s configuration so that the server will be able to validate the tokens’ signatures.

If you want to quickly test PSPDFKit Processor, 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:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
// index.js

const express = require("express");
const router = express.Router();
const fs = require("fs");
const jwt = require("jsonwebtoken");
const key = fs.readFileSync("./jwt.pem");
const token = jwt.sign(
  { allowed_operations: "any", allowed_files: "any" },
  key,
  {
    algorithm: "RS256",
    expiresIn: 60 * 60 // 1hr, this will set the `exp` claim for us.
  }
);

/* GET home page. */
router.get("/", function(req, res, next) {
  res.render("index", { token: token });
});

module.exports = router;