Skip to main content

How to set up your SSO with Paperless Forms – Identity Provider Setup Guide

#App #Website #SSOLogin

Identity Provider Setup Guide

This guide walks your IT/identity team through registering Paperless with your identity provider (Okta or Microsoft Entra ID) so your organization's users can sign in to Paperless using your existing single sign-on.

Overview

Paperless ships in two main applications:

Application

Where it runs

Paperless Forms iPad & Windows App

iPad and Windows devices

Paperless Forms Website (Admin)

A browser, used by administrators and support

Paperless Forms Web App

iOS, Windows and Android devices

Each one needs its own registration in your identity provider, because they authenticate differently (a mobile/desktop app uses different OAuth flows than a website).

You will create two app registrations total, then share their identifiers with Paperless Forms support, who will activate SSO for your organization.

Before you start

Have ready:

  • Admin access to your identity provider (Okta admin console, or Microsoft Entra admin center)

  • A test user account you can use to verify the setup

  • ~30 minutes

Then, decide on:

  • Whether all users in your organization can use Paperless via SSO, or only specific groups

Microsoft Entra ID Setup

ℹ️ If your organization uses Okta instead, skip to the Okta section.

Step 1 — Create the Paperless Forms app (for the app on devices)

  1. Sign in to Microsoft Entra admin center (https://entra.microsoft.com)

  2. Go to Identity → Applications → App registrations

  3. Click + New registration

  4. For Name, use "Paperless Device" (or anything you like)

  5. For Supported account types, select Accounts in this organizational directory only (single tenant) — unless you specifically need multi-tenant

  6. For Redirect URI, leave blank for now (we'll add platforms in a moment)

  7. Click Register

  8. Copy the Application (client) ID displayed at the top — you'll send this to Paperless support

  9. In the left menu, click Authentication

  10. Click + Add a platform → choose Mobile and desktop applications

  11. Add the following custom redirect URIs (one at a time):

    • http://localhost:7890/callback

    • com.peak.pelican://oauth/callback

  12. Click Save

  13. Still on the Authentication page, scroll to Advanced settings:

    • Set Allow public client flows to Yes

  14. Click Save

Step 2 — Create the Paperless Web app (for the admin website)

  1. Go to Identity → Applications → App registrations

  2. Click + New registration

  3. For Name, use "Paperless Web" (or anything you like)

  4. For Supported account types, select the same option you selected for the devices in Step 1.5

  5. For Redirect URI, select platform Single-page application (SPA) from the dropdown, then add:

    • If your database is on the US infrastructure:
      ​​https://paperless.datahex.ca/Login/SsoCallback

    • If your database is on the CA infrastructure:
      ​​https://ca-paperless.datahex.ca/Login/SsoCallback

  6. Click Register

  7. Copy the Application (client) ID

Step 3 — Configure API permissions (both apps)

For each of the two apps, do the following:

  1. Click into the app

  2. In the left menu, click on API permissions

  3. Verify Microsoft Graph → User.Read (delegated) is listed (it's there by default)

  4. Click + Add a permission → Microsoft Graph → Delegated permissions → search for and add:

    • "openid"

    • "profile"

    • "email"

    • "offline_access"

  5. Click Save

  6. If your tenant requires admin consent, click Grant admin consent for [your tenant] and approve

Step 4 — Token configuration (OPTIONAL)

To ensure the user's email is reliably available in the ID token:

  1. In the left menu, click on Token configuration

  2. Click + Add optional claim

  3. For Token type ID, select claims: "email", "preferred_username"

  4. Click Save

Step 5 — Send to Paperless

Email Paperless support with:

  • Identity provider: Microsoft Entra ID

  • Tenant ID: found on the Entra admin center home page (e.g., "12345678-1234-1234-1234-123456789abc")

  • Authority: https://login.microsoftonline.com/<your-tenant-id>/v2.0

  • Paperless Device Client ID: from Step 1

  • Paperless Web Client ID: from Step 2

Paperless support will enable SSO for your account using these values.

Okta Setup

ℹ️ If your organization uses Microsoft Entra ID instead, skip to the Entra ID section.

Step 1 — Create the Paperless Forms iOS/Windows App (for the iOS & Windows version on devices)

  1. Sign in to your Okta admin console (e.g., https://yourcompany-admin.okta.com)

  2. From the left menu, go to Applications and Resources → Applications

  3. Click Create App Integration

  4. Select Classic experience

  5. Select:

    • Sign-in method: OIDC - OpenID Connect

    • Application type: Native Application

  6. Click Next

  7. In General Settings:

    • For App integration name, use Paperless App, or anything you prefer

    • For Client definition, select Use Okta-generated client ID

    • For Proof of possession, leave unchecked

    • For Grant type, make sure to check both options as they are required:

      • Authorization Code

      • Refresh Token

    • For Sign-in redirect URIs, remove the default value(s) and add both of the following (one per line):

      • http://localhost:7890/callback

      • ca.datahex.paperless://oauth/callback

    • For Sign-out redirect URIs, leave empty/remove the default value(s)

    • For Assignments, choose who can use Paperless Forms:

      • Allow everyone in your organization to access

        • For Enable immediate access, keep this option checked according to your preference

        OR

      • Limit access to selected groups, which you can use to pick a specific Okta group

        • Specify the Selected group(s) that will have access

  8. Click Save

  9. In the app's General tab, verify under Client Credentials:

    • For Client authentication, select None

    • For Proof Key for Code Exchange (PKCE), check the option Require PKCE as additional verification

  10. Create a new Text (.txt) document

  11. Create a line called Paperless App ID:

  12. Copy the Client ID from the app's General tab, which is a long string starting with 0oa...

  13. Paste it in the Text document next to Paperless App ID:

  14. Continue to the next step to gather the next ID

Step 2 — Create the Paperless Website App (for the admin website)

  1. Sign in to your Okta admin console (e.g., https://yourcompany-admin.okta.com)

  2. From the left menu, go to Applications and Resources → Applications

  3. Click Create App Integration

  4. Select Classic experience

  5. Select:

    • Sign-in method: OIDC - OpenID Connect

    • Application type: Single-Page Application

  6. Click Next

  7. In General Settings:

    • For App integration name, use Paperless Website, or anything you prefer

    • For Client definition, select Use Okta-generated client ID

    • For Proof of possession, leave unchecked

    • For Grant type, make sure to check both options as they are required:

      • Authorization Code

      • Refresh Token

    • For Sign-in redirect URIs, add:

      • If your database is on the US infrastructure:
        ​​https://paperless.datahex.ca/Login/SsoCallback

      • If your database is on the CA infrastructure:
        ​​https://ca-paperless.datahex.ca/Login/SsoCallback

    • For Sign-out redirect URIs, leave empty/remove the default value(s)

    • For Trusted Origins, leave empty/remove the default value(s)

    • For Assignments, choose who can use Paperless Forms:

      • Allow everyone in your organization to access

        • For Enable immediate access, keep this option checked according to your preference

        OR

      • Limit access to selected groups, which you can use to pick a specific Okta group

        • Specify the Selected group(s) that will have access

  8. Click Save

  9. In the app's General tab, verify under Client Credentials:

    • For Client authentication, select None

    • For Proof Key for Code Exchange (PKCE), check the option Require PKCE as additional verification

  10. Create a new Text (.txt) document

  11. Create a line called Paperless Website ID:

  12. Copy the Website ID from the app's General tab, which is a long string starting with 0oa...

  13. Paste it in the Text document next to Paperless Website ID:

  14. If you are using the Paperless Forms Web App, continue to the next step to gather the next ID

Step 3 — Create the Paperless Forms WebApp App (for the Web App version on devices)

ℹ️ If you are not using the Web App version, this step is unecessary.

  1. Sign in to your Okta admin console (e.g., https://yourcompany-admin.okta.com)

  2. From the left menu, go to Applications and Resources → Applications

  3. Click Create App Integration

  4. Select Classic experience

  5. Select:

    • Sign-in method: OIDC - OpenID Connect

    • Application type: Single-Page Application

  6. Click Next

  7. In General Settings:

    • For App integration name, use Paperless WebApp, or anything you prefer

    • For Client definition, select Use Okta-generated client ID

    • For Proof of possession, leave unchecked

    • For Grant type, make sure to check both options as they are required:

      • Authorization Code

      • Refresh Token

    • For Sign-in redirect URIs, add:

      • If your database is on the US infrastructure:
        ​​https://paperless-webapp.datahex.ca/sso/callback

      • If your database is on the CA infrastructure:
        ​​​​https://ca-paperless-webapp.datahex.ca/sso/callback

    • For Sign-out redirect URIs, add:

      • If your database is on the US infrastructure:
        ​​https://paperless-webapp.datahex.ca

      • If your database is on the CA infrastructure:
        ​​​​https://ca-paperless-webapp.datahex.ca

    • For Trusted Origins, add:

      • If your database is on the US infrastructure:
        ​​https://paperless-webapp.datahex.ca

      • If your database is on the CA infrastructure:
        ​​​​https://ca-paperless-webapp.datahex.ca

    • For Assignments, choose who can use Paperless Forms:

      • Allow everyone in your organization to access

        • For Enable immediate access, keep this option checked according to your preference

        OR

      • Limit access to selected groups, which you can use to pick a specific Okta group

        • Specify the Selected group(s) that will have access

  8. Click Save

  9. In the app's General tab, verify under Client Credentials:

    • For Client authentication, select None

    • For Proof Key for Code Exchange (PKCE), check the option Require PKCE as additional verification

  10. Create a new Text (.txt) document

  11. Create a line called Paperless WebApp ID:

  12. Copy the WebApp ID from the app's General tab, which is a long string starting with 0oa...

  13. Paste it in the Text document next to Paperless WebApp ID:

Step 4 — Allow both apps in the authorization server policy

Okta has a separate set of policies controlling which apps can request tokens.
By default, new apps may not be permitted.

  1. Go to Security → API → Authorization Servers

  2. Click the default authorization server

  3. Click the Access Policies tab

  4. Click Add Policy

  5. In Add Policy:

    • Name the policy

    • Add a Description

    • In Assign to, choose The following clients and add:

      • Paperless App (or the name you gave it in Step 1)

      • Paperless Website (or the name you gave it in Step 2)

      • Optionally, Paperless WebApp (or the name you gave it in Step 3)

  6. Click Create Policy

  7. At the bottom of the new policy, click on Add rule:

    • Name the rule

    • For Grant type, select Core grants → Authorization Code, uncheck Device Authorization

    • For User, select Any user assigned the app

    • For Scopes requested, select The following scopes and add:

      • openid

      • profile

      • email

      • offline_access

    • For Use this inline hook, select None (disabled)

    • For Access token lifetime, select your preference

    • For Refresh token lifetime, select your preference

  8. Click Create rule

  9. Make sure the Status is set to Active

Step 5 — Send the credentials to Paperless Forms' team

Email Paperless Forms support the Text document that was built over the previous steps.

  • Identity provider: Okta

  • Okta domain (Authority): e.g., https://yourcompany.okta.com/oauth2/default

  • Paperless App ID: The 0oa... value from Step 1

  • Paperless Website ID: The 0oa... value from Step 2

  • Paperless WebApp ID: The 0oa... value from Step 3, optionally

Paperless Forms support will enable SSO for your account using these values.

Common pitfalls

Why does Paperless need up to three apps?

Mobile/desktop apps use a different OAuth flow than browser apps. Identity providers require separate registrations because they have different redirect URI requirements (custom URL schemes vs. HTTPS).

My Okta app keeps showing invalid_token_endpoint_auth_method during testing.

This means that the application was created or configured with Client authentication set to Client secret.

  1. Go to Applications and ressources → Applications

  2. Click on the app you want to edit

  3. In the General tab, edit the Client authentication from Secret client to None

My users get no_matching_policy when signing in

Step 4 of the Okta setup is incomplete.

  1. Go to Security → API → Authorization Servers

  2. Click the default authorization server

  3. In the Access Policies tab, ensure that the applications created in Steps 1 and 2 (and optionally 3) have the rule created in Step 4 assigned to them, and that its Status is set to Active

My users get access denied even though they're in Okta

  1. Go to Applications and ressources → Applications

  2. Click on the app you want to edit

  3. In the Assignments tab, add the group(s) or set the application to Allow everyone in your organization to access

Can we reuse one app for both Device and Web?

In Okta: No, the app types are different (Native vs. Single-Page Application) and the allowed redirect URI formats don't overlap.

In Microsoft Entra: Technically possible (one app with multiple platform configurations), but we recommend separate apps for better audit logging and per-platform policy control.

Will users see a consent screen?

The first time a user signs in, they may be prompted to consent to the requested permissions (the "openid", "profile", "email" claims).

For Microsoft Entra, an admin can pre-grant consent for the entire tenant under API permissions → Grant admin consent to skip this.

What happens after setup

Once you provide the Client IDs and Authority to Paperless Forms support:

  1. Paperless Forms support enables SSO for your organization

  2. Your users open Paperless Forms on their devices, sign in with their Paperless Forms username and password as usual

  3. After validating their Paperless Forms credentials, the app will redirect them to your identity provider's sign-in page (Okta or Microsoft sign-in)

  4. After they sign in with their company SSO credentials, they're returned to Paperless Forms and can use the app normally

The same flow applies for the Paperless website.

If a user's identity provider account is later disabled (e.g., they leave the company), they will lose access to Paperless within a short period — even if their Paperless Forms password still exists, the SSO check will fail.

Did this answer your question?