docs(auth): clarify OIDC credential placeholders

.env.example

@@ -1,22 +1,24 @@
 # Since .env is gitignored, you can use .env.example to build a new `.env` file when you clone the repo.
-# Keep this file up-to-date when you add new variables to \`.env\`.
+# Keep this file up-to-date when you add new variables to `.env`.
 
 # This file will be committed to version control, so make sure not to have any secrets in it.
 # If you are cloning this repo, create a copy of this file named `.env` and populate it with your secrets.
 
-# The below secret is not used anywhere but required for Auth.js (Would encrypt JWTs and Mail hashes, both not used)
-AUTH_SECRET="supersecret"
+# Generate two different 64-character hex values with `openssl rand -hex 32` before starting Homarr.
+# Never reuse these values or commit the populated `.env` file.
+AUTH_SECRET=
 
 # The below secret is used to encrypt integration secrets in the database.
-# It should be a 32-byte string, generated by running `openssl rand -hex 32` on Unix
-# or starting the project without any (which will show a randomly generated one).
-SECRET_ENCRYPTION_KEY=0000000000000000000000000000000000000000000000000000000000000000
+# Homarr will reject an empty or invalid value and print a randomly generated candidate.
+SECRET_ENCRYPTION_KEY=
 
 LOG_LEVEL='info'
 
 # This is how you can use the sqlite driver:
 DB_DRIVER='better-sqlite3'
-DB_URL='FULL_PATH_TO_YOUR_SQLITE_DB_FILE'
+# Safe local source-development path. SQLite files are ignored by Git.
+# Container images use /appdata/db/db.sqlite by default instead.
+DB_URL='./db.sqlite'
 
 # Those are the two ways to use the mysql2 driver:
 # 1. Using the URL format:
@@ -63,8 +65,6 @@ UNSAFE_ENABLE_MOCK_INTEGRATION=true
 
 # Public URL contract. Values must be absolute HTTP(S) URLs without credentials,
 # query strings, or fragments. Trailing slashes are normalized at startup.
-# Public Homarr origin used by MCP OAuth metadata and redirects behind proxies.
-# BASE_URL=https://homarr.example.com
 HOMARR_WEBSITE_URL=https://homarr.dev
 # PocketBase API used by Homarr and by the standalone documentation site.
 # Defaults to HOMARR_WEBSITE_URL.

apps/docs/docs/advanced/environment-variables/index.mdx

@@ -30,7 +30,6 @@ Using the `PUID` and `PGID` will require you to set the correct permissions on t
 | `PUID`                   | User ID to run the container as                                                                                                                                                                                                        | Any valid user ID                   | `0`                           |
 | `PGID`                   | Group ID to run the container as                                                                                                                                                                                                       | Any valid group ID                  | `0`                           |
 | `LOG_LEVEL`              | Log level to use                                                                                                                                                                                                                       | `debug` / `info` / `warn` / `error` | `info`                        |
