Multi-user/service account driven paperless integration

[tecosaur]

Hi Sassanix,

If you haven't guessed by my recent issues around claims, since first trying Warracker a few months ago and PRing some improvements to OIDC to make it more well-behaved, I've been regularly using/appreciating it. Thanks again for all your work on this! 😀

The minor enhancements I mentioned in my recent issues aside, there are two changes that would allow Warracker to integrate much better with my self-hosted stack:

1. Better support for declarative configuration (I've implemented this myself in 3988892, I should probably put a PR up)
2. Support for multi-user paperless, via a service account

The current paperless integration

I'd like to lay out what I have in mind with (2), and why I think it would be a valuable change.

My current understanding of the paperless integration is:

• I get an "API Auth Token" for my paperless account
• I go to the admin settings in Warracker, and give it my token
• Warracker is able to view/upload documents with my paperless account

There are a few implications of this design that make it a hard sell for me, as much as I'd like to integrate paperless and Warracker.

Security

The paperless API token allows complete access to my account. While I don't expect Warracker to try anything nefarious, this breaks the Principle of Least Privilege. I'd feel much happier knowing that Warracker only had access to documents managed with Warracker.

Multi-user support

I run my self-hoststed stack for my family. Each user has their own paperless account (also managed through SSO). From my understanding, if I were to enable the paperless integration currently, everybody's uploads would end up in my account. What I'd really like is for everybody's paperless account to have access to just their uploads.

This could be addressed with per-user paperless tokens, but when accounts are managed by SSO (as seems increasingly common), I think there's a better way.

Service account proposal

I've been having a look at the paperless API docs, and I think that paperless integration could be managed very nicely with a service account, thanks to the existence of sharing permissions. I see it working something like this:

Setup

• I create a warracker account in paperless
• I cannot get an API token for this account easily (without logging in as warracker, etc.), but I can set the password used during account creation (and if I find a way to automate paperless setup, this can be included)
• Warracker uses GET /api/token/ to turn the service account username + password into an API token

Flow 1 (upload from Warracker)

• I upload a document in Warracker, with service-account paperless integration
• Warracker uploads the document under the warracker account to paperless using POST /api/documents/post_document
• Since SSO is used for both Warraker and Paperless, Warracker can get my user ID from GET /api/users/ (cached, re-fetched if the user in question isn't found). Matching should be done by username. Ideally the sub OIDC claim would be used, but I don't see any easy way this could be done.
• With my user ID, Warracker can call PATCH /api/documents/{id} and update set_permissions.view.users to add my user account

Flow 2 (linking already-uploaded documents)

• I have already got a receipt/invoice/etc. in paperless
• Warracker's service account uses GET /api/documents/ to find documents I have shared with the service account
• GET /api/documents/{id}/preview/ is used to get preview images for the documents
• I pick a document in Warracker

Unless I've missed something, using a service account in this way should allow Warracker to more elegantly and safely integrate with paperless.

Please let me know what you think 🙂

[Salvoxia]

I came here to ask for the same enhancement, my use case is pretty much identical (Paperless and Warracker using OIDC).
@tecosaur : Not sure if I understand your service account proposal 100% correctly.
For Flow 1 you describe

• Since SSO is used for both Warraker and Paperless, Warracker can get my user ID from GET /api/users/ (cached, re-fetched if the user in question isn't found). Matching should be done by username. Ideally the sub OIDC claim would be used, but I don't see any easy way this could be done.
• With my user ID, Warracker can call PATCH /api/documents/{id} and update set_permissions.view.users to add my user account

That sounds elegant, but if I understand that right this flow only works for users who use OIDC for both Warracker and Paperless. IMHO there should also be a way for users who don't use ODIC for any of these applications for whatever reason.

So I think this a two-step approach:

1. Implementing per-user Paperless API Tokens is the way that will always work
2. Using a Warracker service account in paperless might be an alternative for setups that support the flows

Then again, the question arises whether the benefits of no 2 are worth the additional implementation/maintenance effort if no 1 is already implemented in the first place.

[tecosaur]

That sounds elegant, but if I understand that right this flow only works for users who use OIDC for both Warracker and Paperless.

Indeed. Without OIDC, it's not reasonable to assume that people will share the same username across services I think.

Implementing per-user Paperless API Tokens is the way that will always work

Functionally, this is a viable alternative, though it does make it possible to accidentally delete a document used by Warracker, which can be avoided through the service account (one of the other reasons why I feel it's a good approach).

My main issue with per-user API tokens though is simply that no matter how clear the instructions are, non-techy friends/family that use it will not set it up.

[Salvoxia]

My main issue with per-user API tokens though is simply that no matter how clear the instructions are, non-techy friends/family that use it will not set it up.

Point taken. Since the Paperless API provides an endpoint to issue an API token with /api/token/, authenticating with username and password, that might be a viable alternative, requiring the Warracker user to enter their Paperless credentials for obtaining an API token. However, this might only work with local paperless accounts, not sure how it could work if paperless uses OIDC.