Add API Key authentication support to CRUD API plugin (#1655)

garrytrinder · web-flow · commit d0da2d701315 · 2026-05-13T12:36:01.000+02:00
* Add API Key authentication support to CRUD API plugin

* Refactor API Key authentication configuration to allow null values for header and query parameter names

* Fix URL matching in CrudApiPlugin to exclude query parameters

* Remove API Key authentication support from CrudApiPlugin and update schema accordingly
diff --git a/DevProxy.Plugins/Mocking/CrudApiDefinitionLoader.cs b/DevProxy.Plugins/Mocking/CrudApiDefinitionLoader.cs
@@ -30,6 +30,7 @@ protected override void LoadData(string fileContents)
             _configuration.DataFile = apiDefinitionConfig?.DataFile ?? string.Empty;
             _configuration.Auth = apiDefinitionConfig?.Auth ?? CrudApiAuthType.None;
             _configuration.EntraAuthConfig = apiDefinitionConfig?.EntraAuthConfig;
+            _configuration.ApiKeyAuthConfig = apiDefinitionConfig?.ApiKeyAuthConfig;
 
             var configResponses = apiDefinitionConfig?.Actions;
             if (configResponses is not null)
diff --git a/DevProxy.Plugins/Mocking/CrudApiPlugin.cs b/DevProxy.Plugins/Mocking/CrudApiPlugin.cs
@@ -39,7 +39,8 @@ public enum CrudApiActionType
 public enum CrudApiAuthType
 {
     None,
-    Entra
+    Entra,
+    ApiKey
 }
 
 public sealed class CrudApiEntraAuth
@@ -52,6 +53,13 @@ public sealed class CrudApiEntraAuth
     public bool ValidateSigningKey { get; set; }
 }
 
