fix: add to handle htmx header, add comments and update docs

Signed-off-by: Marek Dano <Marek.Dano@ibm.com>

Author: Marek Dano

docs/docs/manage/sso-microsoft-entra-id-tutorial.md

@@ -178,8 +178,12 @@ Front-channel logout enables automatic session clearing when users log out from
    - Production: `https://gateway.yourcompany.com/admin/logout`
    - Development: `http://localhost:8000/admin/logout`
 
-2. When users log out from Microsoft, Entra ID sends a GET request to this URL
-3. ContextForge clears the session cookie and returns HTTP 200
+2. **How it works**: The `/admin/logout` endpoint supports three scenarios:
+   - **OIDC front-channel logout**: When users log out from Microsoft Entra ID, it sends a GET request without browser headers. ContextForge clears the session and returns HTTP 200 (per OpenID Connect Front-Channel Logout 1.0 spec).
+   - **Browser navigation**: If a user navigates directly to `/admin/logout` in their browser (GET with `Accept: text/html` header), they are redirected to the login page.
+   - **User-initiated logout**: POST requests from the Admin UI logout button redirect to the login page after clearing the session.
+
+3. All three scenarios properly clear authentication cookies and SSO session state.
 
 ## Step 5: Configure ContextForge Environment
 

mcpgateway/admin.py

@@ -4114,13 +4114,15 @@ async def _admin_logout(request: Request) -> Response:
     """
     Handle admin logout by clearing authentication cookies.
 
-    Supports both GET and POST methods:
-    - POST: User-initiated logout from the UI (redirects to login page)
-    - GET: OIDC front-channel logout from identity provider (returns 200 OK)
+    Supports three logout scenarios:
+    - POST: User-initiated logout from the UI (redirects to login page or Keycloak logout)
+    - GET with browser headers: Browser navigation to /admin/logout (redirects to login page)
+    - GET without browser headers: OIDC front-channel logout callback from IdP (returns 200 OK)
 
-    For OIDC front-channel logout, Microsoft Entra ID sends GET requests to notify
-    the application that the user has logged out from the IdP. The application
-    should clear the session and return HTTP 200.
+    For OIDC front-channel logout (per OpenID Connect Front-Channel Logout 1.0 spec),
+    identity providers like Microsoft Entra ID send GET requests to notify the application
+    that the user has logged out from the IdP. The application should clear the session
+    and return HTTP 200.
 
     Args:
         request (Request): FastAPI request object.
@@ -4264,16 +4266,22 @@ def _build_keycloak_logout_url(root_path: str) -> Optional[str]:
 
     # For GET requests, distinguish between browser navigation and OIDC front-channel logout
     if request.method == "GET":
-        # Check if request is from a browser (has Accept: text/html header)
+        # Check if request is from a browser (Accept: text/html, HX-Request header, or admin referer)
+        # Detection must match auth_middleware.py and rbac.py patterns to ensure consistent behavior
         # Browser navigation should redirect to login, OIDC callbacks should return 200 OK
         accept_header = request.headers.get("accept", "")
-        is_browser_request = "text/html" in accept_header
+        is_htmx = request.headers.get("hx-request") == "true"
+        referer = request.headers.get("referer", "")
+        is_browser_request = "text/html" in accept_header or is_htmx or "/admin" in referer
 
         if is_browser_request:
             # Browser navigation - redirect to login (cookies cleared below)
             response = RedirectResponse(url=f"{root_path}/admin/login", status_code=303)
         else:
             # OIDC front-channel logout from IdP - return 200 OK per OIDC spec
+            # Reference: OpenID Connect Front-Channel Logout 1.0
+            # https://openid.net/specs/openid-connect-frontchannel-1_0.html
+            # The RP must clear the session and return HTTP 200 to acknowledge logout
             response = Response(content="Logged out", status_code=200)
     else:
         # POST requests (user-initiated) - redirect to login (cookies cleared below)

tests/unit/mcpgateway/test_admin_module.py

@@ -496,6 +496,32 @@ async def test_admin_logout_paths():
     assert response.status_code == 200
     assert response.body == b"Logged out"
 
+    # GET request with HX-Request header (HTMX) should redirect to login
+    get_htmx_request = _make_request(root_path="/root")
+    get_htmx_request.method = "GET"
+    get_htmx_request.headers = {"accept": "application/json", "hx-request": "true"}
+    response = await admin._admin_logout(get_htmx_request)
+    assert isinstance(response, RedirectResponse)
+    assert response.status_code == 303
+    assert response.headers["location"] == "/root/admin/login"
+
+    # GET request with admin referer should redirect to login
+    get_referer_request = _make_request(root_path="/root")
+    get_referer_request.method = "GET"
+    get_referer_request.headers = {"accept": "application/json", "referer": "http://localhost:4444/admin/users"}
+    response = await admin._admin_logout(get_referer_request)
+    assert isinstance(response, RedirectResponse)
+    assert response.status_code == 303
+    assert response.headers["location"] == "/root/admin/login"
+
+    # GET request with */* Accept header (no text/html) should return 200 OK (OIDC)
+    get_wildcard_request = _make_request(root_path="/root")
+    get_wildcard_request.method = "GET"
+    get_wildcard_request.headers = {"accept": "*/*"}
+    response = await admin._admin_logout(get_wildcard_request)
+    assert response.status_code == 200
+    assert response.body == b"Logged out"
+
 
 @pytest.mark.asyncio
 async def test_admin_logout_keycloak_redirect(monkeypatch):