Client Authentication in PSPDFKit Instant
Instant uses JSON Web Tokens (JWTs) for authentication at a very granular level: the layer.
You can think of an Instant layer as a scratchpad for annotations on top of a specific PDF file in PSPDFKit Server. There can be any number of these layers for a PDF file. However, every JWT you issue for use with Instant will reference exactly one layer. So each client will always be operating on a single layer at a time.
All JWTs are cryptographically signed. While it is possible to generate valid JWTs on your users’ devices, please refrain from doing so: Generating a JWT on a device requires the presence of a trusted private key. This opens up additional attack vectors for little-to-no tangible benefit. Instead, we urge you to generate JWTs exclusively on your backend server.
Any client that’s supposed to have access to a layer needs a JWT signed by your backend. At the very least, the JWT needs to specify the following information:
The unique identifier for the PDF file in the user-defined
document_idclaim — you obtain this value when you import a PDF in PSPDFKit Server
The general permissions granted to the bearer of this JWT in the user-defined
permissionsclaim — in the simplest case, you can use the catchall value
An expiration date in the standard
expclaim — a UNIX timestamp in seconds defining the latest date at which the client will have to request a new JWT from your backend to continue syncing
Since access can always be revoked before the
exp date is reached, consider picking expiration dates well into the future. This will help avoid unnecessary network roundtrips to obtain a new JWT and then reauthenticate the layer.
In addition to the claims discussed in the previous section and the standard
iat claims, Instant also supports the following user-defined claims in the JWT:
A unique identifier for the user authenticated by the JWT in the
user_idclaim — when omitted, an anonymous user is assumed and some functionality may be unavailable
The name of the layer on the PDF identified by the
layerclaim — when omitted, the default layer for that PDF is implied
The human-readable name to use as the creator/author for all created annotations and comments in the
creator_nameclaim — when omitted and not customized through
Document.defaultAnnotationUsername, PSPDFKit will prompt the user for a creator name exactly once
The unique identifier of the default group new annotations and comments are supposed to be associated with in the
groupclaim — when omitted, the
nullgroup is implied (this only applies when your license includes the Collaboration Permissions component)
To use the Collaboration Permissions component, the
user_id claim mentioned above and the
collaboration_permissions claim are both mandatory. For details on the latter, please refer to the Collaboration Permissions Overview guide.
Customizing General Permissions
If you want to limit what a client can do on a layer, you need to replace the catchall string
all with an array of strings for each permission you want to grant. While there are additional permissions available for use in web clients, iOS clients are only interested in the following ones:
This permission is required for the initial download of the underlying PDF file without annotations. Although Instant stores the file locally for later use and shares the downloaded file across all of its layers, you should always include this permission when issuing a JWT for use with Instant on iOS.
This permission is required to access the annotations on a layer.
This permission is required if you want to let the bearer of the JWT create, update, or delete annotations or add comments on the layer. Omitting this permission will result in the client treating the layer as read-only. Changes made on other clients will still be synced to a client without the
write permission, but that client will be prevented from making any changes of their own.
JWTs without the write permission can be used for implementing things like the spectator side of a presenter mode, finalizing an agreement or contract as the last step before digitally signing it by multiple parties, or letting your users share their notes with others in real time, without the risk of the others accidentally changing something.