Add static bearer token support for third-party MCP client testing

README.md

@@ -548,6 +548,62 @@ curl -i -H "Authorization: Bearer TOKEN_FROM_UNAUTHORIZED_USER" http://localhost
 
 ---
 
+## Static Bearer Token (For Third-Party Testing)
+
+When you need to give a third party a simple token to test their MCP client integration — without going through the full OAuth flow — you can set a static bearer token via the `AUTHORIZATION_BEARER_TOKEN` environment variable.
+
+When this variable is set, any request that presents it as a `Bearer` token will be immediately granted access (returning `200 OK` with `X-Forwarded-User: static-authorized-user`). Requests with any other token fall through to the normal OAuth/session validation as usual. If the variable is unset or empty, the feature is completely disabled.
+
+This is intended for **short-lived testing only** — not as a permanent auth mechanism.
+
+### .env
+
+Add the token to your `.env` file alongside your other secrets:
+
+```env
+AUTHORIZATION_BEARER_TOKEN=your-secret-token-here
+```
+
+### Docker Compose
+
+```yaml
+mcpauth:
+  image: oideibrett/mcpauth:latest
+  volumes:
+    - ./config/data:/app/data
+  environment:
+    - ENABLE_EDGE_AUTH=true
+    - COOKIE_DOMAIN=.yourdomain.com  # leading dot for subdomains
+    - PORT=11000
+    - PROVIDER=keycloak
+    - CLIENT_ID=${CLIENT_ID}
+    - CLIENT_SECRET=${CLIENT_SECRET}
+    - OAUTH_DOMAIN=${OAUTH_DOMAIN:-oauth.yourdomain.com}
+    - KEYCLOAK_AUTH_HOST=keycloak.yourdomain.com
+    - KEYCLOAK_AUTH_PORT=443
+    - KEYCLOAK_AUTH_PROTOCOL=https
+    - KEYCLOAK_REALM=master
+    - ALLOWED_SCOPES=openid,email,profile
+    - AUTHORIZATION_BEARER_TOKEN=${AUTHORIZATION_BEARER_TOKEN}
+    #- REQUIRED_SCOPES=openid,email
+    - REQUIRED_SCOPES=email
+  restart: unless-stopped
+  ports:
+    - "127.0.0.1:11000:11000"
+```
+
+### Testing with curl
+
+```bash
+# Should return 200 OK
+curl -i -H "Authorization: Bearer your-secret-token-here" http://localhost:11000/auth
+
+# Wrong token — falls through to OAuth validation, returns 401
+curl -i -H "Authorization: Bearer wrongtoken" http://localhost:11000/auth
+```
+
+---
+
 
 ## Middleware Chain (Traefik)
 

server/auth_handler_test.go

