fix: unreachable OIDC on dev mode

Signed-off-by: BoxBoxJason <contact@boxboxjason.dev>

Author: BoxBoxJason

README.md

@@ -270,6 +270,9 @@ backend:
     - AUTH_MODE=oidc_enforced
     - OIDC_PROVIDER_NAME=Authentik
     - OIDC_ISSUER_URL=https://auth.example.com/application/o/excalidash/
+    # Optional split-horizon setup when backend reaches IdP via internal DNS.
+    # Keep OIDC_ISSUER_URL browser-routable; set OIDC_DISCOVERY_URL for backend-only access.
+    # - OIDC_DISCOVERY_URL=http://auth-internal:9000/application/o/excalidash/
     - OIDC_CLIENT_ID=your-client-id
     # Optional for public clients; required for confidential clients
     # - OIDC_CLIENT_SECRET=your-client-secret
@@ -287,6 +290,7 @@ Notes:
 | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
 | OIDC-only (`oidc_enforced`) | You typically do not use local bootstrap admin registration; first admin can be created through your IdP depending on config. |
 | Reverse proxy               | Set `FRONTEND_URL` and `TRUST_PROXY` correctly or auth + websockets may fail.                                                 |
+| Split-horizon IdP networking | Set `OIDC_ISSUER_URL` to the browser-reachable issuer and optionally `OIDC_DISCOVERY_URL` to a backend-reachable internal URL. |
 | OIDC admin mapping          | If `OIDC_ADMIN_GROUPS` is set, admin role is reconciled on each authenticated request for OIDC users: users in those groups are promoted to `ADMIN`, users not in those groups are demoted to `USER`. |
 | Legacy sessions             | Users with old sessions (issued before group claims were embedded) should sign out/in once so OIDC group claims are refreshed. |
 
@@ -324,6 +328,8 @@ Configure ExcaliDash backend for hybrid OIDC:
 ```bash
 cd backend
 cp .env.oidc.example .env
+# If backend runs in Docker and Keycloak issuer is localhost for browser, set:
+# OIDC_DISCOVERY_URL=http://keycloak:8080/realms/excalidash
 # Ensure OIDC_REDIRECT_URI matches where your frontend is running:
 # - http://localhost:6767/api/auth/oidc/callback (repo frontend dev default)
 # - https://excalidash.example.com/api/auth/oidc/callback (production)
@@ -468,6 +474,6 @@ Common flags:
 # Credits
 
 - Example designs from:
-  - https://github.com/Prakash-sa/system-design-ultimatum/tree/main
-  - https://github.com/kitsteam/excalidraw-examples/tree/main
+  - <https://github.com/Prakash-sa/system-design-ultimatum/tree/main>
+  - <https://github.com/kitsteam/excalidraw-examples/tree/main>
 - [The amazing work of Excalidraw & contributors](https://www.npmjs.com/package/@excalidraw/excalidraw)

backend/.env.example

@@ -39,6 +39,9 @@ CSRF_SECRET=change-this-secret-in-production
 # OIDC Configuration (required when AUTH_MODE=hybrid or AUTH_MODE=oidc_enforced)
 # OIDC_PROVIDER_NAME=Authentik
 # OIDC_ISSUER_URL=https://auth.example.com/application/o/excalidash/
+# Optional: internal backend-only discovery URL for split-horizon networking.
+# Example: browser uses OIDC_ISSUER_URL=https://auth.example.com while backend discovers via http://auth:9000
+# OIDC_DISCOVERY_URL=http://auth-internal:9000/application/o/excalidash/
 # OIDC_CLIENT_ID=your-client-id
 # OIDC_CLIENT_SECRET=your-client-secret
 # OIDC_REDIRECT_URI=https://excalidash.example.com/api/auth/oidc/callback

backend/.env.oidc.example

@@ -17,6 +17,8 @@ AUTH_MODE=hybrid
 
 OIDC_PROVIDER_NAME=Keycloak
 OIDC_ISSUER_URL=http://localhost:8080/realms/excalidash
+# Optional when backend runs in a container but Keycloak issuer is localhost for browser.
+# OIDC_DISCOVERY_URL=http://keycloak:8080/realms/excalidash
 OIDC_CLIENT_ID=excalidash
 OIDC_GROUPS_CLAIM=realm_access.roles
 # Example: Keycloak realm role used to grant ADMIN in ExcaliDash