basic docs for remote user auth (#108)

.github/workflows/ci.yml

@@ -2,7 +2,7 @@ name: Deploy 3.1 docs
 on:
   push:
     branches:
-      - "v3.1"
+      - "v3.2"
 
 permissions:
   contents: write
@@ -13,7 +13,7 @@ jobs:
     steps:
       - uses: actions/checkout@v3
         with:
-          ref: "v3.1"
+          ref: "v3.2"
       - uses: actions/setup-python@v4
         with:
           python-version: 3.x
@@ -23,4 +23,4 @@ jobs:
           git fetch origin gh-pages --depth=1
           git config user.name ci-bot
           git config user.email [email protected]
-          poetry run mike deploy -p 3.1 latest --update-aliases
+          poetry run mike deploy -p 3.2 dev --update-aliases

docs/settings/auth.md

@@ -144,3 +144,53 @@ For example, if:
 
 and username is `coco` and, say, LDAP user entry does not feature mail attribute, the
 email assigned to user will be `[email protected]`
+
+
+
+## AUTH__REMOTE
+
+When set to non-empty value it enables remote user authentication support.
+By default this environment variable is not set.
+
+Following examples enable remote user authentication:
+
+    PAPERMERGE__AUTH__REMOTE=1
+
+or
+
+    PAPERMERGE__AUTH__REMOTE=True
+
+or
+
+    PAPERMERGE__AUTH__REMOTE=Yes
+
+
+When remote user authentication is enabled, {{ extra.project }} expects to receive
+user details via following http headers AND cookies:
+
+- `Remote-User` (header) - user's username e.g. `john`
+- `Remote-Groups` (header) - comma delimited list of groups user belongs to e.g. `admin`, `accounting,research`
+- `Remote-Email` (header) - user's email
+- `Remote-Name` (header) - user's name
+- `remote_user` (cookie) - user's username
+- `remote_groups` (cookie) - comma delimited list of groups
+- `remote_email` (cookie)
+- `remote_name` (cookie)
+
+
+!!! Note
+
+    Currently `Remote-Groups` header and `remote_groups` cookie have no effect. User groups will
+    be introduced soon.
+
+
+
+
+## AUTH__REMOTE_LOGOUT_ENDPOINT
+
+When remote user authentication is enabled, it points to the logout endpoint which ends user's session.
+Endpoint must be specified with full URL including scheme, domain and path.
+
+Example:
+
+    PAPERMERGE__AUTH__REMOTE_LOGOUT_ENDPOINT=https://auth.trusel.net/logout