@@ -0,0 +1,136 @@
+package server
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/gin-gonic/gin"
+)
+
+// newTestServer builds a minimal Server suitable for authHandler tests — no DB required.
+func newTestServer() *Server {
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	s := &Server{
+		Router:   router,
+		Sessions: NewSessionStore(),
+	}
+	router.Any("/auth", s.authHandler)
+	return s
+}
+
+func TestAuthHandler_StaticToken_Accepted(t *testing.T) {
+	t.Setenv("AUTHORIZATION_BEARER_TOKEN", "supersecret")
+
+	s := newTestServer()
+	req := httptest.NewRequest(http.MethodGet, "/auth", nil)
+	req.Header.Set("Authorization", "Bearer supersecret")
+	w := httptest.NewRecorder()
+
+	s.Router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d", w.Code)
+	}
+	if w.Header().Get("X-Forwarded-User") != "static-authorized-user" {
+		t.Fatalf("expected X-Forwarded-User=static-authorized-user, got %q", w.Header().Get("X-Forwarded-User"))
+	}
+}
+
+func TestAuthHandler_StaticToken_WrongToken_Rejected(t *testing.T) {
+	t.Setenv("AUTHORIZATION_BEARER_TOKEN", "supersecret")
+
+	s := newTestServer()
+	req := httptest.NewRequest(http.MethodGet, "/auth", nil)
+	req.Header.Set("Authorization", "Bearer wrongtoken")
+	w := httptest.NewRecorder()
+
+	s.Router.ServeHTTP(w, req)
+
+	// Wrong token falls through to session lookup which will find nothing → 401
+	if w.Code != http.StatusUnauthorized {
+		t.Fatalf("expected 401, got %d", w.Code)
+	}
+}
+
+func TestAuthHandler_StaticTokenEnvUnset_FallsThrough(t *testing.T) {
+	t.Setenv("AUTHORIZATION_BEARER_TOKEN", "")
+
+	s := newTestServer()
+	req := httptest.NewRequest(http.MethodGet, "/auth", nil)
+	req.Header.Set("Authorization", "Bearer anytoken")
+	w := httptest.NewRecorder()
+
+	s.Router.ServeHTTP(w, req)
+
+	// No static token configured, no session → 401 via normal OAuth path
+	if w.Code != http.StatusUnauthorized {
+		t.Fatalf("expected 401, got %d", w.Code)
+	}
+}
+
+func TestAuthHandler_NoToken_Rejected(t *testing.T) {
+	t.Setenv("AUTHORIZATION_BEARER_TOKEN", "")
+
+	s := newTestServer()
+	req := httptest.NewRequest(http.MethodGet, "/auth", nil)
+	w := httptest.NewRecorder()
+
+	s.Router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusUnauthorized {
+		t.Fatalf("expected 401, got %d", w.Code)
+	}
+}
+
+func TestAuthHandler_SessionToken_Accepted(t *testing.T) {
+	t.Setenv("AUTHORIZATION_BEARER_TOKEN", "")
+
+	s := newTestServer()
+
+	// Seed a valid session token
+	s.Sessions.SaveToken("valid-session-token", SessionData{
+		Email:     "user@example.com",
+		ExpiresAt: time.Now().Add(time.Hour),
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/auth", nil)
+	req.Header.Set("Authorization", "Bearer valid-session-token")
+	w := httptest.NewRecorder()
+
+	s.Router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d", w.Code)
+	}
+	if w.Header().Get("X-Forwarded-User") != "user@example.com" {
+		t.Fatalf("expected X-Forwarded-User=user@example.com, got %q", w.Header().Get("X-Forwarded-User"))
+	}
+}
+
+func TestAuthHandler_StaticToken_DoesNotInterfereWithSession(t *testing.T) {
+	t.Setenv("AUTHORIZATION_BEARER_TOKEN", "supersecret")
+
+	s := newTestServer()
+
+	// A different valid session token should still work via normal OAuth path
+	s.Sessions.SaveToken("valid-session-token", SessionData{
+		Email:     "user@example.com",
+		ExpiresAt: time.Now().Add(time.Hour),
+	})
+
+	req := httptest.NewRequest(http.MethodGet, "/auth", nil)
+	req.Header.Set("Authorization", "Bearer valid-session-token")
+	w := httptest.NewRecorder()
+
+	s.Router.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d", w.Code)
+	}
+	if w.Header().Get("X-Forwarded-User") != "user@example.com" {
+		t.Fatalf("expected X-Forwarded-User=user@example.com, got %q", w.Header().Get("X-Forwarded-User"))
+	}
+}

server/server.go

@@ -5,6 +5,7 @@ import (
 	"encoding/base64"
 	"fmt"
 	"net/http"
+	"os"
 	"net/url"
 	"strconv"
 	"strings"
@@ -2033,6 +2034,14 @@ func (s *Server) authHandler(c *gin.Context) {
 		return
 	}
 
+	// Static bearer token check — bypasses OAuth when AUTHORIZATION_BEARER_TOKEN is set
+	if staticToken := os.Getenv("AUTHORIZATION_BEARER_TOKEN"); staticToken != "" && token == staticToken {
+		log.Info().Msg("[Auth] Static bearer token authentication successful")
+		c.Header("X-Forwarded-User", "static-authorized-user")
+		c.Data(http.StatusOK, "text/plain; charset=utf-8", []byte("You're authenticated as 'static-authorized-user'"))
+		return
+	}
+
 	var sessionData SessionData
 	var ok bool