Add Pocket ID, TinyAuth and File Browser Quantum

2026-08-31 23:39:07 +02:00
parent 91ea3f9a70
commit 4090203dc4
19 changed files with 751 additions and 51 deletions
@@ -0,0 +1,286 @@
+---
+title: TinyAuth
+description: Install TinyAuth, a lightweight forward-auth proxy, and pair it with Pocket ID to add SSO login in front of your self-hosted apps.
+---
+
+
+:ellipsis{left=0px width=40rem top=10rem blur=140px zIndex=60}
+# TinyAuth
+
+::note
+🎯 __Objectives:__
+
+- Install TinyAuth
+- Log in via [Pocket ID](/serveex/security/pocket-id) (OIDC)
+- Protect an app behind Swag with forward-auth
+::
+
+[TinyAuth](https://tinyauth.app) is a small forward-auth proxy: a single login page that Swag can insert in front of any app before letting a request through, similar in spirit to [Authentik](/serveex/advanced/authentik)'s reverse-proxy mode, but without the rest of Authentik's identity-provider machinery.
+
+It supports a simple local username/password login out of the box, and can also delegate login to an external OIDC provider. Here we'll use [Pocket ID](/serveex/security/pocket-id), so anyone visiting a protected app first authenticates with a passkey via Pocket ID, then gets forwarded through.
+
+- [TinyAuth documentation](https://tinyauth.app/docs)
+- [TinyAuth on GitHub](https://github.com/tinyauthapp/tinyauth)
+
+::note
+
+This guide assumes you've already installed [Pocket ID](/serveex/security/pocket-id). You can skip the Pocket ID sections below and use TinyAuth with just a local username/password instead.
+::
+
+## Installation
+Folder structure:
+```text [Directory tree]
+root
+└── docker
+    └── tinyauth
+        ├── compose.yaml
+        ├── .env
+        └── data
+```
+
+Create the data folder:
+
+```bash [Terminal]
+sudo mkdir -p /docker/tinyauth/data
+```
+
+Generate a password hash for your local account:
+
+```bash [Terminal]
+sudo docker run -i -t --rm ghcr.io/tinyauthapp/tinyauth:v5 user create --interactive
+```
+
+::note
+
+Enable "Format for Docker" when prompted, so the generated hash is already escaped for use in a `.env` file.
+::
+
+Open Dockge, click `compose`, name the stack `tinyauth`, and add the following config:
+
+```yaml [compose.yaml]
+---
+services:
+  tinyauth:
+    image: ghcr.io/tinyauthapp/tinyauth:v5
+    container_name: tinyauth
+    restart: unless-stopped
+    env_file:
+
+      - .env
+    volumes:
+
+      - /docker/tinyauth/data:/data
+    ports:
+
+      - 3000:3000
+```
+
+::tip
+✨ Add the Watchtower label to automate updates:
+
+```yaml [compose.yaml]
+services:
+  tinyauth:
+    #...
+    labels:
+
+      - com.centurylinklabs.watchtower.enable=true
+```
+::
+
+Fill in the `.env` file:
+
+```properties [.env]
+TINYAUTH_APPURL=https://tinyauth.mydomain.com
+TINYAUTH_AUTH_USERS=
+```
+
+| Variable | Value | Example |
+|----------|-------|---------|
+| `TINYAUTH_APPURL`{lang=properties} | The public URL you'll use to reach TinyAuth (see exposure below) | `https://tinyauth.mydomain.com` |
+| `TINYAUTH_AUTH_USERS`{lang=properties} | The hash generated above | `user:$$2a$$10$$UdLYoJ5lgPsC0RKq...` |
+
+Deploy the stack. The local interface is available at `http://yourserverip:3000`.
+
+## Exposing TinyAuth with Swag
+TinyAuth needs its own subdomain: it's the page users land on before being forwarded to the app they actually want.
+
+::note
+
+We assume you have the subdomain `tinyauth.mydomain.com` with a `CNAME` pointing to `mydomain.com` in your [DNS zone](/general/networking/dns). And of course, [unless you use Cloudflare Zero Trust](/serveex/security/cloudflare), your box's port `443` must be forwarded to your server's port `443` in [NAT rules](/general/networking/nat).
+::
+
+Go to Dockge and edit SWAG's compose file by adding TinyAuth's network:
+
+```yaml [compose.yaml]
+services:
+  swag:
+     container_name: # ...
+      # ... 
+     networks:               # Attach container to custom network 
+      # ...           
+
+      - tinyauth             # Name of the declared network
+
+networks:                    # Define the custom network
+  # ...
+  tinyauth:                  # Declared network name
+    name: tinyauth_default   # Actual external network name
+    external: true           # Marks it as externally defined
+```
+
+Redeploy the stack and wait for SWAG to be fully operational.
+
+::note
+
+Here we assume the TinyAuth network name is `tinyauth_default`. You can check the connection by visiting SWAG's dashboard at `http://yourserverip:81`.
+::
+
+In the Swag folders, create the file `tinyauth.subdomain.conf`:
+
+::tip{icon=""}
+✨ __Tip:__ Use [File Browser](/serveex/files/file-browser) to navigate and edit files instead of using terminal commands.
+::
+
+```bash [Terminal]
+sudo nano /docker/swag/config/nginx/proxy-confs/tinyauth.subdomain.conf
+```
+
+Paste the following configuration:
+
+```nginx [tinyauth.subdomain.conf]
+## Version 2023/12/19
+
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+
+    server_name tinyauth.*;
+
+    include /config/nginx/ssl.conf;
+
+    client_max_body_size 0;
+
+    location / {
+        include /config/nginx/proxy.conf;
+        include /config/nginx/resolver.conf;
+        set $upstream_app tinyauth;
+        set $upstream_port 3000;
+        set $upstream_proto http;
+        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
+    }
+}
+```
+
+Press :kbd{value="Ctrl+O"}, then :kbd{value="Enter"} to save, and :kbd{value="Ctrl+X"} to exit.
+
+Wait a few minutes, then open `https://tinyauth.mydomain.com` in your browser and log in with the username/password you created above.
+
+::caution
+
+__If it fails:__ check your firewall rules.
+::
+
+## Connecting TinyAuth to Pocket ID
+First, [register TinyAuth as an OIDC client in Pocket ID](/serveex/security/pocket-id#registering-an-oidc-client), using this callback URL:
+
+```text
+https://tinyauth.mydomain.com/api/oauth/callback/pocketid
+```
+
+Copy the __Client ID__ and __Client Secret__ Pocket ID gives you, then edit TinyAuth's `.env` file:
+
+```bash [Terminal]
+sudo nano /docker/tinyauth/.env
+```
+
+Add the following:
+
+```properties [.env]
+TINYAUTH_OAUTH_PROVIDERS_POCKETID_NAME=Pocket ID
+TINYAUTH_OAUTH_PROVIDERS_POCKETID_CLIENTID=
+TINYAUTH_OAUTH_PROVIDERS_POCKETID_CLIENTSECRET=
+TINYAUTH_OAUTH_PROVIDERS_POCKETID_AUTHURL=https://id.mydomain.com/authorize
+TINYAUTH_OAUTH_PROVIDERS_POCKETID_TOKENURL=https://id.mydomain.com/api/oidc/token
+TINYAUTH_OAUTH_PROVIDERS_POCKETID_USERINFOURL=https://id.mydomain.com/api/oidc/userinfo
+TINYAUTH_OAUTH_PROVIDERS_POCKETID_REDIRECTURL=https://tinyauth.mydomain.com/api/oauth/callback/pocketid
+TINYAUTH_OAUTH_PROVIDERS_POCKETID_SCOPES=openid email profile
+```
+
+| Variable | Value |
+|----------|-------|
+| `CLIENTID`{lang=properties} | The client ID copied from Pocket ID |
+| `CLIENTSECRET`{lang=properties} | The client secret copied from Pocket ID |
+| `AUTHURL` / `TOKENURL` / `USERINFOURL`{lang=properties} | Pocket ID's public URL, with the paths shown above |
+
+Press :kbd{value="Ctrl+O"}, then :kbd{value="Enter"} to save, and :kbd{value="Ctrl+X"} to exit.
+
+Redeploy the TinyAuth stack. On your next visit to `https://tinyauth.mydomain.com`, you'll see a "Login with Pocket ID" option alongside the local login form.
+
+::tip
+✨ To skip straight to Pocket ID and hide the local login form, add `TINYAUTH_OAUTH_AUTOREDIRECT=pocketid` to the same `.env` file.
+::
+
+## Protecting an app via reverse proxy
+Unlike Authentik, Swag doesn't ship a ready-made include file for TinyAuth, so we'll add the forward-auth check directly to the app's own `*.subdomain.conf`. We'll use Dockge as an example.
+
+Open the file:
+
+```bash [Terminal]
+sudo nano /docker/swag/config/nginx/proxy-confs/dockge.subdomain.conf
+```
+
+Add an internal `/tinyauth` location, and reference it from the app's `location /` block with `auth_request`:
+
+```nginx [dockge.subdomain.conf]{9-11,25}
+server {
+    listen 443 ssl;
+    listen [::]:443 ssl;
+
+    server_name dockge.*;
+
+    include /config/nginx/ssl.conf;
+
+    client_max_body_size 0;
+
+    location /tinyauth {
+        internal;
+        proxy_pass http://tinyauth:3000/api/auth/nginx;
+        proxy_pass_request_body off;
+        proxy_set_header Content-Length "";
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Host $http_host;
+        proxy_set_header X-Forwarded-Uri $request_uri;
+    }
+
+    location @tinyauth_login {
+        return 302 https://tinyauth.mydomain.com/login?redirect_uri=$scheme://$http_host$request_uri;
+    }
+
+    location / {
+        auth_request /tinyauth;
+        error_page 401 = @tinyauth_login;
+
+        include /config/nginx/proxy.conf;
+        include /config/nginx/resolver.conf;
+        set $upstream_app dockge;
+        set $upstream_port 5001;
+        set $upstream_proto http;
+        proxy_pass $upstream_proto://$upstream_app:$upstream_port;
+    }
+}
+```
+
+::note
+
+The `location /tinyauth` block must be able to reach the TinyAuth container by its Docker name (`tinyauth` here). Add TinyAuth's network to this stack's compose file the same way you did [for Swag](/serveex/security/tinyauth#exposing-tinyauth-with-swag) if it isn't already attached.
+::
+
+Press :kbd{value="Ctrl+O"}, then :kbd{value="Enter"} to save, and :kbd{value="Ctrl+X"} to exit.
+
+That's it! Visiting `https://dockge.mydomain.com` now redirects to TinyAuth first. Repeat this `location /tinyauth` / `auth_request` pattern in any other app's `*.subdomain.conf` to protect it the same way.
+
+::note
+
+Repeat this process for each app you want to protect (unless it has native OIDC support, in which case you can point it directly at Pocket ID instead).
+::