From 31ba2bd9cdfee1d6c20af16838f2534d4264b3b3 Mon Sep 17 00:00:00 2001 From: Tobias Gesellchen Date: Sun, 26 Jul 2026 21:42:44 +0200 Subject: [PATCH] docs: document and consolidate Management API credential defaults (#586) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary - Documents the default Management API credentials (`admin` / `change_me!`) right where the Local Account tab is introduced (`MUSIC-SERVICES.md`) — surfaced by #269, where the reporter was stuck at an unexplained login prompt. - Consolidates: the defaults now live in one place (`SOUNDTOUCH-SERVICE.md`'s existing Configuration Options table), with the other five mentions across the docs linking to it instead of restating the value independently. - Fixes two factual errors found while consolidating (`SELF-HOSTING.md`): it claimed there's no login by default (wrong — Basic Auth is always on with a published default) and that it protects the Settings tab (wrong — `/api/setup/*` isn't behind Basic Auth at all). Refs #269. ## Test plan - [x] Docs-only change; links verified against existing cross-file anchor conventions used elsewhere in the repo 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Sonnet 5 --- docs/content/docs/concepts/amazon-music-oauth.md | 4 ++++ docs/content/docs/concepts/spotify-oauth.md | 2 +- docs/content/docs/guides/CLOUD-DEPLOY-WALKTHROUGH.md | 7 +++++-- docs/content/docs/guides/MUSIC-SERVICES.md | 10 ++++++++++ docs/content/docs/guides/SELF-HOSTING.md | 6 +++--- docs/content/docs/guides/SOUNDTOUCH-SERVICE.md | 4 +++- 6 files changed, 26 insertions(+), 7 deletions(-) diff --git a/docs/content/docs/concepts/amazon-music-oauth.md b/docs/content/docs/concepts/amazon-music-oauth.md index d3888be..2f1d595 100644 --- a/docs/content/docs/concepts/amazon-music-oauth.md +++ b/docs/content/docs/concepts/amazon-music-oauth.md @@ -279,6 +279,10 @@ Or set the equivalent environment variables: `AMAZON_CLIENT_ID`, `AMAZON_CLIENT_ ### 3. Trigger the OAuth flow +> The commands below use the published default Management API credentials +> (`admin` / `change_me!`); substitute your own if you've changed them (see +> [Configuration Options](../guides/SOUNDTOUCH-SERVICE.md#configuration-options)). + ```bash # Get the LWA authorization URL curl -u admin:change_me! -X POST http://localhost:8000/mgmt/amazon/init diff --git a/docs/content/docs/concepts/spotify-oauth.md b/docs/content/docs/concepts/spotify-oauth.md index 8abba9a..87f930e 100644 --- a/docs/content/docs/concepts/spotify-oauth.md +++ b/docs/content/docs/concepts/spotify-oauth.md @@ -118,6 +118,6 @@ sequenceDiagram ## Security - `/mgmt/spotify/callback` is intentionally outside Basic Auth to allow direct redirects from Spotify's authorization server. -- All other `/mgmt/*` endpoints require Basic Auth as configured by `--mgmt-username` and `--mgmt-password`. +- All other `/mgmt/*` endpoints require Basic Auth as configured by `--mgmt-username` and `--mgmt-password` (defaults documented in [Configuration Options](../guides/SOUNDTOUCH-SERVICE.md#configuration-options)). - Tokens are persisted to disk as JSON with restricted file permissions (`0600`). - The `GetAccounts` endpoint strips sensitive tokens from the response. diff --git a/docs/content/docs/guides/CLOUD-DEPLOY-WALKTHROUGH.md b/docs/content/docs/guides/CLOUD-DEPLOY-WALKTHROUGH.md index 0b74f07..c9fbf8d 100644 --- a/docs/content/docs/guides/CLOUD-DEPLOY-WALKTHROUGH.md +++ b/docs/content/docs/guides/CLOUD-DEPLOY-WALKTHROUGH.md @@ -37,8 +37,11 @@ internet-facing, those endpoints are reachable by anyone who knows the URL. Minimum mitigations before going live: -- Enable **HTTP Basic Auth** on the management UI (set via `MGMT_USERNAME` / - `MGMT_PASSWORD` or the `--mgmt-username` / `--mgmt-password` flags). +- **Change the Management API password** — HTTP Basic Auth on the management + UI is always on, but ships with a published default + (`admin` / `change_me!`); set your own via `MGMT_USERNAME` / + `MGMT_PASSWORD` (or the `--mgmt-username` / `--mgmt-password` flags — see + [Configuration Options](SOUNDTOUCH-SERVICE.md#configuration-options)). - Run AfterTouch **behind a reverse proxy** (Nginx, Caddy, Coolify, Traefik) and consider blocking the `/streaming/*` paths to all but your speaker's IP address at the proxy level if your server/firewall allows it. diff --git a/docs/content/docs/guides/MUSIC-SERVICES.md b/docs/content/docs/guides/MUSIC-SERVICES.md index 8c8e8b0..4f99191 100644 --- a/docs/content/docs/guides/MUSIC-SERVICES.md +++ b/docs/content/docs/guides/MUSIC-SERVICES.md @@ -11,6 +11,16 @@ This guide explains how to link your Spotify or Amazon Music account to AfterTou --- +> **The Local Account tab requires a login.** Authorizing a Spotify or +> Amazon account (Step 3 below) happens on the **Local Account** tab, which +> is protected by AfterTouch's Management API login (HTTP Basic Auth). +> Unless you've changed it, the default is username `admin`, password +> `change_me!` — see +> [Configuration Options](SOUNDTOUCH-SERVICE.md#configuration-options) for +> how to set your own (`MGMT_USERNAME` / `MGMT_PASSWORD`). Your browser will +> prompt for this the first time you open a protected page or click a +> management action — if nothing happens, try reloading the page. + ## How it works Connecting a music service happens in three separate steps, each done once: diff --git a/docs/content/docs/guides/SELF-HOSTING.md b/docs/content/docs/guides/SELF-HOSTING.md index ace0c28..26bc3e5 100644 --- a/docs/content/docs/guides/SELF-HOSTING.md +++ b/docs/content/docs/guides/SELF-HOSTING.md @@ -122,12 +122,12 @@ The easiest solution is to assign a **static (fixed) IP address** to the compute ## Security note -AfterTouch's web interface and management API have no login by default. On a typical home network this is fine, since only devices on your local network can reach it. +The main web interface has no login by default — on a typical home network this is fine, since only devices on your local network can reach it. -If you want to restrict access — for example, on a shared network — start the service with a username and password: +The Management API (Spotify/Amazon account linking, the Local Accounts page) is a separate area that's *always* protected by HTTP Basic Auth, but ships with a published default (`admin` / `change_me!`) — anyone who has read the docs can use it. If you want real protection — for example, on a shared network — set your own: ``` ./soundtouch-service --mgmt-username admin --mgmt-password yourpassword ``` -This protects the Settings tab (where your Spotify and Amazon credentials are stored) from being read or changed by others on the network. +See [Configuration Options](SOUNDTOUCH-SERVICE.md#configuration-options) for the full list of settings and env-var equivalents. Note that this does *not* cover the Settings tab, where your Spotify/Amazon Client ID and Secret are stored — that tab has no separate protection today. diff --git a/docs/content/docs/guides/SOUNDTOUCH-SERVICE.md b/docs/content/docs/guides/SOUNDTOUCH-SERVICE.md index beeb338..69a7464 100644 --- a/docs/content/docs/guides/SOUNDTOUCH-SERVICE.md +++ b/docs/content/docs/guides/SOUNDTOUCH-SERVICE.md @@ -163,7 +163,7 @@ The service supports multiple ways to configure its behavior. When multiple sour | `DATA_DIR` | `--data-dir` | Directory for persistent data | `./data` | | `SERVER_URL` | `--server-url`, `-s` | External URL of this service | `http://:8000` | | `HTTPS_PORT` | `--https-port` | HTTPS port to bind the service to | `8443` | -| `HTTPS_SERVER_URL` | `--https-server-url`, `-S` | External HTTPS URL. An override: when empty it is derived from `SERVER_URL` (same host, `https`, on `HTTPS_PORT`), and can also be viewed/overridden in Settings. | derived from `SERVER_URL` | +| `HTTPS_SERVER_URL` | `--https-server-url`, `-S` | External HTTPS URL. An override: when empty it is derived from `SERVER_URL` (same host, `https`, on `HTTPS_PORT`), and can also be viewed/overridden in Settings. | derived from `SERVER_URL` | | `PYTHON_BACKEND_URL`, `TARGET_URL` | `--target-url` | URL for Python-based service components (legacy) | `http://localhost:8001` | | `REDACT_PROXY_LOGS` | `--redact-logs` | Redact sensitive data in proxy logs | `true` | | `LOG_PROXY_BODY` | `--log-bodies` | Log full request/response bodies | `false` | @@ -174,6 +174,8 @@ The service supports multiple ways to configure its behavior. When multiple sour | `DNS_BIND_ADDR` | `--dns-bind` | Bind address for the DNS discovery server (standard port `:53` is required for DNS/DHCP migration) | `:53` | | `INTERNAL_PATHS` | `--internal-paths` | Paths for internal requests to exclude from recording (e.g., `/setup/*`, `/web/*`) | `[]` | | `DISCOVERY_DISABLED` | | Disable automated device discovery | `false` | +| `MGMT_USERNAME` | `--mgmt-username` | Username for HTTP Basic Auth on the Management API (`/api/mgmt/*`, `/mgmt/*`) — Spotify/Amazon account linking, Local Accounts | `admin` | +| `MGMT_PASSWORD` | `--mgmt-password` | Password for the same Management API Basic Auth. **Change this if AfterTouch is reachable beyond a trusted LAN** — the default is published in this doc. | `change_me!` | | `STOCKHOLM_DIR` | `--stockholm-dir` | Path to extracted Stockholm frontend directory — enables the Stockholm UI when set | *(disabled)* | | `MARGE_URL` | | Streaming/marge base URL used when rewriting `stockholm/json/config.json`. Defaults to `SERVER_URL`. Set to `SERVER_URL/marge` only when using a soundcork backend. | *(same as `SERVER_URL`)* | | `MARGE_AUTH_TOKEN` | | Pre-seeds the Stockholm `margeAuthToken` state (skips the login step for the first session) | *(empty)* |