Implementing SSO between Papyrs and other applications using JSON Web Tokens (JWTs)
(Available from Papyrs Business 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, Google Apps (G Suite) Single Sign On, and Slack 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 PapyrsIn 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 flowThe mechanism your application should follow is very simple and consists of the following steps:
- 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=urlparameter. - Papyrs authenticates the user.
- Papyrs creates a signed token (the JWT) containing the details of the authenticated user.
- Papyrs redirects the user to your application's
CALLBACK_URL, returning the signed token in the?jwtparameter. If the request in (1) contained areturn_toparameter, 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. - Your application decodes the token and parses the user 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 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.