add api-key parameter (#3690)

### 🛠 Summary

CVS-174477
Enable client authorization using API key passed in authorization
header.
API key can be set using --api_key_file parameter or using API_KEY env
variable
Key verification is enabled only for generative endpoints /v3

### 🧪 Checklist

- [x] Unit tests added.
- [x] The documentation updated.
- [x] Change follows security best practices.
``

---------

Co-authored-by: Adrian Tobiszewski <adrian.tobiszewski@intel.com>
Co-authored-by: Miłosz Żeglarski <milosz.zeglarski@intel.com>

Author: 3 people

ci/loadWin.groovy

@@ -111,7 +111,7 @@ def install_dependencies() {
 def clean() {
     def output1 = bat(returnStdout: true, script: 'windows_clean_build.bat ' + get_short_bazel_path() + ' ' + env.OVMS_CLEAN_EXPUNGE)
     if(fileExists('dist\\windows\\ovms')){
-        def status_del = bat(returnStatus: true, script: 'rmdir /s /q ovms')
+        def status_del = bat(returnStatus: true, script: 'rmdir /s /q dist\\windows\\ovms')
         if (status_del != 0) {
             error "Error: Deleting existing ovms directory failed ${status_del}. Check pipeline.log for details."
         } else {

docs/parameters.md

@@ -56,6 +56,7 @@ Configuration options for the server are defined only via command-line options a
 | `allowed_headers` | `string` (default: *) | Comma-separated list of allowed headers in CORS requests. |
 | `allowed_methods` | `string` (default: *) | Comma-separated list of allowed methods in CORS requests. |
 | `allowed_origins` | `string` (default: *) | Comma-separated list of allowed origins in CORS requests. |
+| `api_key_file` | `string` | Path to the text file with the API key for generative endpoints `/v3/`. The value of first line is used. If not specified, server is using environment variable API_KEY. If not set, requests will not require authorization.| 
 
 ## Config management mode options
 

docs/security_considerations.md

@@ -5,13 +5,9 @@
 By default, the OpenVINO Model Server containers start with the security context of a local account `ovms` with Linux UID 5000. This ensures the Docker container does not have elevated permissions on the host machine. This is in line with best practices to use minimal permissions when running containerized applications. You can change the security context by adding the `--user` parameter to the Docker run command. This may be needed for loading mounted models with restricted access.
 For additional security hardening, you might also consider preventing write operations on the container root filesystem by adding a `--read-only` flag. This prevents undesired modification of the container files. In case the cloud storage used for the model repository (S3, Google Storage, or Azure storage) is restricting the root filesystem, it should be combined with `--tmpfs /tmp` flag.
 
-```bash
-mkdir -p models/resnet/1
-wget -P models/resnet/1 https://storage.openvinotoolkit.org/repositories/open_model_zoo/2022.1/models_bin/2/resnet50-binary-0001/FP32-INT1/resnet50-binary-0001.bin
-wget -P models/resnet/1 https://storage.openvinotoolkit.org/repositories/open_model_zoo/2022.1/models_bin/2/resnet50-binary-0001/FP32-INT1/resnet50-binary-0001.xml
-
-docker run --rm -d --user $(id -u):$(id -g) --read-only --tmpfs /tmp -v ${PWD}/models/:/models -p 9178:9178 openvino/model_server:latest \
---model_path /models/resnet/ --model_name resnet --port 9178
+```
+docker run --rm -d --user $(id -u):$(id -g) --read-only --tmpfs /tmp -p 9000:9000 openvino/model_server:latest \
+--model_path s3://bucket/model --model_name model --port 9000
 
 ```
 ---
@@ -21,11 +17,16 @@ See also:
 - [Securing OVMS with NGINX](../extras/nginx-mtls-auth/README.md)
 - [Securing models with OVSA](https://docs.openvino.ai/2025/about-openvino/openvino-ecosystem/openvino-project/openvino-security-add-on.html)
 
+---
+Generative endpoints starting with `/v3`, might be restricted with authorization and API key. It can be set during the server initialization with a parameter `api_key_file` or environment variable `API_KEY`. 
+The `api_key_file` should contain a path to the file containing the value of API key. The content of the file first line is used. If parameter api_key_file and variable  API_KEY are not set, the server will not require any authorization. The client should send the API key inside the `Authorization` header as `Bearer <api_key>`.
+
 ---
 
 OpenVINO Model Server has a set of mechanisms preventing denial of service attacks from the client applications. They include the following:
 - setting the number of inference execution streams which can limit the number of parallel inference calls in progress for each model. It can be tuned with `NUM_STREAMS` or `PERFORMANCE_HINT` plugin config.
 - setting the maximum number of gRPC threads which is, by default, configured to the number 8 * number_of_cores. It can be changed with the parameter `--grpc_max_threads`.
+- setting the maximum number of REST workers which is, be default, configured to the number 4 * number_of_cores. It can be changed with the parameter `--rest_workers`.
 - maximum size of REST and GRPC message which is 1GB - bigger messages will be rejected
 - setting max_concurrent_streams which defines how many concurrent threads can be initiated from a single client - the remaining will be queued. The default is equal to the number of CPU cores. It can be changed with the `--grpc_channel_arguments grpc.max_concurrent_streams=8`.
 - setting the gRPC memory quota for the requests buffer - the default is 2GB. It can be changed with `--grpc_memory_quota=2147483648`. Value `0` invalidates the quota.

src/capi_frontend/server_settings.hpp

@@ -178,6 +178,7 @@ struct ServerSettingsImpl {
     std::string allowedOrigins{"*"};
     std::string allowedMethods{"*"};
     std::string allowedHeaders{"*"};
+    std::string apiKey;
 #ifdef MTR_ENABLED
     std::string tracePath;
 #endif

src/cli_parser.cpp

@@ -15,6 +15,7 @@
 //*****************************************************************************
 #include "cli_parser.hpp"
 
+#include <filesystem>
 #include <iostream>
 #include <stdexcept>
 #include <string>
@@ -35,6 +36,7 @@
 namespace ovms {
 
 constexpr const char* CONFIG_MANAGEMENT_HELP_GROUP{"config management"};
+constexpr const char* API_KEY_ENV_VAR{"API_KEY"};
 
 std::string getConfigPath(const std::string& configPath) {
     bool isDir = false;
@@ -160,7 +162,11 @@ void CLIParser::parse(int argc, char** argv) {
             ("allowed_headers",
                 "Comma separated list of headers that are allowed to access the API. Default: *.",
                 cxxopts::value<std::string>()->default_value("*"),
-                "ALLOWED_HEADERS");
+                "ALLOWED_HEADERS")
+            ("api_key_file",
+                "path to the text file containing API key for authentication for generative endpoints. If not set, authentication is disabled.",
+                cxxopts::value<std::string>()->default_value(""),
+                "API_KEY");
 
         options->add_options("multi model")
             ("config_path",
@@ -493,6 +499,31 @@ void CLIParser::prepareServer(ServerSettingsImpl& serverSettings) {
     serverSettings.allowedOrigins = result->operator[]("allowed_origins").as<std::string>();
     serverSettings.allowedMethods = result->operator[]("allowed_methods").as<std::string>();
     serverSettings.allowedHeaders = result->operator[]("allowed_headers").as<std::string>();
+    std::filesystem::path apiKeyFile = result->operator[]("api_key_file").as<std::string>();
+    serverSettings.apiKey = "";
+    if (!apiKeyFile.empty()) {
+        std::ifstream file(apiKeyFile);
+        if (file.is_open()) {
+            std::getline(file, serverSettings.apiKey);
+            // Use first line and trim whitespace characters from both ends
+            size_t endpos = serverSettings.apiKey.find_last_not_of(" \n\r\t");
+            if (endpos != std::string::npos) {
+                serverSettings.apiKey = serverSettings.apiKey.substr(0, endpos + 1);
+            }
+            file.close();
+        } else {
+            std::cerr << "Error reading API key file: Unable to open file " << apiKeyFile << std::endl;
+            exit(OVMS_EX_USAGE);
+        }
+    } else {
+        const char* envApiKey = std::getenv(API_KEY_ENV_VAR);
+        if (envApiKey != nullptr) {
+            serverSettings.apiKey = envApiKey;
+        }
+        if (serverSettings.apiKey.empty()) {
+            std::cout << "Info: API key not provided via --api_key_file or API_KEY environment variable. Authentication will be disabled." << std::endl;
+        }
+    }
 }
 
 void CLIParser::prepareModel(ModelsSettingsImpl& modelsSettings, HFSettingsImpl& hfSettings) {

src/config.cpp

@@ -37,11 +37,7 @@ const uint32_t WIN_MAX_GRPC_WORKERS = 1;
 const uint32_t MAX_PORT_NUMBER = std::numeric_limits<uint16_t>::max();
 
 // For drogon, we need to minimize the number of default workers since this value is set for both: unary and streaming (making it always double)
-#if (USE_DROGON == 0)
-const uint64_t DEFAULT_REST_WORKERS = AVAILABLE_CORES * 4.0;
-#else
 const uint64_t DEFAULT_REST_WORKERS = AVAILABLE_CORES;
-#endif
 const uint32_t DEFAULT_GRPC_MAX_THREADS = AVAILABLE_CORES * 8.0;
 const size_t DEFAULT_GRPC_MEMORY_QUOTA = (size_t)2 * 1024 * 1024 * 1024;  // 2GB
 const uint64_t MAX_REST_WORKERS = 10'000;
@@ -370,5 +366,6 @@ const std::string& Config::allowedOrigins() const { return this->serverSettings.
 const std::string& Config::allowedMethods() const { return this->serverSettings.allowedMethods; }
 const std::string& Config::allowedHeaders() const { return this->serverSettings.allowedHeaders; }
 const std::string Config::cacheDir() const { return this->serverSettings.cacheDir; }
+const std::string& Config::apiKey() const { return this->serverSettings.apiKey; }
 
 }  // namespace ovms

src/config.hpp

@@ -323,6 +323,7 @@ class Config {
     const std::string& allowedOrigins() const;
     const std::string& allowedMethods() const;
     const std::string& allowedHeaders() const;
+    const std::string& apiKey() const;
 
     /**
          * @brief Model cache directory

src/http_rest_api_handler.cpp

@@ -15,6 +15,7 @@
 //*****************************************************************************
 #include "http_rest_api_handler.hpp"
 
+#include <algorithm>
 #include <cctype>
 #include <iomanip>
 #include <memory>
@@ -123,7 +124,8 @@ const std::string HttpRestApiHandler::v3_RegexExp =
 
 const std::string HttpRestApiHandler::metricsRegexExp = R"((.?)\/metrics(\?(.*))?)";
 
-HttpRestApiHandler::HttpRestApiHandler(ovms::Server& ovmsServer, int timeout_in_ms) :
+HttpRestApiHandler::HttpRestApiHandler(ovms::Server& ovmsServer, int timeout_in_ms, const std::string& apiKey) :
+    apiKey(apiKey),
     predictionRegex(predictionRegexExp),
     modelstatusRegex(modelstatusRegexExp),
     configReloadRegex(configReloadRegexExp),
@@ -668,14 +670,36 @@ Status HttpRestApiHandler::processListModelsRequest(std::string& response) {
     return StatusCode::OK;
 }
 
+bool HttpRestApiHandler::isAuthorized(const std::unordered_map<std::string, std::string>& headers, const std::string& apiKey) {
+    std::unordered_map<std::string, std::string> lowercaseHeaders;
+    for (const auto& [key, value] : headers) {
+        std::string lowercaseKey = key;
+        std::transform(lowercaseKey.begin(), lowercaseKey.end(), lowercaseKey.begin(), ::tolower);
+        if (lowercaseKey == "authorization") {
+            if (value == "Bearer " + apiKey) {
+                return true;
+            } else {
+                SPDLOG_DEBUG("Unauthorized request - invalid API key provided.");
+                return false;
+            }
+        }
+    }
+    SPDLOG_DEBUG("Unauthorized request - missing API key");
+    return false;
+}
+
 Status HttpRestApiHandler::processV3(const std::string_view uri, const HttpRequestComponents& request_components, std::string& response, const std::string& request_body, std::shared_ptr<HttpAsyncWriter> serverReaderWriter, std::shared_ptr<MultiPartParser> multiPartParser) {
 #if (MEDIAPIPE_DISABLE == 0)
     OVMS_PROFILE_FUNCTION();
 
     HttpPayload request;
     std::string modelName;
     bool streamFieldVal = false;
-
+    if (!this->apiKey.empty()) {
+        if (!isAuthorized(request_components.headers, this->apiKey)) {
+            return StatusCode::UNAUTHORIZED;
+        }
+    }
     auto status = createV3HttpPayload(uri, request_components, response, request_body, serverReaderWriter, std::move(multiPartParser), request, modelName, streamFieldVal);
     if (!status.ok()) {
         SPDLOG_DEBUG("Failed to create V3 payload: {}", status.string());

src/http_rest_api_handler.hpp

@@ -115,7 +115,7 @@ class HttpRestApiHandler {
      *
      * @param timeout_in_ms
      */
-    HttpRestApiHandler(ovms::Server& ovmsServer, int timeout_in_ms);
+    HttpRestApiHandler(ovms::Server& ovmsServer, int timeout_in_ms, const std::string& apiKey = "");
 
     Status parseRequestComponents(HttpRequestComponents& components,
         const std::string_view http_method,
@@ -241,6 +241,8 @@ class HttpRestApiHandler {
     Status processV3(const std::string_view uri, const HttpRequestComponents& request_components, std::string& response, const std::string& request_body, std::shared_ptr<HttpAsyncWriter> serverReaderWriter, std::shared_ptr<MultiPartParser> multiPartParser);
     Status processListModelsRequest(std::string& response);
     Status processRetrieveModelRequest(const std::string& name, std::string& response);
+    bool isAuthorized(const std::unordered_map<std::string, std::string>& headers, const std::string& apiKey);
+    const std::string apiKey;
 
 private:
     const std::regex predictionRegex;