Single Sign On

In this document:

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

(Available from Large 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 Activity Directory and Google Apps Single Sign On mechanisms. These mechanisms can also be combined. For example, users can log in to Papyrs with their Active Directory 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) [1]. 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 [email protected]:

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 Field Description
iss The URL of the Papyrs account which signed the token (Example: 'https://example.papyrs.com')
iat The time the token was created (Issued At)
jti A unique id which your app can use to prevent replay attacks
sub Unique case-sensitive ID (primary key) to identify the signed in Papyrs user. (Example: 'SxJZ')
email Email address of the Papyrs user who is signed in (this address might change over time)
name Display 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.

[1] See JWT.io for documentation and libraries for all major languages (including Python, Ruby, C# and so on). For more details see the IETF document.

Printer friendly docs