End-User Experience
This document describes what your users will see and do when Single Sign-On (SSO) is enabled on your Paperless account. Share it with your IT team and end users so they know what to expect.
Prerequisites
Before any of the flows below work, the following must be in place:
Your IT team has registered Paperless as an application in your identity provider (Okta or Entra ID). One registration for the device app (Paperless Forms app), and one for the Paperless Forms website.
Paperless Forms Support has been given the configuration values (Authority URL, Client IDs) and has enabled SSO on your company.
Each Paperless Forms user's username matches their corporate email address at the identity provider. If they don't match, the user will not be able to sign in via SSO.
ℹ️Note: SSO is a per-company setting. |
Flow 1 — First sign-in on the Paperless Forms website (account linking)
The first time a user signs in to the Paperless Forms website after SSO is enabled, their Paperless Forms account is automatically linked to their corporate identity.
The user goes to the Paperless website and lands on the login page.
They enter their Paperless Forms username and password as usual.
After their Paperless Forms credentials are accepted, the page redirects to your identity provider (Okta or Entra ID).
They sign in with their corporate credentials.
If your IT team requires multi-factor authentication (MFA), they will be prompted for it here.The identity provider sends them back to Paperless Forms.
Behind the scenes, Paperless Forms checks that the email returned by the identity provider matches the Paperless Forms username. If it does, the account is linked. If it does not, sign-in is refused.
The user lands on their normal Paperless Forms home page, signed in.
ℹ️What "linking" means: Paperless Forms stores a stable identifier from your identity provider on the user record. |
Flow 2 — Subsequent sign-ins on the Paperless Forms website
Once an account is linked, every following sign-in works the same way as the first — but no linking step is needed.
The user enters their Paperless Forms username and password.
They are redirected to the identity provider and sign in with their corporate credentials (and MFA if required).
Paperless Forms verifies that the identity returned matches the linked identifier on the user record.
They land on their normal Paperless Forms home page.
ℹ️If the identity does not match the linked one (for example, someone tries to sign in to a Paperless account that belongs to another corporate identity), sign-in is refused. |
Flow 3 — First sign-in in the app on a device
On a device, the first time a user signs in after SSO is enabled:
The user selects their account on the device and enters their Paperless Forms password as usual.
The device detects that SSO is required and opens a secure browser window.
The user signs in with their corporate credentials (and MFA if required).
The identity provider returns them to the app.
The app verifies the identity (same email-match rule as the website) and links the account on first sign-in.
The user continues into the app normally.
⚠️One-time step: This linking happens only the first time. |
Flow 4 — Day-to-day device usage (background session)
After the first sign-in, the device keeps the user signed in as long as their corporate session is valid. Most of the time, this is invisible to the user.
The device caches a short-lived access token from the identity provider. While it is valid, the user can keep working — even offline.
Shortly before the token expires, the device silently refreshes it in the background, with no user interaction.
If the silent refresh succeeds, the user notices nothing.
If the silent refresh fails (for example, the identity provider revoked the session), the device prompts the user to sign in again through the secure browser window.
⚠️Offline use: The device can continue to operate offline as long as the cached access token has not yet expired. Once it does, the device must reach the identity provider to refresh — so a brief network connection is required at that point. |
Flow 5 — Sign-out and session expiry
Manual sign-out on the website: The user is signed out of Paperless Forms. Depending on your identity provider's settings, they may or may not also be signed out of their corporate session.
Manual sign-out on a device: Same behavior — the user is signed out of Paperless Forms on that device.
Automatic sign-out: If the user's corporate session is revoked or their account is removed from the identity provider, the next refresh attempt will fail and Paperless Forms will sign them out automatically.
Flow 6 — Account changes at the identity provider
Common changes your IT team may make, and what happens in Paperless Forms:
Change at the IdP | Effect in Paperless Forms |
User changes their corporate password | Transparent – they sign in with the new password on next prompt |
MFA reset/New device for MFA | Transparent – they complete the MFA challenge on next prompt |
Account disabled or deleted at the IdP | They are signed out of Paperless Forms on next session check, and cannot sign in again |
User's corporate email is changed | Their Paperless Forms username no longer matches – sign-in will be refused until usernames align |
User is removed from the Paperless Forms application | Same effect as account disabled – they lose access on next session check |
Flow 7 — Admin actions in the Paperless Forms website
A Paperless Forms admin can manage the SSO link on a user account from the Edit Users page
Clear the link: Removing the Subject Identifier from the user lets them go through the first-sign-in linking flow again on their next sign-in. Useful if the wrong corporate identity was linked.
Set the link manually: An admin can paste a Subject Identifier directly onto the user, bypassing the first-sign-in matching step. Useful in advanced scenarios where the email-match rule cannot be satisfied (for example, a user whose corporate email differs from their Paperless username).
Create a new user with an SSO link: When adding a user, an admin can set the Subject Identifier up front so the user is linked from their very first sign-in.
ℹ️The Subject Identifier field appears on the Add User and Edit User pages **only** when SSO is enabled for the company. |
Troubleshooting
Sign-in refused" after entering corporate credentials
The email returned by your identity provider does not match the user's Paperless Forms username. Either correct the Paperless username, correct the email at the identity provider, or have an admin set the Subject Identifier manually.
User is repeatedly prompted to sign in through the corporate browser
The silent refresh is failing. Common causes: the identity provider has revoked the session, the user's account has been disabled, or the corporate password recently changed. Have the user complete the sign-in once to re-establish the session.
User cannot sign in at all after SSO was enabled
Check that the user's Paperless Forms username matches their corporate email exactly. Spaces, case differences, or alias addresses can cause mismatches.
A device is offline and the user is locked out
The access token may have expired while offline. The device needs a brief network connection to refresh the session with the identity provider.
Quick reference
Scenario | What the user does |
Sign in to the website (first time) | Paperless Forms username + password → Corporate sign-in |
Sign in to the website (subsequent) | Paperless Forms username + password → Corporate sign-in |
Sign in on a device (first time) | Paperless Forms username + password → Corporate sign-in in browser window |
Sign in on a device (subsequent) | Paperless Forms username – usually nothing more |
Use a device offline | Paperless Forms username – works until the cached token expires |
Sign out | Use the Paperless Forms sign-out button as usual |
For questions or issues not covered here, contact Paperless Forms Support.