ADR-0001 Axis Camera Authentication Negotiation

efiocca · efiocca · commit b80aafcd65e9 · 2026-07-24T13:14:09.000-06:00
diff --git a/AxisIPCamera/AxisIPCamera.csproj b/AxisIPCamera/AxisIPCamera.csproj
@@ -21,8 +21,6 @@
     
     <PackageReference Include="RestSharp" Version="112.1.0" />
     
-    <PackageReference Include="System.Formats.Asn1" Version="8.0.1" />
-    
     <None Update="manifest.json">
       <CopyToOutputDirectory>Always</CopyToOutputDirectory>
     </None>
diff --git a/AxisIPCamera/Client/AxisHttpClient.cs b/AxisIPCamera/Client/AxisHttpClient.cs
@@ -17,12 +17,12 @@
 using Microsoft.Extensions.Logging;
 using Newtonsoft.Json;
 using RestSharp;
-using RestSharp.Authenticators;
 
 using Keyfactor.Logging;
 using Keyfactor.Orchestrators.Extensions;
-using Keyfactor.Extensions.Orchestrator.AxisIPCamera.Model;
 using Keyfactor.Orchestrators.Extensions.Interfaces;
+using Keyfactor.Extensions.Orchestrator.AxisIPCamera.Exceptions;
+using Keyfactor.Extensions.Orchestrator.AxisIPCamera.Model;
 using Keyfactor.Extensions.Orchestrator.AxisIPCamera.Helpers;
 
 /* AxisHttpClient.cs
@@ -67,64 +67,118 @@ public AxisHttpClient(JobConfiguration config, CertificateStore store, IPAMSecre
             try
             {
                 var errorContext = new CertificateErrorContext();
-                
+
                 Logger = LogHandler.GetClassLogger<AxisHttpClient>();
                 Logger.LogTrace("Entered AxisHttpClient constructor.");
                 Logger.LogTrace("Initializing Axis IP Camera HTTP client");
-                
+
                 // ** NOTE: Ignoring the default config.UseSSL custom field --- we will always connect to the device via HTTPS
                 var baseRestClientUrl = $"https://{store.ClientMachine}";
-                
+
                 Logger.LogDebug($"Base HTTP client URL: {baseRestClientUrl}");
 
-                // Initialize custom HTTP handler to validate device identity
-                RestClientOptions options = null;
-                Logger.LogTrace($"Adding custom TLS cert validator to the HTTP client options...");
+                // Retrieve username and password credentials to connect to the device
+                Logger.LogTrace("Adding device credentials to the HTTP client options...");
+                string username = PAMUtilities.ResolvePAMField(resolver, Logger, "API Username", config.ServerUsername);
+                string password = PAMUtilities.ResolvePAMField(resolver, Logger, "API Password", config.ServerPassword);
+
+                // See ADR-0001 Axis Camera Authentication Negotiation
+                // https://keyfactor.atlassian.net/wiki/spaces/IoTStrategy/pages/2968584197/ADR-0001+Axis+Camera+Authentication+Negotiation
+                //
+                // The client intentionally uses HttpClientHandler credentials
+                // rather than RestSharp's HttpBasicAuthenticator to allow
+                // automatic negotiation of Basic vs Digest authentication
+                // based on the authentication challenge presented by the camera.
+                Logger.LogInformation($"Adding custom TLS cert validator to the HTTP client options.");
+                Logger.LogInformation($"Using HttpClientHandler credential negotiation for camera authentication.");
                 var handler = new HttpClientHandler
                 {
                     ServerCertificateCustomValidationCallback =
-                        DeviceCertValidator.GetValidator(store.StorePath, errorContext, Logger)
+                        DeviceCertValidator.GetValidator(
+                            store.StorePath,
+                            errorContext,
+                            Logger),
+
+                    Credentials = new NetworkCredential(username, password),
+
+                    PreAuthenticate =
+                        false // PreAuthenticate is set to false to avoid the default behavior of sending the username and password in the Authorization header
                 };
+                // End ADR-0001 
 
                 // Initialize HTTP client options with the base URL and custom TLS cert validator
-                options = new RestClientOptions(baseRestClientUrl)
+                RestClientOptions options = new RestClientOptions(baseRestClientUrl)
                 {
                     ConfigureMessageHandler = _ => handler
                 };
 
-                // Add Basic Auth username and password credentials
-                Logger.LogTrace("Adding Basic Auth Credentials to the HTTP client options...");
-                string username = PAMUtilities.ResolvePAMField(resolver, Logger, "API Username", config.ServerUsername);
-                string password = PAMUtilities.ResolvePAMField(resolver, Logger, "API Password", config.ServerPassword);
-                
-                options.Authenticator = new HttpBasicAuthenticator(username, password);
-
                 // Add SSL validation
                 Logger.LogTrace("Validating connection to the device...");
 
                 _httpClient = new RestClient(options);
-                var request = new RestRequest("/"); // Initiates the TLS handshake to retrieve the server cert
+                // Initiates the TLS handshake to verify the ability to authenticate to the camera
+                var request = new RestRequest("axis-cgi/param.cgi?action=list&group=Network.HTTP.AuthenticationPolicy");
                 var response = _httpClient.Execute(request);
 
-                // Build the list of errors to log to the console
+                Logger.LogTrace($"Connection to the device response status code: {response.StatusCode}");
+                
+                // Build the list of SSL certificate errors and log to the console
                 StringBuilder errorSb = new StringBuilder();
                 if (errorContext.HasErrors)
                 {
                     foreach (var error in errorContext.Errors)
                     {
                         errorSb.AppendLine(error);
                     }
-                    throw new Exception(errorSb.ToString());
+
+                    throw new DeviceCertValidationException(
+                        $"Device TLS cert validator errors encountered --- {errorSb}");
+                }
+
+                // Begin ADR-0001 Axis Camera Authentication Negotiation
+                // Log the WWW-Authenticate headers if 401 Unauthorized returned
+                // Throw exception if connection cannot be made successfully to the camera
+                if (response.StatusCode == HttpStatusCode.Unauthorized)
+                {
+                    Logger.LogWarning("Camera returned 401 Unauthorized");
+
+                    foreach (var header in response.Headers)
+                    {
+                        Logger.LogDebug($"WWW-Authenticate header: {header.Value}");
+                    }
+
+                    throw new AuthenticationException(
+                        "Authentication to the Axis camera failed due to 401 Unauthorized. Verify the configured credentials.");
                 }
-                
-                Logger.LogTrace($"Connection to the device response status code: {response.StatusCode}");
+
+                if (!response.IsSuccessful)
+                {
+                    throw new Exception(response.ErrorMessage);
+                }
+                // End ADR-0001 
+
                 Logger.LogTrace("Completed Initialization of Axis IP Camera HTTP Client");
                 Logger.LogTrace("Leaving AxisHttpClient constructor.");
             }
-            catch (Exception e)
+            catch (DeviceCertValidationException ex)
+            {
+                Logger.LogError("Device TLS cert validation failed while connecting to the device: " + LogHandler.FlattenException(ex));
+                throw new Exception(ex.Message);
+            }
+            catch (AuthenticationException ex1)
+            {
+                Logger.LogError("Authentication to the device failed: " + LogHandler.FlattenException(ex1));
+                throw new Exception(ex1.Message);
+            }
+            catch (HttpRequestException ex2)
+            {
+                Logger.LogError("Failed to communicate with the device: " + LogHandler.FlattenException(ex2));
+                throw new Exception(ex2.Message);
+            }
+            catch (Exception ex3)
             {
-                Logger.LogError("Error initializing Axis IP Camera HTTP Client: " + LogHandler.FlattenException(e));
-                throw new Exception($"Device identity could not be verified successfully --- {e.Message}");
+                Logger.LogError("Unexpected error while connecting to the device: " + LogHandler.FlattenException(ex3));
+                throw new Exception(ex3.Message);
             }
         }
 
diff --git a/AxisIPCamera/Exceptions/AuthenticationException.cs b/AxisIPCamera/Exceptions/AuthenticationException.cs
@@ -0,0 +1,26 @@
+// Copyright 2026 Keyfactor
+// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions
+// and limitations under the License.
+
+using System;
+
+namespace Keyfactor.Extensions.Orchestrator.AxisIPCamera.Exceptions
+{
+    public class AuthenticationException : Exception
+    {
+        public AuthenticationException(string message)
+            : base(message)
+        {
+        }
+
+        public AuthenticationException(
+            string message,
+            Exception innerException)
+            : base(message, innerException)
+        {
+        }
+    }
+}
diff --git a/AxisIPCamera/Exceptions/DeviceCertValidationException.cs b/AxisIPCamera/Exceptions/DeviceCertValidationException.cs
@@ -0,0 +1,26 @@
+// Copyright 2026 Keyfactor
+// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions
+// and limitations under the License.
+
+using System;
+
+namespace Keyfactor.Extensions.Orchestrator.AxisIPCamera.Exceptions
+{
+    public class DeviceCertValidationException : Exception
+    {
+        public DeviceCertValidationException(string message)
+            : base(message)
+        {
+        }
+
+        public DeviceCertValidationException(
+            string message,
+            Exception innerException)
+            : base(message, innerException)
+        {
+        }
+    }
+}
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,4 +1,6 @@
 v1.1.0
+- fix(logging): Improved exception handling to be more robust for HTTP client initialization
+- fix(auth): Implemented .NET native credential negotiation to support both Basic & Digest auth policies
 - chore(docs): Updated doctool release actions to v5
 - chore(build): Updated .NET target frameworks to net8.0 and net10.0
 - fix(odkg): Fixed incorrect mapping of ECDSA algorithm to ECP. Updated to ECDSA.
diff --git a/docsource/content.md b/docsource/content.md
@@ -72,6 +72,19 @@ recommended to create a new account specifically for executing API calls. This a
 privileges since the orchestrator extension is capable of making configuration changes, such as installing and removing certificates.
 2. Currently supports AXIS M2035-LE Bullet Camera, AXIS OS version 12.2.62. Has not been tested with any other firmware version.
 
+### Authentication
+
+The Axis IP Camera Orchestrator Extension uses .NET HttpClientHandler credential negotiation when connecting to Axis devices over HTTPS.
+This allows the orchestrator to automatically negotiate the authentication mechanism required by the camera.
+The orchestrator has been validated against Axis cameras configured with:
+
+- Basic
+- Digest
+- Basic & Digest
+- Recommended
+
+As a result, customer-side changes to camera authentication policies are generally not required.
+
 ## Post Installation
 
 The AXIS IP Camera Orchestrator Extension *always* connects to an AXIS IP Network Camera via HTTPS, regardless
@@ -110,6 +123,23 @@ These values must match or the session will be denied.
 > Therefore, you will need to install the full CA chain - including root and intermediate certificates - into the orchestrator server's local
 > certificate store.
 
+## Troubleshooting
+
+### 401 Unauthorized Responses
+
+The Axis IP Camera Orchestrator Extension supports authentication negotiation and has been validated against Axis cameras configured for:
+
+- Basic
+- Digest
+- Basic & Digest
+- Recommended
+
+If a 401 Unauthorized response is encountered:
+
+1. Verify the configured credentials.
+2. Verify connectivity to the device.
+3. Review orchestrator logs for authentication-related messages.
+
 ## Operational Notes
 
 ### AXIS OS 12 Firmware Recommendation
