Cutlery/paperless-ngx
1
0
Fork 0
mirror of https://github.com/paperless-ngx/paperless-ngx.git synced 2026-03-10 11:53:46 -04:00
Code Issues Packages Projects Releases Wiki Activity
Page: Email OAuth App Setup
Pages
Affiliated Projects Backend Snippets Email OAuth App Setup Home Platform‐Specific Troubleshooting Post Consume Script Examples Pre Consume Script Examples Related Projects Scanner & Software Recommendations Using Security Tools with Paperless ngx Using a Reverse Proxy with Paperless ngx Using and Generating ASN Barcodes v3 Ideas List
Clone
18
Email OAuth App Setup
Rick Gray edited this page 2026-03-04 13:15:26 -06:00
Table of Contents

Note

These instructions are user-maintained

See the Paperless-ngx documentation about setting up OAuth. In both cases you will need to specify your Paperless-ngx installation's Redirect URI as e.g. https://paperless.example.com/api/oauth/callback/.

Gmail

See https://support.google.com/cloud/answer/6158849

  1. Login to the Google Cloud Console and create a Project.

  2. In the Cloud Console, navigate to the “APIs & Services” > “Library” section and enable Gmail API

  3. In the Cloud Console, navigate to the “APIs & Services” > “OAuth Consent Screen” section and create a screen. Make no changes to the "Scopes" page.

  4. Under "Audience" invite yourself to the project by "Add users" under Test users.

  5. Under "Clients" create a new "OAuth client", choose a web application and set the authorized javascript origins (e.g. https://paperless.domain.com) and redirect URI (e.g. https://paperless.domain.com/api/oauth/callback/)

  6. Obtain Client ID and Client Secret. Simply copy it in your created "OAuth 2.0 Client IDs" in "Credentials" (Or download the .json files)

  7. Set the appropriate config variables.

  8. Re-deploy Paperless NGX, and "Connect Gmail Account" button will appear under Mail Settings

Outlook

See https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app and https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-configure-app-access-web-apis

  1. Login to the Azure portal, open the App registrations page, and click New registration.

  2. Choose the Supported account types dropdown. For personal M365 accounts, use the option Any Entra ID Tenant + Personal Microsoft accounts.

  3. Set the platform to Web and redirect URI to your own public facing domain with the callback path appended. Example: https://example.domain/api/oauth/callback/

  4. Navigate to the Authentication (Preview) tab, then Settings, then check ID tokens (used for implicit and hybrid flows).

  5. Navigate to the API permissions tab and Add a permission. Click Microsoft Graph, Delegated permissions, and check IMAP.AccessAsUser.All, offline_access, email, openid, and profile. Hit Add permissions to save.

  6. Navigate to the Certificates & secrets tab and add a new Client secret and note this value (not ID).

  7. Finally, on the "Overview" tab obtain the "Application (client) ID".

Notes:

  • After connecting your outlook account in the paperless web UI, the Username field is your email address.
  • When using Outlook, you may need to change the character set in Paperless-ngx to US-ASCII in order to process emails.
  • Enable IMAP access to apps:

outlook.live.com >> Settings >> Forwarding and IMAP >> POP and IMAP >> enable 'Let devices and Apps use IMAP' >> Save

  • Use behind reverse proxy will require additional setup or oauth2 proxy, however access directly to the server may be simpler as setup process is only required to run once.

Feel free to contribute to the wiki pages - enhance and extend the content!

Also browse Discussions & connect in Matrix chat.