feat(api): add authentication requirements to OpenAPI spec

Author: azasypkin

dev/docker/secutils-e2e.toml

@@ -19,7 +19,7 @@ timeout = 60000
 
 [security]
 secrets_encryption_key = "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"
-operators = ["@kratos", "@secutils", "@retrack"]
+operators = ["@kratos", "@secutils", "@retrack", "demo@secutils.dev"]
 
 [security.preconfigured_users]
 "e2e@secutils.dev" = { handle = "u", tier = "ultimate" }

src/server/handlers.rs

@@ -41,6 +41,28 @@ use crate::{
 use actix_web::web;
 use utoipa::OpenApi;
 
+struct SecurityAddon;
+
+impl utoipa::Modify for SecurityAddon {
+    fn modify(&self, openapi: &mut utoipa::openapi::OpenApi) {
+        if let Some(components) = openapi.components.as_mut() {
+            components.add_security_scheme(
+                "bearerAuth",
+                utoipa::openapi::security::SecurityScheme::Http(
+                    utoipa::openapi::security::HttpBuilder::new()
+                        .scheme(utoipa::openapi::security::HttpAuthScheme::Bearer)
+                        .bearer_format("JWT")
+                        .description(Some(
+                            "JWT token obtained from the authentication service. \
+                             Pass as `Authorization: Bearer <token>`.",
+                        ))
+                        .build(),
+                ),
+            );
+        }
+    }
+}
+
 /// Resolves the effective user for a shared-resource-aware handler.
 ///
 /// If a `UserShare` is present and its resource matches the expected shared resource, the share
@@ -199,6 +221,10 @@ pub(crate) async fn resolve_shared_user(
         api_trackers::api_trackers_test,
         api_trackers::api_trackers_debug,
     ),
+    modifiers(&SecurityAddon),
+    security(
+        ("bearerAuth" = [])
+    ),
     components(schemas(
         // Tags
         crate::users::UserTag,
@@ -562,6 +588,9 @@ mod tests {
                     }
                   }
                 }
+              },
+              "401": {
+                "description": "Missing or invalid authentication credentials."
               }
             }
           },
@@ -594,6 +623,9 @@ mod tests {
               },
               "400": {
                 "description": "Invalid tag parameters."
+              },
+              "401": {
+                "description": "Missing or invalid authentication credentials."
               }
             }
           }
@@ -714,7 +746,10 @@ mod tests {
                   }
                 }
               }
-            }
+            },
+            "security": [
+              {}
+            ]
           },
           "post": {
             "tags": [
@@ -736,6 +771,12 @@ mod tests {
               "204": {
                 "description": "Status was successfully updated."
               },
+              "401": {
+                "description": "Missing or invalid authentication credentials."
+              },
+              "403": {
+                "description": "Caller is not an operator."
+              },
               "500": {
                 "description": "Failed to update status."
               }
@@ -770,6 +811,9 @@ mod tests {
                     }
                   }
                 }
+              },
+              "401": {
+                "description": "Missing or invalid authentication credentials."
               }
             }
           },
@@ -802,6 +846,9 @@ mod tests {
               },
               "400": {
                 "description": "Invalid template parameters."
+              },
+              "401": {
+                "description": "Missing or invalid authentication credentials."
               }
             }
           }
@@ -1093,6 +1140,58 @@ mod tests {
         "###);
     }
 