+public sealed class CrudApiApiKeyAuth
+{
+    public string ApiKey { get; set; } = string.Empty;
+    public string? HeaderName { get; set; }
+    public string? QueryParameterName { get; set; }
+}
+
 public sealed class CrudApiAction
 {
     [System.Text.Json.Serialization.JsonConverter(typeof(JsonStringEnumConverter))]
@@ -67,6 +75,7 @@ public sealed class CrudApiAction
 public sealed class CrudApiConfiguration
 {
     public IEnumerable<CrudApiAction> Actions { get; set; } = [];
+    public CrudApiApiKeyAuth? ApiKeyAuthConfig { get; set; }
     public string ApiFile { get; set; } = "api.json";
     [System.Text.Json.Serialization.JsonConverter(typeof(JsonStringEnumConverter))]
     public CrudApiAuthType Auth { get; set; } = CrudApiAuthType.None;
@@ -115,6 +124,21 @@ public override async Task InitializeAsync(InitArgs e, CancellationToken cancell
             Configuration.Auth = CrudApiAuthType.None;
         }
 
+        if (Configuration.Auth == CrudApiAuthType.ApiKey &&
+            Configuration.ApiKeyAuthConfig is null)
+        {
+            Logger.LogError("API Key auth is enabled but no configuration is provided. API will work anonymously.");
+            Configuration.Auth = CrudApiAuthType.None;
+        }
+
+        if (Configuration.Auth == CrudApiAuthType.ApiKey &&
+            Configuration.ApiKeyAuthConfig is not null &&
+            string.IsNullOrEmpty(Configuration.ApiKeyAuthConfig.ApiKey))
+        {
+            Logger.LogError("API Key auth is enabled but no API key is configured. API will work anonymously.");
+            Configuration.Auth = CrudApiAuthType.None;
+        }
+
         if (!ProxyUtils.MatchesUrlToWatch(UrlsToWatch, Configuration.BaseUrl, true))
         {
             Logger.LogWarning(
@@ -221,6 +245,7 @@ private async Task SetupOpenIdConnectConfigurationAsync()
             return $"(?<{paramName}>[^/&]+)";
         });
 
+        var requestUrlWithoutQuery = request.RequestUri.GetLeftPart(UriPartial.Path);
         var parameters = new Dictionary<string, string>();
         var action = Configuration.Actions.FirstOrDefault(action =>
         {
@@ -231,7 +256,7 @@ private async Task SetupOpenIdConnectConfigurationAsync()
 
             var absoluteActionUrl = (Configuration.BaseUrl + action.Url).Replace("//", "/", 8);
 
-            if (absoluteActionUrl == request.Url)
+            if (absoluteActionUrl == requestUrlWithoutQuery)
             {
                 return true;
             }
@@ -245,7 +270,7 @@ private async Task SetupOpenIdConnectConfigurationAsync()
 
             // convert parameters into named regex groups
             var urlRegex = Regex.Replace(Regex.Escape(absoluteActionUrl).Replace("\\{", "{", StringComparison.OrdinalIgnoreCase), "({[^}]+})", parameterMatchEvaluator);
-            var match = Regex.Match(request.Url, urlRegex);
+            var match = Regex.Match(requestUrlWithoutQuery, urlRegex);
             if (!match.Success)
             {
                 return false;
@@ -290,12 +315,25 @@ private void AddCORSHeaders(Request request, List<HttpHeader> headers)
 
         headers.Add(new HttpHeader("access-control-allow-origin", origin));
 
+        var allowHeaders = new List<string> { "content-type" };
+
         if (Configuration.EntraAuthConfig is not null ||
             Configuration.Actions.Any(a => a.Auth == CrudApiAuthType.Entra))
         {
-            headers.Add(new HttpHeader("access-control-allow-headers", "authorization, content-type"));
+            allowHeaders.Add("authorization");
         }
 
+        if (Configuration.ApiKeyAuthConfig is not null &&
+            !string.IsNullOrEmpty(Configuration.ApiKeyAuthConfig.HeaderName))
+        {
+            if (!allowHeaders.Contains(Configuration.ApiKeyAuthConfig.HeaderName, StringComparer.OrdinalIgnoreCase))
+            {
+                allowHeaders.Add(Configuration.ApiKeyAuthConfig.HeaderName);
+            }
+        }
+
+        headers.Add(new HttpHeader("access-control-allow-headers", string.Join(", ", allowHeaders)));
+
         var methods = string.Join(", ", Configuration.Actions
             .Where(a => a.Method is not null)
             .Select(a => a.Method)
@@ -307,7 +345,6 @@ private void AddCORSHeaders(Request request, List<HttpHeader> headers)
     private bool AuthorizeRequest(ProxyRequestArgs e, CrudApiAction? action = null)
     {
         var authType = action is null ? Configuration.Auth : action.Auth;
-        var authConfig = action is null ? Configuration.EntraAuthConfig : action.EntraAuthConfig;
 
         if (authType == CrudApiAuthType.None)
         {
@@ -318,6 +355,56 @@ private bool AuthorizeRequest(ProxyRequestArgs e, CrudApiAction? action = null)
             return true;
         }
 
+        if (authType == CrudApiAuthType.ApiKey)
+        {
+            return AuthorizeApiKeyRequest(e);
+        }
+
+        return AuthorizeEntraRequest(e, action);
+    }
+
+    private bool AuthorizeApiKeyRequest(ProxyRequestArgs e)
+    {
+        var apiKeyAuthConfig = Configuration.ApiKeyAuthConfig;
+
+        Debug.Assert(apiKeyAuthConfig is not null, "ApiKeyAuthConfig is null when API key auth is required.");
+
+        // Check header
+        if (!string.IsNullOrEmpty(apiKeyAuthConfig.HeaderName))
+        {
+            var headerValue = e.Session.HttpClient.Request.Headers
+                .FirstOrDefault(h => h.Name.Equals(apiKeyAuthConfig.HeaderName, StringComparison.OrdinalIgnoreCase))?.Value;
+
+            if (!string.IsNullOrEmpty(headerValue) && headerValue == apiKeyAuthConfig.ApiKey)
+            {
+                return true;
+            }
+        }
+
+        // Check query parameter
+        if (!string.IsNullOrEmpty(apiKeyAuthConfig.QueryParameterName))
+        {
+            var requestUrl = e.Session.HttpClient.Request.RequestUri;
+            var queryString = requestUrl.Query;
+            if (!string.IsNullOrEmpty(queryString))
+            {
+                var queryParams = System.Web.HttpUtility.ParseQueryString(queryString);
+                var queryValue = queryParams[apiKeyAuthConfig.QueryParameterName];
+                if (!string.IsNullOrEmpty(queryValue) && queryValue == apiKeyAuthConfig.ApiKey)
+                {
+                    return true;
+                }
+            }
+        }
+
+        Logger.LogRequest("401 Unauthorized. The specified API key is not valid.", MessageType.Failed, new LoggingContext(e.Session));
+        return false;
+    }
+
+    private bool AuthorizeEntraRequest(ProxyRequestArgs e, CrudApiAction? action = null)
+    {
+        var authConfig = action is null ? Configuration.EntraAuthConfig : action.EntraAuthConfig;
+
         Debug.Assert(authConfig is not null, "EntraAuthConfig is null when auth is required.");
 
         var token = e.Session.HttpClient.Request.Headers.FirstOrDefault(h => h.Name.Equals("Authorization", StringComparison.OrdinalIgnoreCase))?.Value;
diff --git a/schemas/v3.0.0/crudapiplugin.apifile.schema.json b/schemas/v3.0.0/crudapiplugin.apifile.schema.json
@@ -109,9 +109,31 @@
       "type": "string",
       "enum": [
         "none",
-        "entra"
+        "entra",
+        "apiKey"
       ],
-      "description": "Determines if the API is secured. Allowed values: none, entra. Default is none."
+      "description": "Determines if the API is secured. Allowed values: none, entra, apiKey. Default is none."
+    },
+    "apiKeyAuthConfig": {
+      "type": "object",
+      "description": "Configuration for API Key authentication. Applies to all actions unless overridden at the action level.",
+      "properties": {
+        "apiKey": {
+          "type": "string",
+          "description": "The valid API key that must be present in the request."
+        },
+        "headerName": {
+          "type": "string",
+          "description": "The HTTP header name to read the API key from."
+        },
+        "queryParameterName": {
+          "type": "string",
+          "description": "The name of the query-string parameter to read the API key from."
+        }
+      },
+      "required": [
+        "apiKey"
+      ]
     },
     "entraAuthConfig": {
       "type": "object",
