diff --git a/content/en/3.serveex/3.security/3.pocket-id.md b/content/en/3.serveex/3.security/3.pocket-id.md index f372333..d18830b 100644 --- a/content/en/3.serveex/3.security/3.pocket-id.md +++ b/content/en/3.serveex/3.security/3.pocket-id.md @@ -1,21 +1,12 @@ --- title: Pocket ID -description: Install Pocket ID, a lightweight self-hosted OIDC provider using passkeys, as a minimal alternative to Authentik for single sign-on. +description: Install Pocket ID, a lightweight self-hosted OIDC provider that lets you log in to your other apps with a passkey instead of a password. --- :ellipsis{left=0px width=40rem top=10rem blur=140px zIndex=60} -# Pocket ID -::note -🎯 __Objectives:__ - -- Install Pocket ID -- Create your admin account and first passkey -- Register an OIDC client for another app -:: - -[Pocket ID](https://pocket-id.org) is a minimalist, self-hosted OIDC (OpenID Connect) provider. Unlike [Authentik](/serveex/advanced/authentik), it doesn't try to do everything: no LDAP, no proxy outposts, no complex flow builder. It only does one thing: let you log in to OIDC-compatible apps with a **passkey** (fingerprint, face unlock, or security key) instead of a password. +[Pocket ID](https://pocket-id.org) is a minimalist, self-hosted OIDC (OpenID Connect) provider built entirely around passkeys: instead of managing passwords, you and your users log in to compatible apps with a **passkey** (fingerprint, face unlock, or a hardware security key). It runs as a single lightweight container with no external database to manage, and it does exactly one thing well: issuing OIDC logins. This makes it a good fit if you just need a simple, fast SSO backend, for example to pair with [TinyAuth](/serveex/security/tinyauth) as a lightweight forward-auth setup, or to log in directly to apps that natively support OIDC. @@ -33,18 +24,23 @@ root └── data ``` -Create the data folder: +::steps{level="3"} +### Create the data folder ```bash [Terminal] sudo mkdir -p /docker/pocket-id/data ``` -Generate an encryption key for the `.env` file: +### Generate an encryption key ```bash [Terminal] openssl rand -base64 32 ``` +Keep the output, you'll need it for the `.env` file below. + +### Deploy the stack + Open Dockge, click `compose`, name the stack `pocket-id`, and add the following config: ```yaml [compose.yaml] @@ -55,7 +51,6 @@ services: container_name: pocket-id restart: unless-stopped env_file: - - .env volumes: @@ -83,6 +78,8 @@ services: ``` :: +### Set your environment variables + Fill in the `.env` file: ```properties [.env] @@ -99,6 +96,9 @@ TRUST_PROXY=true Deploy the stack. The local interface is available at `http://yourserverip:1411`. +### Done ! +:: + ## First login Pocket ID doesn't use passwords: your first account is created with a **passkey**, which your browser or OS will generate for you (Windows Hello, Touch ID, a phone, or a hardware key like a YubiKey). @@ -118,6 +118,9 @@ Other apps need to reach Pocket ID over HTTPS to complete the OIDC login flow, s We assume you have the subdomain `id.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). :: +::steps{level="3"} +### Add Pocket ID's network to SWAG + Go to Dockge and edit SWAG's compose file by adding Pocket ID's network: ```yaml [compose.yaml] @@ -144,6 +147,8 @@ Redeploy the stack and wait for SWAG to be fully operational. Here we assume the Pocket ID network name is `pocket-id_default`. You can check the connection by visiting SWAG's dashboard at `http://yourserverip:81`. :: +### Create the subdomain.conf file + In the Swag folders, create the file `id.subdomain.conf`: ::tip{icon=""} @@ -182,11 +187,13 @@ server { ::caution -Don't put Pocket ID behind another authentication layer (Authentik, TinyAuth, HTTP auth...). It's the identity provider itself, so locking it away would prevent anyone, including you, from logging in. +Don't put Pocket ID behind another authentication layer (TinyAuth, HTTP auth...). It's the identity provider itself, so locking it away would prevent anyone, including you, from logging in. :: Press :kbd{value="Ctrl+O"}, then :kbd{value="Enter"} to save, and :kbd{value="Ctrl+X"} to exit. +### Visit your new subdomain + Wait a few minutes, then open `https://id.mydomain.com` in your browser. ::caution @@ -194,14 +201,26 @@ Wait a few minutes, then open `https://id.mydomain.com` in your browser. __If it fails:__ check your firewall rules. :: +### Done ! +:: + ## Registering an OIDC client To let another app (e.g. [TinyAuth](/serveex/security/tinyauth)) log in through Pocket ID, you need to register it as an OIDC client: -- Go to `https://id.mydomain.com` -- Log in with your passkey -- Go to _Administration > OIDC Clients_ -- Click _Add OIDC Client_ -- Fill in a name (e.g. `TinyAuth`) and the app's callback URL (provided by the app you're protecting) -- Save, then copy the generated __Client ID__ and __Client Secret__. You'll need them in the other app's configuration +::steps{level="3"} +### Log in to Pocket ID -And that's it! Pocket ID is ready to act as your OIDC provider. Head to the [TinyAuth guide](/serveex/security/tinyauth) to use it as a forward-auth login page for the rest of your apps. +Go to `https://id.mydomain.com` and log in with your passkey. + +### Create the OIDC client + +Go to _Administration > OIDC Clients_, then click _Add OIDC Client_. Fill in a name (e.g. `TinyAuth`) and the app's callback URL (provided by the app you're protecting). + +### Save your client credentials + +Save, then copy the generated __Client ID__ and __Client Secret__. You'll need them in the other app's configuration. + +### Done ! +:: + +Pocket ID is ready to act as your OIDC provider. Head to the [TinyAuth guide](/serveex/security/tinyauth) to use it as a forward-auth login page for the rest of your apps. diff --git a/content/en/3.serveex/3.security/4.tinyauth.md b/content/en/3.serveex/3.security/4.tinyauth.md index d910cc2..fce39ac 100644 --- a/content/en/3.serveex/3.security/4.tinyauth.md +++ b/content/en/3.serveex/3.security/4.tinyauth.md @@ -1,21 +1,12 @@ --- 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. +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. Protect your app behind Swag with forward-auth. --- :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. +[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, checking whether a visitor is authenticated before forwarding them on. 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. @@ -38,13 +29,14 @@ root └── data ``` -Create the data folder: +::steps{level="3"} +### Create the data folder ```bash [Terminal] sudo mkdir -p /docker/tinyauth/data ``` -Generate a password hash for your local account: +### Generate a password hash ```bash [Terminal] sudo docker run -i -t --rm ghcr.io/tinyauthapp/tinyauth:v5 user create --interactive @@ -55,6 +47,8 @@ sudo docker run -i -t --rm ghcr.io/tinyauthapp/tinyauth:v5 user create --interac Enable "Format for Docker" when prompted, so the generated hash is already escaped for use in a `.env` file. :: +### Deploy the stack + Open Dockge, click `compose`, name the stack `tinyauth`, and add the following config: ```yaml [compose.yaml] @@ -88,6 +82,8 @@ services: ``` :: +### Set your environment variables + Fill in the `.env` file: ```properties [.env] @@ -102,6 +98,9 @@ TINYAUTH_AUTH_USERS= Deploy the stack. The local interface is available at `http://yourserverip:3000`. +### Done ! +:: + ## 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. @@ -110,6 +109,9 @@ TinyAuth needs its own subdomain: it's the page users land on before being forwa 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). :: +::steps{level="3"} +### Add TinyAuth's network to SWAG + Go to Dockge and edit SWAG's compose file by adding TinyAuth's network: ```yaml [compose.yaml] @@ -136,6 +138,8 @@ Redeploy the stack and wait for SWAG to be fully operational. Here we assume the TinyAuth network name is `tinyauth_default`. You can check the connection by visiting SWAG's dashboard at `http://yourserverip:81`. :: +### Create the subdomain.conf file + In the Swag folders, create the file `tinyauth.subdomain.conf`: ::tip{icon=""} @@ -174,6 +178,8 @@ server { Press :kbd{value="Ctrl+O"}, then :kbd{value="Enter"} to save, and :kbd{value="Ctrl+X"} to exit. +### Visit your new subdomain + Wait a few minutes, then open `https://tinyauth.mydomain.com` in your browser and log in with the username/password you created above. ::caution @@ -181,13 +187,21 @@ Wait a few minutes, then open `https://tinyauth.mydomain.com` in your browser an __If it fails:__ check your firewall rules. :: +### Done ! +:: + ## Connecting TinyAuth to Pocket ID +::steps{level="3"} +### Register TinyAuth as an OIDC client + 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 ``` +### Add the Pocket ID provider + Copy the __Client ID__ and __Client Secret__ Pocket ID gives you, then edit TinyAuth's `.env` file: ```bash [Terminal] @@ -215,21 +229,29 @@ TINYAUTH_OAUTH_PROVIDERS_POCKETID_SCOPES=openid email profile Press :kbd{value="Ctrl+O"}, then :kbd{value="Enter"} to save, and :kbd{value="Ctrl+X"} to exit. +### Redeploy the stack + 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. +### Done ! +:: -Open the file: +## Protecting an app via reverse proxy +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. + +::steps{level="3"} +### Open the app's subdomain.conf file ```bash [Terminal] sudo nano /docker/swag/config/nginx/proxy-confs/dockge.subdomain.conf ``` +### Add the forward-auth check + Add an internal `/tinyauth` location, and reference it from the app's `location /` block with `auth_request`: ```nginx [dockge.subdomain.conf]{9-11,25} @@ -278,9 +300,70 @@ The `location /tinyauth` block must be able to reach the TinyAuth container by i Press :kbd{value="Ctrl+O"}, then :kbd{value="Enter"} to save, and :kbd{value="Ctrl+X"} to exit. +### Done ! +:: + 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). :: + +## Leaving specific paths public +Sometimes you want most of an app locked behind TinyAuth, but a handful of paths left open, for example a public status page, or the API endpoints a mobile app relies on. Unlike Authentik, TinyAuth has no built-in "authenticated paths" setting for this: it's a plain nginx problem, and it's solved with nginx's own location matching. + +A regex `location` block always takes priority over the plain `location /` block, no matter which one appears first in the file. So any path matched by a regex location you define runs its own `proxy_pass`, without ever reaching the `auth_request /tinyauth;` line in `location /`. + +For example, to leave Uptime-Kuma's public status page and its assets open while protecting everything else: + +```nginx [dockge.subdomain.conf]{9-16} +server { + listen 443 ssl; + listen [::]:443 ssl; + + server_name stats.*; + + include /config/nginx/ssl.conf; + + location ~ ^/(status|assets|icon\.svg|api|upload|metrics) { + include /config/nginx/proxy.conf; + include /config/nginx/resolver.conf; + set $upstream_app uptime-kuma; + set $upstream_port 3001; + set $upstream_proto http; + proxy_pass $upstream_proto://$upstream_app:$upstream_port; + } + + 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 uptime-kuma; + set $upstream_port 3001; + set $upstream_proto http; + proxy_pass $upstream_proto://$upstream_app:$upstream_port; + } +} +``` + +::note + +Adjust the list of excluded paths to what the app you're protecting actually needs public. Never leave an admin or settings path in that list, only what the app itself documents as safe to expose unauthenticated. +::