mirror of
https://github.com/paperless-ngx/paperless-ngx.git
synced 2025-10-30 03:56:23 -05:00
Documentation: improve permissions docs (#6046)
This commit is contained in:
shamoon
@@ -206,12 +206,12 @@ for details.
|
||||
|
||||
## Permissions
|
||||
|
||||
As of version 1.14.0 Paperless-ngx added core support for user / group permissions. Permissions is
|
||||
based around 'global' permissions as well as 'object-level' permissions. Global permissions designate
|
||||
which parts of the application a user can access (e.g. Documents, Tags, Settings) and object-level
|
||||
determine which objects are visible or editable. All objects have an 'owner' and 'view' and 'edit'
|
||||
permissions which can be granted to other users or groups. The paperless-ngx permissions system uses
|
||||
the built-in user model of the backend framework, Django.
|
||||
Permissions in Paperless-ngx are based around ['global' permissions](#global-permissions) as well as
|
||||
['object-level' permissions](#object-permissions). Global permissions determine which parts of the
|
||||
application a user can access (e.g. Documents, Tags, Settings) and object-level determine which
|
||||
objects are visible or editable. All objects have an 'owner' and 'view' and 'edit' permissions which
|
||||
can be granted to other users or groups. The paperless-ngx permissions system uses the built-in user
|
||||
model of the backend framework, Django.
|
||||
|
||||
!!! tip
|
||||
|
||||
@@ -219,37 +219,63 @@ the built-in user model of the backend framework, Django.
|
||||
for a Tag will _not_ affect the permissions of documents that have the Tag.
|
||||
|
||||
Permissions can be set using the new "Permissions" tab when editing documents, or bulk-applied
|
||||
in the UI by selecting documents and choosing the "Permissions" button. Owner can also optionally
|
||||
be set for documents uploaded via the API. Documents consumed via the consumption dir currently
|
||||
do not have an owner set.
|
||||
|
||||
!!! note
|
||||
|
||||
After migration to version 1.14.0 all existing documents, tags etc. will have no explicit owner
|
||||
set which means they will be visible / editable by all users. Once an object has an owner set,
|
||||
only the owner can explicitly grant / revoke permissions.
|
||||
|
||||
!!! note
|
||||
|
||||
When first migrating to permissions it is recommended to use a 'superuser' account (which
|
||||
would usually have been setup during installation) to ensure you have full permissions.
|
||||
|
||||
Note that superusers have access to all objects.
|
||||
in the UI by selecting documents and choosing the "Permissions" button.
|
||||
|
||||
### Default permissions
|
||||
|
||||
Default permissions for documents can be set using workflows.
|
||||
[Workflows](#workflows) provide advanced ways to control permissions.
|
||||
|
||||
For objects created via the web UI (tags, doc types, etc.) the default is to set the current user
|
||||
as owner and no extra permissions, but you explicitly set these under Settings > Permissions.
|
||||
as owner and no extra permissions, but you can explicitly set these under Settings > Permissions.
|
||||
|
||||
Documents consumed via the consumption directory do not have an owner or additional permissions set by default, but again, can be controlled with [Workflows](#workflows).
|
||||
|
||||
### Users and Groups
|
||||
|
||||
Paperless-ngx versions after 1.14.0 allow creating and editing users and groups via the 'frontend' UI.
|
||||
These can be found under Settings > Users & Groups, assuming the user has access. If a user is designated
|
||||
Paperless-ngx supports editing users and groups via the 'frontend' UI, which can be found under
|
||||
Settings > Users & Groups, assuming the user has access. If a user is designated
|
||||
as a member of a group those permissions will be inherited and this is reflected in the UI. Explicit
|
||||
permissions can be granted to limit access to certain parts of the UI (and corresponding API endpoints).
|
||||
|
||||
!!! note
|
||||
|
||||
Superusers can access all parts of the front and backend application as well as any and all objects.
|
||||
|
||||
#### Detailed Explanation of Global Permissions {#global-permissions}
|
||||
|
||||
Global permissions define what areas of the app and API endpoints the user can access. For example, they
|
||||
determine if a user can create, edit, delete or view _any_ documents, but individual documents themselves
|
||||
still have "object-level" permissions.
|
||||
|
||||
| Type | Details |
|
||||
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Admin | _View_ or higher permissions grants access to the logs view as well as the system status. |
|
||||
| AppConfig | _Change_ or higher permissions grants access to the "Application Configuration" area. |
|
||||
| Correspondent | Grants global permissions to add, edit, delete or view Correspondents. |
|
||||
| CustomField | Grants global permissions to add, edit, delete or view Custom Fields. |
|
||||
| Document | Grants global permissions to add, edit, delete or view Documents. |
|
||||
| DocumentType | Grants global permissions to add, edit, delete or view Document Types. |
|
||||
| Group | Grants global permissions to add, edit, delete or view Groups. |
|
||||
| MailAccount | Grants global permissions to add, edit, delete or view Mail Accounts. |
|
||||
| MailRule | Grants global permissions to add, edit, delete or view Mail Rules. |
|
||||
| Note | Grants global permissions to add, edit, delete or view Notes. |
|
||||
| PaperlessTask | Grants global permissions to view or dismiss (_Change_) File Tasks. |
|
||||
| SavedView | Grants global permissions to add, edit, delete or view Saved Views. |
|
||||
| ShareLink | Grants global permissions to add, delete or view Share Links. |
|
||||
| StoragePath | Grants global permissions to add, edit, delete or view Storage Paths. |
|
||||
| Tag | Grants global permissions to add, edit, delete or view Tags. |
|
||||
| UISettings | Grants global permissions to add, edit, delete or view the UI settings that are used by the web app.<br/>Users expected to access the web UI should usually be granted at least _View_ permissions. |
|
||||
| User | Grants global permissions to add, edit, delete or view Users. |
|
||||
| Workflow | Grants global permissions to add, edit, delete or view Workflows.<br/>Note that Workflows are global, in other words all users who can access workflows have access to the same set of them. |
|
||||
|
||||
#### Detailed Explanation of Object Permissions {#object-permissions}
|
||||
|
||||
| Type | Details |
|
||||
| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Owner | By default objects are only visible and editable by their owner.<br/>Only the object owner can grant permissions to other users or groups.<br/>Additionally, only document owners can create share links and add / remove custom fields.<br/>For backwards compatibility objects can have no owner which makes them visible to any user. |
|
||||
| View | Confers the ability to view (not edit) a document, tag, etc.<br/>Users without 'view' (or higher) permissions will be shown _'Private'_ in place of the object name for example when viewing a document with a tag for which the user doesn't have permissions. |
|
||||
| Edit | Confers the ability to edit (and view) a document, tag, etc. |
|
||||
|
||||
### Password reset
|
||||
|
||||
In order to enable the password reset feature you will need to setup an SMTP backend, see
|
||||
|
||||
Reference in New Issue
Block a user