+    #[test]
+    fn openapi_spec_has_security_schemes() {
+        let spec = spec();
+        assert_json_snapshot!(spec["components"]["securitySchemes"], @r###"
+        {
+          "bearerAuth": {
+            "type": "http",
+            "scheme": "bearer",
+            "bearerFormat": "JWT",
+            "description": "JWT token obtained from the authentication service. Pass as `Authorization: Bearer <token>`."
+          }
+        }
+        "###);
+    }
+
+    #[test]
+    fn openapi_spec_has_global_security() {
+        let spec = spec();
+        assert_json_snapshot!(spec["security"], @r###"
+        [
+          {
+            "bearerAuth": []
+          }
+        ]
+        "###);
+    }
+
+    #[test]
+    fn openapi_spec_anonymous_endpoint_overrides_security() {
+        let spec = spec();
+        let status_get = &spec["paths"]["/api/status"]["get"];
+        assert_json_snapshot!(status_get["security"], @r###"
+        [
+          {}
+        ]
+        "###);
+    }
+
+    #[test]
+    fn openapi_spec_optional_auth_endpoint_has_both_options() {
+        let spec = spec();
+        let template_get = &spec["paths"]["/api/certificates/templates/{template_id}"]["get"];
+        assert_json_snapshot!(template_get["security"], @r###"
+        [
+          {},
+          {
+            "bearerAuth": []
+          }
+        ]
+        "###);
+    }
+
     #[test]
     fn openapi_spec_has_external_docs() {
         let spec = spec();

src/server/handlers/api_trackers.rs

@@ -20,7 +20,8 @@ pub struct TrackerIdPath {
 #[utoipa::path(
     tags = ["web_scraping"],
     responses(
-        (status = 200, description = "List of API trackers.", body = [ApiTracker])
+        (status = 200, description = "List of API trackers.", body = [ApiTracker]),
+        (status = UNAUTHORIZED, description = "Missing or invalid authentication credentials.")
     )
 )]
 #[get("/api/web_scraping/api_trackers")]
@@ -38,7 +39,8 @@ pub async fn api_trackers_list(
     request_body = ApiTrackerCreateParams,
     responses(
         (status = 201, description = "API tracker was successfully created.", body = ApiTracker),
-        (status = BAD_REQUEST, description = "Invalid API tracker parameters.")
+        (status = BAD_REQUEST, description = "Invalid API tracker parameters."),
+        (status = UNAUTHORIZED, description = "Missing or invalid authentication credentials.")
     )
 )]
 #[post("/api/web_scraping/api_trackers")]
@@ -62,7 +64,8 @@ pub async fn api_trackers_create(
     request_body = ApiTrackerUpdateParams,
     responses(
         (status = 204, description = "API tracker was successfully updated."),
-        (status = NOT_FOUND, description = "API tracker not found.")
+        (status = NOT_FOUND, description = "API tracker not found."),
+        (status = UNAUTHORIZED, description = "Missing or invalid authentication credentials.")
     )
 )]
 #[put("/api/web_scraping/api_trackers/{tracker_id}")]
@@ -86,7 +89,8 @@ pub async fn api_trackers_update(
     params(TrackerIdPath),
     responses(
         (status = 204, description = "API tracker was successfully deleted."),
-        (status = NOT_FOUND, description = "API tracker not found.")
+        (status = NOT_FOUND, description = "API tracker not found."),
+        (status = UNAUTHORIZED, description = "Missing or invalid authentication credentials.")
     )
 )]
 #[delete("/api/web_scraping/api_trackers/{tracker_id}")]
@@ -110,7 +114,8 @@ pub async fn api_trackers_delete(
     request_body = ApiTrackerGetHistoryParams,
     responses(
         (status = 200, description = "List of API tracker revisions."),
-        (status = NOT_FOUND, description = "API tracker not found.")
+        (status = NOT_FOUND, description = "API tracker not found."),
+        (status = UNAUTHORIZED, description = "Missing or invalid authentication credentials.")
     )
 )]
 #[post("/api/web_scraping/api_trackers/{tracker_id}/_history")]
@@ -134,7 +139,8 @@ pub async fn api_trackers_get_history(
     params(TrackerIdPath),
     responses(
         (status = 204, description = "History was successfully cleared."),
-        (status = NOT_FOUND, description = "API tracker not found.")
+        (status = NOT_FOUND, description = "API tracker not found."),
+        (status = UNAUTHORIZED, description = "Missing or invalid authentication credentials.")
     )
 )]
 #[post("/api/web_scraping/api_trackers/{tracker_id}/_clear")]
@@ -157,7 +163,8 @@ pub async fn api_trackers_clear_history(
     params(TrackerIdPath),
     responses(
         (status = 200, description = "List of tracker execution logs."),
-        (status = NOT_FOUND, description = "API tracker not found.")
+        (status = NOT_FOUND, description = "API tracker not found."),
+        (status = UNAUTHORIZED, description = "Missing or invalid authentication credentials.")
     )
 )]
 #[get("/api/web_scraping/api_trackers/{tracker_id}/_logs")]
@@ -180,7 +187,8 @@ pub async fn api_trackers_get_logs(
     params(TrackerIdPath),
     responses(
         (status = 204, description = "Logs were successfully cleared."),
-        (status = NOT_FOUND, description = "API tracker not found.")
+        (status = NOT_FOUND, description = "API tracker not found."),
+        (status = UNAUTHORIZED, description = "Missing or invalid authentication credentials.")
     )
 )]
 #[post("/api/web_scraping/api_trackers/{tracker_id}/_clear_logs")]
@@ -201,7 +209,8 @@ pub async fn api_trackers_clear_logs(
 #[utoipa::path(
     tags = ["web_scraping"],
     responses(
-        (status = 200, description = "Logs summary keyed by tracker ID.")
+        (status = 200, description = "Logs summary keyed by tracker ID."),
+        (status = UNAUTHORIZED, description = "Missing or invalid authentication credentials.")
     )
 )]
 #[get("/api/web_scraping/api_trackers/_logs_summary")]
@@ -223,7 +232,8 @@ pub async fn api_trackers_get_logs_summary(
     request_body = ApiTrackerTestParams,
     responses(
         (status = 200, description = "Test request result.", body = ApiTrackerTestResult),
-        (status = BAD_REQUEST, description = "Invalid test parameters.")
+        (status = BAD_REQUEST, description = "Invalid test parameters."),
+        (status = UNAUTHORIZED, description = "Missing or invalid authentication credentials.")
     )
 )]
 #[post("/api/web_scraping/api_trackers/_test")]
