Email OAuth App Setup - paperless-ngx/paperless-ngx GitHub Wiki

[!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 "Credentials" create a new "OAuth client ID", choose a web application and set the authorized javascript origins and redirect URI

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

  6. Set the appropriate config variables.

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 account type (single tenant vs multi-tenant). For personal M365 accounts use the option Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox).

  3. Set redirect URI. https://example.domain/api/oauth/callback

  4. Navigate to the Authentication tab. Set "Implicit grant and hybrid flows" to allow both access and id tokens,

  5. Navigate to the Certificates & Secrets tab and add a new secret and note this value (not ID).

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

Notes:

  • 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.