-| `BASE_URL`               | Public Homarr origin used by MCP OAuth metadata and redirects. Set this when a reverse proxy does not preserve the public host and protocol.                                                                                           | HTTP(S) origin without a path       | -                             |
 | `NO_EXTERNAL_CONNECTION` | Disables Homarr's internet-backed requests, including update checks, weather, and RSS feeds                                                                                                                                            | `true` or `false`                   | `false`                       |
 | `ENABLE_DNS_CACHING`     | Enables dns caching. Enabled by default, but if you experience issues with IPv6 or static IPs, see [#4006](https://github.com/homarr-labs/homarr/issues/4006) or disable this flag                                                     | `true` or `false`                   | `true`                        |
 | `HOMARR_DISABLE_IPV6`    | Disables the IPv6 listener of the internal nginx proxy, even when the host supports IPv6. IPv6 is normally disabled automatically when the host has no IPv6 configured. See [#4596](https://github.com/homarr-labs/homarr/issues/4596) | `true` or `false`                   | `false`                       |

apps/docs/docs/advanced/proxy/index.mdx

@@ -40,7 +40,7 @@ services:
     volumes:
       - ./homarr/appdata:/appdata
     environment:
-      - BASE_URL=https://your.internal.dns.address.here.com
+      - BASE_URL=your.internal.dns.address.here.com
       - SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with `openssl rand -hex 32`
     networks:
       - proxy

apps/docs/docs/advanced/single-sign-on/index.mdx

@@ -244,18 +244,21 @@ Homarr supports multiple authentication options, from internal userbase (credent
         - Create a group (e.g., `homarr-admins`) and assign users who require admin access.
 
         **2. Example .env file:**
+
+        Generate `SECRET_ENCRYPTION_KEY` with `openssl rand -hex 32`; do not copy an example key between installs.
+
         ```env
-        OIDC_CLIENT_ID=identificationid #OIDC client ID
-        OIDC_CLIENT_SECRET=secretsecretsecret #OIDC client secret
+        OIDC_CLIENT_ID=<REPLACE_WITH_OIDC_CLIENT_ID>
+        OIDC_CLIENT_SECRET=<REPLACE_WITH_OIDC_CLIENT_SECRET>
         OIDC_SLUG=homarr #Application slug in Authentik
         AUTH_DOMAIN=auth.example.com #Authentik FQDN
         ADMIN_GROUP=homarr-admins #Authentik group for Homarr admins
         HOMARR_FQDN=homarr.example.com #Homarr FQDN
-        SECRET_ENCRYPTION_KEY=encryptencryptencrypt #Homarr encryption key
+        SECRET_ENCRYPTION_KEY=<REPLACE_WITH_64_HEX_CHARACTERS>
         ```
 
         **3. Example Docker Compose configuration:**
-        ```yaml {14-26}
+        ```yaml {14-24}
         services:
           homarr:
             image: ghcr.io/homarr-labs/homarr:latest
@@ -269,8 +272,6 @@ Homarr supports multiple authentication options, from internal userbase (credent
             environment:
               - TZ=America/Los_Angeles
               - SECRET_ENCRYPTION_KEY=${SECRET_ENCRYPTION_KEY}
-              - BASE_URL=https://${HOMARR_FQDN}
-              - NEXTAUTH_URL=https://${HOMARR_FQDN}
               - AUTH_PROVIDERS=oidc #(optional: include ',credentials' to keep local accounts as fallback)
               - AUTH_OIDC_CLIENT_ID=${OIDC_CLIENT_ID}
               - AUTH_OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}
@@ -322,15 +323,18 @@ Homarr supports multiple authentication options, from internal userbase (credent
         - Record the `Client-ID` and `Client Key` (secret).
 
         **2. Example .env file (Homarr):**
+
+        Generate `SECRET_ENCRYPTION_KEY` with `openssl rand -hex 32`; do not copy an example key between installs.
+
         ```env
-        OIDC_CLIENT_ID=identificationid #Google Client-ID
-        OIDC_CLIENT_SECRET=secretsecretsecret #Google Client Key (secret)
+        OIDC_CLIENT_ID=<REPLACE_WITH_GOOGLE_CLIENT_ID>
+        OIDC_CLIENT_SECRET=<REPLACE_WITH_GOOGLE_CLIENT_SECRET>
         HOMARR_FQDN=homarr.example.com #Homarr FQDN
-        SECRET_ENCRYPTION_KEY=encryptencryptencrypt #Homarr encryption key
+        SECRET_ENCRYPTION_KEY=<REPLACE_WITH_64_HEX_CHARACTERS>
         ```
 
         **3. Example Docker Compose configuration (Homarr):**
-        ```yaml {16-22}
+        ```yaml {14-20}
         services:
           homarr:
             image: ghcr.io/homarr-labs/homarr:latest
@@ -344,8 +348,6 @@ Homarr supports multiple authentication options, from internal userbase (credent
             environment:
               - TZ=Europe/Berlin
               - SECRET_ENCRYPTION_KEY=${SECRET_ENCRYPTION_KEY}
-              - BASE_URL=https://${HOMARR_FQDN}
-              - NEXTAUTH_URL=https://${HOMARR_FQDN}
               - AUTH_PROVIDERS=oidc #(optional: include ',credentials' to keep local accounts as fallback)
               - AUTH_OIDC_CLIENT_ID=${OIDC_CLIENT_ID}
               - AUTH_OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}

apps/docs/docs/getting-started/installation/source.mdx

@@ -38,13 +38,14 @@ This method is only useful, when you want to develop on Homarr or extend it with
     Install all dependencies using <code>pnpm install</code>
   </li>
   <li>
-    Copy the `.env.example` file to `.env` and replace `DB_URL` with the full path you want to use for the sqlite
-    database file. For example `DB_URL='/home/username/homarr/db.sqlite`
+    Copy the `.env.example` file to `.env`. Its `DB_URL='./db.sqlite'` value is ready for local use and stores the
+    database in the cloned repository. Replace it with an absolute writable path such as
+    `DB_URL='/home/username/homarr/db.sqlite'` if you want to store the database elsewhere.
   </li>
   <li>
-    Replace `AUTH_SECRET` and `SECRET_ENCRYPTION_KEY` both with a secure random string by using `openssl rand -hex 32`
+    Run `openssl rand -hex 32` twice and set `AUTH_SECRET` and `SECRET_ENCRYPTION_KEY` to the two different generated
+    values. Keep both values secret and preserve `SECRET_ENCRYPTION_KEY` with your backups.
   </li>
-  <li>Replace `CRON_JOB_API_KEY` with a secure random string by using `openssl rand -base64 32`</li>
   <li>Run `pnpm run db:migration:sqlite:run` and wait that it completes</li>
   <li>Build the source using `pnpm build`</li>
   <li>

apps/docs/docs/management/mcp.mdx

@@ -54,10 +54,6 @@ The **AI / MCP** tab on Homarr's API page shows the current endpoint, configurat
 MCP supports API keys and OAuth 2.1 with PKCE. API keys are simpler for direct client configuration; OAuth is available
 for clients that support dynamic authorization.
 
-When Homarr is behind a reverse proxy that does not preserve the public host and protocol, set `BASE_URL` to the exact
-public origin, for example `https://homarr.example.com`. Do not include a path. OAuth clients discover the authorization
-server and protected resource through Homarr's `/.well-known/` routes.
-
 Tools use the permissions of the API key owner or authorized user. Creating a key does not grant additional access.
 Custom Widget and Workshop authoring tools, prompts, and resources are visible only to administrators.
 

apps/nextjs/next.config.ts

@@ -65,15 +65,6 @@ const nextConfig: NextConfig = {
       },
     ],
   },
-  async rewrites() {
-    return [
-      { source: "/.well-known/:path*", destination: "/well-known/:path*" },
-      {
-        source: "/api/mcp/:transport/.well-known/:path*",
-        destination: "/well-known/:path*/api/mcp/:transport",
-      },
-    ];
-  },
   // skipcq: JS-0116
   // eslint-disable-next-line @typescript-eslint/require-await,no-restricted-syntax
   async headers() {

apps/nextjs/src/app/.well-known/oauth-authorization-server/route.ts

@@ -0,0 +1,33 @@
+import { headers } from "next/headers";
+
+import { extractBaseUrlFromHeaders } from "@homarr/common";
+
+const corsHeaders = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, OPTIONS",
+  "Access-Control-Allow-Headers": "*",
+};
+
+export async function GET() {
+  const baseUrl = extractBaseUrlFromHeaders(await headers());
+
+  return Response.json(
+    {
+      issuer: baseUrl,
+      authorization_endpoint: `${baseUrl}/api/mcp/oauth/authorize`,
+      token_endpoint: `${baseUrl}/api/mcp/oauth/token`,
+      registration_endpoint: `${baseUrl}/api/mcp/oauth/register`,
+      response_types_supported: ["code"],
+      grant_types_supported: ["authorization_code"],
+      code_challenge_methods_supported: ["S256"],
+      token_endpoint_auth_methods_supported: ["none"],
+      scopes_supported: ["mcp:tools"],
+      resource_indicators_supported: true,
+    },
+    { headers: corsHeaders },
+  );
+}
+
+export async function OPTIONS() {
+  return new Response(null, { status: 204, headers: corsHeaders });
+}

apps/nextjs/src/app/.well-known/oauth-protected-resource/route.ts

@@ -0,0 +1,25 @@
+import { headers } from "next/headers";
+
+import { extractBaseUrlFromHeaders } from "@homarr/common";
+
+const corsHeaders = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, OPTIONS",
+  "Access-Control-Allow-Headers": "*",
+};
+
+export async function GET() {
+  const baseUrl = extractBaseUrlFromHeaders(await headers());
+
+  return Response.json(
+    {
+      resource: `${baseUrl}/api/mcp`,
+      authorization_servers: [baseUrl],
+    },
+    { headers: corsHeaders },
+  );
+}
+
+export async function OPTIONS() {
+  return new Response(null, { status: 204, headers: corsHeaders });
+}

apps/nextjs/src/app/api/mcp/[transport]/route.spec.ts

@@ -22,10 +22,7 @@ vi.mock("@homarr/auth/api-key", () => ({
   API_KEY_HEADER_NAME: "ApiKey",
   getSessionFromApiKeyAsync: mocks.authenticate,
 }));
-vi.mock("@homarr/common", () => ({
-  extractBaseUrlFromHeaders: () => "http://localhost",
-  removeTrailingSlash: (value: string) => value.replace(/\/+$/u, ""),
-}));
+vi.mock("@homarr/common", () => ({ extractBaseUrlFromHeaders: () => "http://localhost" }));
 vi.mock("@homarr/common/server", () => ({ ipAddressFromHeaders: mocks.ipAddress }));
 vi.mock("@homarr/core/infrastructure/logs", () => ({
   createLogger: () => ({ info: vi.fn(), warn: mocks.loggerWarn, error: vi.fn() }),
@@ -45,7 +42,6 @@ vi.mock("@homarr/custom-widgets/core", () => ({
   getCustomWidgetJsonSchema: () => ({ type: "object", title: "Custom Widget" }),
 }));
 vi.mock("@homarr/db", () => ({ db: {} }));
-vi.mock("~/env", () => ({ env: { BASE_URL: undefined } }));
 vi.mock("~/versions/package-reader", () => ({ getPackageVersion: () => "test-version" }));
 vi.mock("../_extract-tools", () => ({
   extractMcpTools: () => [

apps/nextjs/src/app/api/mcp/_base-url.ts

@@ -1,8 +0,0 @@
-import { extractBaseUrlFromHeaders, removeTrailingSlash } from "@homarr/common";
-
-import { env } from "~/env";
-
-type RequestHeaders = Parameters<typeof extractBaseUrlFromHeaders>[0];
-
-export const getMcpBaseUrl = (headers: RequestHeaders) =>
-  removeTrailingSlash(env.BASE_URL ?? extractBaseUrlFromHeaders(headers));

apps/nextjs/src/app/api/mcp/_handler.ts

@@ -7,7 +7,7 @@ import { z } from "zod/v4";
 import type { McpTool } from "@homarr/api/mcp";
 import { createTRPCContext, mcpRouter } from "@homarr/api/mcp";
 import { API_KEY_HEADER_NAME, getSessionFromApiKeyAsync } from "@homarr/auth/api-key";
-import { removeTrailingSlash } from "@homarr/common";
+import { extractBaseUrlFromHeaders } from "@homarr/common";
 import { ipAddressFromHeaders } from "@homarr/common/server";
 import { createLogger } from "@homarr/core/infrastructure/logs";
 import { buildCustomWidgetMcpPrompt } from "@homarr/custom-widgets/authoring-prompt";
@@ -24,7 +24,6 @@ import { db } from "@homarr/db";
 
 import { getPackageVersion } from "~/versions/package-reader";
 import { getSafeAssistantToolError } from "../assistant/chat/assistant-tool-error";
-import { getMcpBaseUrl } from "./_base-url";
 import { extractMcpTools } from "./_extract-tools";
 import { createMcpProtocolHandler } from "./_protocol";
 
@@ -247,12 +246,6 @@ function jsonErrorResponse(status: number, body: Record<string, string>, extraHe
   });
 }
 
-const getOAuthChallenge = (req: NextRequest) => {
-  const baseUrl = getMcpBaseUrl(req.headers);
-  const resourcePath = removeTrailingSlash(new URL(req.url).pathname);
-  return `Bearer resource_metadata="${baseUrl}/.well-known/oauth-protected-resource${resourcePath}"`;
-};
-
 export const handleMcpRequest = async (req: NextRequest) => {
   const pathname = new URL(req.url).pathname;
   if (pathname.endsWith("/sse") || pathname.endsWith("/message")) {
@@ -276,37 +269,30 @@ export const handleMcpRequest = async (req: NextRequest) => {
 
   if (!apiKeyValue) {
     recordAuthFailure(ipAddress);
+    const baseUrl = extractBaseUrlFromHeaders(req.headers);
     return jsonErrorResponse(
       401,
       {
         error: "unauthorized",
         hint: "Authenticate with an ApiKey header or via OAuth at /.well-known/oauth-authorization-server",
       },
-      { "WWW-Authenticate": getOAuthChallenge(req) },
+      { "WWW-Authenticate": `Bearer resource_metadata="${baseUrl}/.well-known/oauth-protected-resource"` },
     );
   }
 
   if (!apiKeyValue.includes(".")) {
     recordAuthFailure(ipAddress);
-    return jsonErrorResponse(
-      401,
-      { error: "invalid_token", hint: "The token must be in the format '<id>.<token>'." },
-      { "WWW-Authenticate": getOAuthChallenge(req) },
-    );
+    return jsonErrorResponse(401, { error: "invalid_token", hint: "The token must be in the format '<id>.<token>'." });
   }
 
   const session = await getSessionFromApiKeyAsync(db, apiKeyValue, ipAddress, ua);
 
   if (!session) {
     recordAuthFailure(ipAddress);
-    return jsonErrorResponse(
-      401,
-      {
-        error: "invalid_token",
-        hint: "The API key was not found or the token is incorrect.",
-      },
-      { "WWW-Authenticate": getOAuthChallenge(req) },
-    );
+    return jsonErrorResponse(401, {
+      error: "invalid_token",
+      hint: "The API key was not found or the token is incorrect.",
+    });
   }
 
   clearAuthFailures(ipAddress);

apps/nextjs/src/app/api/mcp/oauth/authorize/route.ts

@@ -1,8 +1,8 @@
 import type { NextRequest } from "next/server";
 
 import { auth } from "@homarr/auth/next";
+import { extractBaseUrlFromHeaders } from "@homarr/common";
 
-import { getMcpBaseUrl } from "../../_base-url";
 import { consumePendingAuth, createAuthCode, getClient, storePendingAuth } from "../_store";
 
 export async function GET(req: NextRequest) {
@@ -83,9 +83,8 @@ export async function GET(req: NextRequest) {
     );
   }
 
-  const baseUrl = getMcpBaseUrl(req.headers);
-  const allowedResources = new Set([`${baseUrl}/api/mcp`, `${baseUrl}/api/mcp/mcp`]);
-  if (resource && !allowedResources.has(resource)) {
+  const expectedResource = `${extractBaseUrlFromHeaders(req.headers)}/api/mcp`;
+  if (resource && resource !== expectedResource) {
     return Response.json(
       {
         error: "invalid_target",
@@ -153,7 +152,7 @@ export async function GET(req: NextRequest) {
     );
   }
 
-  const loginUrl = new URL("/auth/login", baseUrl);
+  const loginUrl = new URL("/auth/login", url.origin);
   loginUrl.searchParams.set("callbackUrl", `/api/mcp/oauth/authorize?pending=${id}`);
   return Response.redirect(loginUrl.toString());
 }

apps/nextjs/src/app/well-known/[...path]/route.ts

@@ -1,51 +0,0 @@
-import type { NextRequest } from "next/server";
-
-import { getMcpBaseUrl } from "~/app/api/mcp/_base-url";
-
-const corsHeaders = {
-  "Access-Control-Allow-Origin": "*",
-  "Access-Control-Allow-Methods": "GET, OPTIONS",
-  "Access-Control-Allow-Headers": "*",
-};
-
-export async function GET(req: NextRequest, props: { params: Promise<{ path: string[] }> }) {
-  const [kind, ...rest] = (await props.params).path;
-  const baseUrl = getMcpBaseUrl(req.headers);
-  const identifierPath = rest.join("/");
-
-  if (kind === "oauth-authorization-server") {
-    const issuer = identifierPath ? `${baseUrl}/${identifierPath}` : baseUrl;
-    return Response.json(
-      {
-        issuer,
-        authorization_endpoint: `${baseUrl}/api/mcp/oauth/authorize`,
-        token_endpoint: `${baseUrl}/api/mcp/oauth/token`,
-        registration_endpoint: `${baseUrl}/api/mcp/oauth/register`,
-        response_types_supported: ["code"],
-        grant_types_supported: ["authorization_code"],
-        code_challenge_methods_supported: ["S256"],
-        token_endpoint_auth_methods_supported: ["none"],
-        scopes_supported: ["mcp:tools"],
-        resource_indicators_supported: true,
-      },
-      { headers: corsHeaders },
-    );
-  }
-
-  if (kind === "oauth-protected-resource") {
-    const resource = identifierPath ? `${baseUrl}/${identifierPath}` : `${baseUrl}/api/mcp`;
-    return Response.json(
-      {
-        resource,
-        authorization_servers: [baseUrl],
-      },
-      { headers: corsHeaders },
-    );
-  }
-
-  return Response.json({ error: "not_found" }, { status: 404, headers: corsHeaders });
-}
-
-export async function OPTIONS() {
-  return new Response(null, { status: 204, headers: corsHeaders });
-}

apps/nextjs/src/env.ts

@@ -16,15 +16,8 @@ const publicHttpUrl = (variableName: string) =>
     }
   });
 
-const publicHttpOrigin = (variableName: string) =>
-  publicHttpUrl(variableName).refine(
-    (value) => value === new URL(value).origin,
-    `${variableName} must be an HTTP(S) origin without a path`,
-  );
-
 export const env = createEnv({
   server: {
-    BASE_URL: publicHttpOrigin("BASE_URL").optional(),
     UNSAFE_ENABLE_MOCK_INTEGRATION: createBooleanSchema(false),
     DEMO_MODE: createBooleanSchema(false),
     DEMO_READ_ONLY: createBooleanSchema(true),