@@ -246,7 +256,8 @@ pub async fn api_trackers_test(
     request_body = ApiTrackerDebugParams,
     responses(
         (status = 200, description = "Debug result."),
-        (status = BAD_REQUEST, description = "Invalid debug parameters.")
+        (status = BAD_REQUEST, description = "Invalid debug parameters."),
+        (status = UNAUTHORIZED, description = "Missing or invalid authentication credentials.")
     )
 )]
 #[post("/api/web_scraping/api_trackers/_debug")]

src/server/handlers/certificate_templates.rs

@@ -31,7 +31,8 @@ pub struct CertificateTemplateGetResponse {
 #[utoipa::path(
     tags = ["certificates"],
     responses(
-        (status = 200, description = "List of certificate templates.", body = [CertificateTemplate])
+        (status = 200, description = "List of certificate templates.", body = [CertificateTemplate]),
+        (status = UNAUTHORIZED, description = "Missing or invalid authentication credentials.")
     )
 )]
 #[get("/api/certificates/templates")]
@@ -55,6 +56,7 @@ pub async fn certificate_templates_list(
 #[utoipa::path(
     tags = ["certificates"],
     params(TemplateIdPath),
+    security((), ("bearerAuth" = [])),
     responses(
         (status = 200, description = "Certificate template with share info.", body = CertificateTemplateGetResponse),
         (status = 404, description = "Template not found.")
@@ -105,7 +107,8 @@ pub async fn certificate_templates_get(
     request_body = TemplatesCreateParams,
     responses(
         (status = 201, description = "Template was successfully created.", body = CertificateTemplate),
-        (status = BAD_REQUEST, description = "Invalid template parameters.")
+        (status = BAD_REQUEST, description = "Invalid template parameters."),
+        (status = UNAUTHORIZED, description = "Missing or invalid authentication credentials.")
     )
 )]
 #[post("/api/certificates/templates")]
@@ -129,7 +132,8 @@ pub async fn certificate_templates_create(
     request_body = TemplatesUpdateParams,
     responses(
         (status = 204, description = "Template was successfully updated."),
-        (status = NOT_FOUND, description = "Template not found.")
+        (status = NOT_FOUND, description = "Template not found."),
+        (status = UNAUTHORIZED, description = "Missing or invalid authentication credentials.")
     )
 )]
 #[put("/api/certificates/templates/{template_id}")]
@@ -153,7 +157,8 @@ pub async fn certificate_templates_update(
     params(TemplateIdPath),
     responses(
         (status = 204, description = "Template was successfully deleted."),
-        (status = NOT_FOUND, description = "Template not found.")
+        (status = NOT_FOUND, description = "Template not found."),
+        (status = UNAUTHORIZED, description = "Missing or invalid authentication credentials.")
     )
 )]
 #[delete("/api/certificates/templates/{template_id}")]
@@ -177,6 +182,7 @@ pub async fn certificate_templates_delete(
     tags = ["certificates"],
     params(TemplateIdPath),
     request_body = TemplatesGenerateParams,
+    security((), ("bearerAuth" = [])),
     responses(
         (status = 200, description = "Generated certificate data (binary, base64-encoded in JSON)."),
         (status = NOT_FOUND, description = "Template not found.")
@@ -212,7 +218,8 @@ pub async fn certificate_templates_generate(
     params(TemplateIdPath),
     responses(
         (status = 200, description = "Share info for the template."),
-        (status = NOT_FOUND, description = "Template not found.")
+        (status = NOT_FOUND, description = "Template not found."),
+        (status = UNAUTHORIZED, description = "Missing or invalid authentication credentials.")
     )
 )]
 #[post("/api/certificates/templates/{template_id}/_share")]
@@ -235,7 +242,8 @@ pub async fn certificate_templates_share(
     tags = ["certificates"],
     params(TemplateIdPath),
     responses(
-        (status = 204, description = "Template was successfully unshared.")
+        (status = 204, description = "Template was successfully unshared."),
+        (status = UNAUTHORIZED, description = "Missing or invalid authentication credentials.")
     )
 )]
 #[post("/api/certificates/templates/{template_id}/_unshare")]
@@ -258,7 +266,8 @@ pub async fn certificate_templates_unshare(
     request_body = TemplatesFetchCertificatesParams,
     responses(
         (status = 200, description = "PEM-encoded certificate chain.", body = [String]),
-        (status = BAD_REQUEST, description = "Invalid or unreachable URL.")
+        (status = BAD_REQUEST, description = "Invalid or unreachable URL."),
+        (status = UNAUTHORIZED, description = "Missing or invalid authentication credentials.")
     )
 )]
 #[post("/api/certificates/_fetch")]