No results

Implementing SSO between Papyrs and other applications using JSON Web Tokens (JWTs)

(Available from Company Intranet plans and higher.)

Papyrs' Single Sign On (SSO) functionality allows you to authenticate users in other applications with their Papyrs credentials. When a user is logged in to your Papyrs site they can then access the other application without being prompted for additional credentials.

In turn, Papyrs also integrates with Active Directory, SAML, Google Workspace and Slack SSO mechanisms. These mechanisms can also be combined. For example, users can log in to Papyrs with their SAML credentials, and third party applications can then authenticate against Papyrs users without any additional password prompts.

Registering your external application for SSO with Papyrs

The SSO mechanism is based on JSON Web Tokens (JWT) [see https://jwt.io/]. Your application sends a SSO request to Papyrs, wich then returns a signed JWT containing details about the authenticated user.

Registering your application with Papyrs
In order to register your application with Papyrs, send the following information to team@papyrs.com:

SHARED_SECRET - A secret string, shared only between your application and Papyrs.
CALLBACK_URL - The callback URL endpoint of your application to which the user is redirected with a token (JWT) after it has been authenticated by Papyrs.

We will register your application, and send you the SSO URL your application can use to request a token (e.g. https://example.papyrs.com/accounts/sso?app_id=example_app).
Single Sign On flow
The mechanism your application should follow is very simple and consists of the following steps:

  1. Redirect the user to the SSO URL (e.g. https://example.papyrs.com/accounts/sso?app_id=example_app). Your application can append an optional &return_to=url parameter.
  2. Papyrs authenticates the user.
  3. Papyrs creates a signed token (the JWT) containing the details of the authenticated user.
  4. Papyrs redirects the user to your application's CALLBACK_URL, returning the signed token in the ?jwt parameter. If the request in (1) contained a return_to parameter, it is appended to the callback URL. This way you can redirect your user back to the original URL they requested before the SSO flow started.
  5. Your application decodes the token and parses the user details.
Token details
The token (JWT) is returned to your application's CALLBACK_URL in the ?jwt URL parameter. It is signed with the SHARED_SECRET, and contains the following details:
JSON FieldDescription
issThe URL of the Papyrs account which signed the token (Example: 'https://example.papyrs.com')
iatThe time the token was created (Issued At)
jtiA unique id which your app can use to prevent replay attacks
subUnique case-sensitive ID (primary key) to identify the signed in Papyrs user. (Example: 'SxJZ')
emailEmail address of the Papyrs user who is signed in (this address might change over time)
nameDisplay name of the Papyrs user who is signed in
Additional fields might be added in the future. The tokens also include the standard JWT exp and nbf fields which should be used to check if the token is still valid / not expired.