[pbs-devel] [PATCH proxmox-backup v2 1/3] api: access: add opt-in HttpOnly ticket authentication flow

[Shannon Sterz]

this new flow returns HttpOnly cookies providing an additional layer
of security for clients operating in a browser environment. opt-in
only to not break existing clients.

most of the new protections were implement by a previous series that
adapted proxmox-auth-api and related crates [1]. this just enables
client's of the api to opt-into these protections.

[1]:
https://lore.proxmox.com/pdm-devel/20250304144247.231089-1-s.sterz@proxmox.com/T/#u

Signed-off-by: Shannon Sterz <s.sterz at proxmox.com>
Tested-by: Mira Limbeck <m.limbeck at proxmox.com>
Tested-by: Maximiliano Sandoval <m.sandoval at proxmox.com>
---
changes since v1:

- add a `tracing::debug!()` statement to the opt-in HttpOnly flow,
  thanks @ Maximiliano Sandoval
- consistently use "HttpOnly" instead of switching between "http only",
  "http-only" and "HttpOnly" in comments and user facing documentation,
  thanks @ Mira Limbeck

 src/api2/access/mod.rs | 76 +++++++++++++++++++++++++++++++++++++++---
 1 file changed, 72 insertions(+), 4 deletions(-)

diff --git a/src/api2/access/mod.rs b/src/api2/access/mod.rs
index 832cdc66..b356c842 100644
--- a/src/api2/access/mod.rs
+++ b/src/api2/access/mod.rs
@@ -2,14 +2,23 @@

 use anyhow::{bail, format_err, Error};

-use serde_json::Value;
+use hyper::header::CONTENT_TYPE;
+use hyper::http::request::Parts;
+use hyper::Response;
+use serde_json::{json, Value};
+
 use std::collections::HashMap;
 use std::collections::HashSet;

+use proxmox_auth_api::api::API_METHOD_CREATE_TICKET_HTTP_ONLY;
+use proxmox_auth_api::types::{CreateTicket, CreateTicketResponse};
 use proxmox_router::{
-    http_bail, http_err, list_subdirs_api_method, Permission, Router, RpcEnvironment, SubdirMap,
+    http_bail, http_err, list_subdirs_api_method, ApiHandler, ApiMethod, ApiResponseFuture,
+    Permission, Router, RpcEnvironment, SubdirMap,
+};
+use proxmox_schema::{
+    api, AllOfSchema, ApiType, BooleanSchema, ObjectSchema, ParameterSchema, ReturnType,
 };
-use proxmox_schema::api;
 use proxmox_sortable_macro::sortable;

 use pbs_api_types::{
@@ -268,7 +277,9 @@ const SUBDIRS: SubdirMap = &sorted!([
     ),
     (
         "ticket",
-        &Router::new().post(&proxmox_auth_api::api::API_METHOD_CREATE_TICKET)
+        &Router::new()
+            .post(&API_METHOD_CREATE_TICKET_TOGGLE)
+            .delete(&proxmox_auth_api::api::API_METHOD_LOGOUT)
     ),
     ("openid", &openid::ROUTER),
     ("domains", &domain::ROUTER),
@@ -277,6 +288,63 @@ const SUBDIRS: SubdirMap = &sorted!([
     ("tfa", &tfa::ROUTER),
 ]);

+const API_METHOD_CREATE_TICKET_TOGGLE: ApiMethod = ApiMethod::new_full(
+    &proxmox_router::ApiHandler::AsyncHttpBodyParameters(&handle_ticket_toggle),
+    ParameterSchema::AllOf(&AllOfSchema::new(
+        "Either create a new HttpOnly ticket or a regular ticket.",
+        &[
+            &ObjectSchema::new(
+                "<INNER: Toggle between HttpOnly or legacy ticket endpoints.>",
+                &[(
+                    "http-only",
+                    true,
+                    &BooleanSchema::new("Whether the HttpOnly authentication flow should be used.")
+                        .default(false)
+                        .schema(),
+                )],
+            )
+            .schema(),
+            &CreateTicket::API_SCHEMA,
+        ],
+    )),
+)
+.returns(ReturnType::new(false, &CreateTicketResponse::API_SCHEMA))
+.protected(true)
+.access(None, &Permission::World);
+
+fn handle_ticket_toggle(
+    parts: Parts,
+    mut param: Value,
+    info: &'static ApiMethod,
+    mut rpcenv: Box<dyn RpcEnvironment>,
+) -> ApiResponseFuture {
+    // If the client specifies that they want to use HttpOnly cookies, prefer those.
+    if Some(true) == param["http-only"].take().as_bool() {
+        if let ApiHandler::AsyncHttpBodyParameters(handler) =
+            API_METHOD_CREATE_TICKET_HTTP_ONLY.handler
+        {
+            tracing::debug!("client requests HttpOnly authentication, using new endpoint...");
+            return handler(parts, param, info, rpcenv);
+        }
+    }
+
+    // Otherwise, default back to the previous ticket method.
+    Box::pin(async move {
+        let create_params: CreateTicket = serde_json::from_value(param)?;
+
+        let ticket_response =
+            proxmox_auth_api::api::create_ticket(create_params, rpcenv.as_mut()).await?;
+
+        let response = Response::builder().header(CONTENT_TYPE, "application/json");
+
+        Ok(response.body(
+            json!({"data": ticket_response, "status": 200, "success": true })
+                .to_string()
+                .into(),
+        )?)
+    })
+}
+
 pub const ROUTER: Router = Router::new()
     .get(&list_subdirs_api_method!(SUBDIRS))
     .subdirs(SUBDIRS);
--
2.47.2