v1.3

Author: bryan-ente

.env.sample

@@ -2,6 +2,7 @@ API_URL="dns.domain.tld:5380"
 USERNAME="api_user"
 PASSWORD="your-password"
 TOKEN=""
+BEARER_AUTH=true
 INCLUDE_INFO=false
 USE_POST=true
 USE_HTTPS=true

README.md

@@ -26,6 +26,7 @@ Then: `require_once "/path/to/vendor/autoload.php";` & `use Technitium\DNSServer
 - `PASSWORD`: The password for the user account.
 - `INCLUDE_INFO`: Returns basic information that might be relevant for the queried request.
 - `TOKEN`: Your API token, if already existent. (`[Your Username]` > `[Create API Token]`). If left empty, the API will use the username and password for authentication to create an API token for you and will write it to your `.env`.
+- `BEARER_AUTH`: Set to `true` to use Bearer Authentication as required as of v15 as stated in Technitium API Docs. If set to `false`, the client will append the token as a query parameter.
 - `USE_POST`: Specify if you want to access the API via POST (`true`) instead of GET (`false`) in default.
 - `USE_HTTPS`: Enable (`true`) HTTPS for the API connection. If your server does not support HTTPS, the API will simply return `false` to all requests.
 
@@ -127,6 +128,13 @@ DDNS(new API(__DIR__ . "/configurations", ".env-custom"), file_get_contents("/my
 
 ## Changes
 
+### 1.3: Alignment with API changes
+
+- Adjusted API calls to align with changes in the Technitium DNS Server API as of May 2026
+- The client does not yet support all clustering related API changes (aswell as the life-time metrics).
+- Fixed incorrect endpoint URL for `get` endpoint in `Stats.dashboard.php` class
+- Added support for Bearer Authentication as required as of v15 as stated in Technitium API Docs.
+
 ### v1.2.1: Fixed and logs/export support
 
 - Added support for `logs/export` allowing you to export a DNS application log file

composer.json

@@ -2,7 +2,7 @@
     "name": "ente/technitium-dnsserver-php-api",
     "type": "library",
     "license": "GPL-3.0-only",
-    "version": "1.2.1",
+    "version": "1.3",
     "description": "API client to interact with the Technitium DNS Server",
     "authors": [
         {

src/API.dnsserver.ente.php

@@ -13,12 +13,13 @@
 use Technitium\DNSServer\API\zones;
 use Technitium\DNSServer\API\Helper\DDNS;
 use Technitium\DNSServer\API\Helper\Log;
+use Technitium\DNSServer\API\sso;
 use \Dotenv\Dotenv;
 use MirazMac\DotEnv\Writer;
 
 class API {
 
-    private string $protocol;
+    private string $protocol = "http";
     private $admin;
     private $allowed;
     private $apps;
@@ -32,6 +33,7 @@ class API {
     private $zones;
     private $ddns;
     private $log;
+    private $sso;
     private string $conf;
     private string $path;
     private string $fullPath;
@@ -46,11 +48,16 @@ public function __construct(string $confPath, ?string $name = null){
     }
 
     private function setProtocol(): void{
-        if($this->env["USE_HTTPS"] == "true"){
-            $this->protocol = "https";
-        } else {
-            $this->protocol = "http";
+        $apiUrl = (string)($this->env["API_URL"] ?? "");
+        $urlProtocol = parse_url($apiUrl, PHP_URL_SCHEME);
+
+        if($urlProtocol === "http" || $urlProtocol === "https"){
+            $this->protocol = $urlProtocol;
+            $this->env["API_URL"] = preg_replace('#^https?://#i', '', $apiUrl);
+            return;
         }
+
+        $this->protocol = $this->isTruthy($this->env["USE_HTTPS"] ?? false) ? "https" : "http";
     }
 
     /**
@@ -171,41 +178,67 @@ public function downloadFile($endpoint, $bypass, $data, $csv = false): string {
      */
     public function sendCall(array $data, string $endpoint, string $method = "POST", bool $skip = false, bool $bypass = false): array{
         $c = curl_init();
+        $requestedEndpoint = $endpoint;
         $endpoint = $this->prepareEndpoint($endpoint, $bypass);
-        if($this->env["USE_POST"]){
+        if($endpoint === false){
+            return ["status" => "error", "error" => "Endpoint not implemented: " . $requestedEndpoint];
+        }
+        if($this->isTruthy($this->env["USE_POST"] ?? false)){
             $method = "POST";
         }
+        
+        $useBearerAuth = $this->isTruthy($this->env["BEARER_AUTH"] ?? false);
+        
         switch($method){
             case "POST":
-                curl_setopt($c, CURLOPT_URL, $endpoint . $this->appendAuth($method,$skip));
+                if($useBearerAuth){
+                    curl_setopt($c, CURLOPT_URL, $endpoint);
+                    $headers = ["Authorization: Bearer " . @$this->env["TOKEN"]];
+                    curl_setopt($c, CURLOPT_HTTPHEADER, $headers);
+                } else {
+                    curl_setopt($c, CURLOPT_URL, $endpoint . $this->appendAuth($method,$skip));
+                }
                 curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
                 curl_setopt($c, CURLOPT_POST, true);
                 curl_setopt($c, CURLOPT_POSTFIELDS, $data);
                 break;
             case "GET":
                 $data = http_build_query($data);
-                curl_setopt($c, CURLOPT_URL, $endpoint . "?" . $data . $this->appendAuth($method, $skip));
+                if($useBearerAuth){
+                    curl_setopt($c, CURLOPT_URL, $endpoint . "?" . $data);
+                    $headers = ["Authorization: Bearer " . @$this->env["TOKEN"]];
+                    curl_setopt($c, CURLOPT_HTTPHEADER, $headers);
+                } else {
+                    curl_setopt($c, CURLOPT_URL, $endpoint . "?" . $data . $this->appendAuth($method, $skip));
+                }
                 curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
                 break;
             default:
                 $data = http_build_query($data);
-                curl_setopt($c, CURLOPT_URL, $endpoint . "?" . $data . $this->appendAuth($method, $skip));
+                if($useBearerAuth){
+                    curl_setopt($c, CURLOPT_URL, $endpoint . "?" . $data);
+                    $headers = ["Authorization: Bearer " . @$this->env["TOKEN"]];
+                    curl_setopt($c, CURLOPT_HTTPHEADER, $headers);
+                } else {
+                    curl_setopt($c, CURLOPT_URL, $endpoint . "?" . $data . $this->appendAuth($method, $skip));
+                }
                 curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
                 break;
         }
         $result = ["status" => "error", "error" => "Unknown error"];
+        $response = null;
         try {
             $response = curl_exec($c);
             if(!$response){
-                Log::error_rep("Failed to send request: " . curl_error($c));
+                Log::error_rep("Failed to send request to " . curl_getinfo($c, CURLINFO_EFFECTIVE_URL) . ": " . curl_error($c));
                 $result = ["status" => "error", "error" => curl_error($c)];
             }
         } catch (\Throwable $e){
-            Log::error_rep("Failed to send request: " . $e->getMessage());
+            Log::error_rep("Failed to send request to " . curl_getinfo($c, CURLINFO_EFFECTIVE_URL) . ": " . $e->getMessage());
             $result = ["status" => "error", "error" => $e->getMessage()];
         }
         curl_close($c);
-        if($this->checkResponse($response)){
+        if($response !== null && $this->checkResponse($response)){
             Log::error_rep("Successfully accessed endpoint: " . $endpoint);
             $result = json_decode($response, true);
         }
@@ -220,6 +253,7 @@ public function sendCall(array $data, string $endpoint, string $method = "POST",
      */
     private function appendAuth(string $m = "POST", bool $skip = false): string{
         $this->loadConf($this->path, $this->conf);
+        $this->setProtocol();
         $authAppend = null;
         if($skip){
             return "";
@@ -251,7 +285,7 @@ private function appendAuth(string $m = "POST", bool $skip = false): string{
                         break;
                 }
         }
-        return $authAppend;
+        return $authAppend ?? "";
     }
 
     /**
@@ -266,6 +300,11 @@ private function getPermanentToken(): bool{
             "pass" => $this->env["PASSWORD"],
             "tokenName" => "technitium-dnsserver-php-api"
         ], "user/createToken", "POST", true);
+        if(!isset($response["token"])){
+            Log::error_rep("Unable to get permanent token: " . ($response["error"] ?? "missing token in response"));
+            return false;
+        }
+
         $writer = new Writer($this->fullPath);
         try {
             $writer
@@ -290,13 +329,17 @@ private function getPermanentToken(): bool{
      * @param string $response The response returned by `API::sendCall()` function.
      * @return bool Returns `true` if the response is valid, otherwise `false`.
      */
-    private function checkResponse(string $response): bool{
-        if(is_null($response)){
+    private function checkResponse(?string $response): bool{
+        if(empty($response)){
+            return false;
+        }
+
+        $decoded = json_decode($response, true);
+        if(!is_array($decoded) || !isset($decoded["status"])){
             return false;
-        } else {
-            $re = json_decode($response, true)["status"];
-            return $re != null || $re !== "error" || $re !== "invalid-token";
         }
+
+        return $decoded["status"] !== "error" && $decoded["status"] !== "invalid-token" && $decoded["status"] !== "2fa-required";
     }
 
     /**
@@ -306,18 +349,25 @@ private function checkResponse(string $response): bool{
      * @return bool|string Returns the URI as string or `false` if the endpoint is not implemented.
      */
     private function prepareEndpoint(string $endpoint, bool $bypass = false): bool|string{
+        $this->setProtocol();
+        $apiUrl = (string)($this->env["API_URL"] ?? "");
+
         if($bypass){
-            return $this->protocol . "://" . $this->env["API_URL"] . "/api/" . $endpoint;
+            return $this->protocol . "://" . $apiUrl . "/api/" . $endpoint;
         }
         $endpoints = json_decode(file_get_contents(__DIR__ . "/helper/endpoints.json"));
 
         if(in_array($endpoint, $endpoints)){
-            return $this->protocol . "://" . $this->env["API_URL"] . "/api/" . $endpoint;
+            return ($this->protocol ?: "http") . "://" . $apiUrl . "/api/" . $endpoint;
         } else {
             return false;
         }
     }
 
+    private function isTruthy(mixed $value): bool{
+        return filter_var($value, FILTER_VALIDATE_BOOLEAN);
+    }
+
 
     public function admin(): admin {
         if(!$this->admin) $this->admin = new admin($this);
@@ -382,7 +432,12 @@ public function ddns(): DDNS {
     }
 
     public function log(): Log {
-        if(!$this->log) $this->log = new Log(null);
+        if(!$this->log) $this->log = new Log("Initialization of API log helper");
         return $this->log;
     }
-}
+
+    public function sso(): sso {
+        if(!$this->sso) $this->sso = new sso($this);
+        return $this->sso;
+    }
+}

src/endpoints/dashboard/Stats.dashboard.php

@@ -14,11 +14,12 @@ public function __construct(\Technitium\DNSServer\API\API $api){
      * @param string $utc True to return main chart with data labels in UTC date time format
      * @param string $start start date for `custom` type. ISO 8601 format.
      * @param string $end end date for `custom` type. ISO 8601 format.
+     * @param bool $dontTrimQueryTypeData (optional): Set to `true` to get full data for query type chart instead of top 10 entries. Default value is `false` when unspecified.
      * @return array|bool Returns an result array or `false` otherwise.
      */
-    public function get(string $type = "LastHour", bool $utc = true, string $start = "", string $end = ""): array|bool {
+    public function get(string $type = "LastHour", bool $utc = true, string $start = "", string $end = "", bool $dontTrimQueryTypeData = false): array|bool {
         if($utc){$utc="true";}else{$utc="false";};
-        $response = $this->API->sendCall(["type" => $type, "utc" => $utc, "start" => $start, "end" => $end], "cache/list");
+        $response = $this->API->sendCall(["type" => $type, "utc" => $utc, "start" => $start, "end" => $end, "dontTrimQueryTypeData" => $dontTrimQueryTypeData], "stats/get");
         if($response["status"] == "ok"){
             return $response["response"];
         } else {

src/endpoints/sso/SSO.php

@@ -0,0 +1,95 @@
+<?php
+namespace Technitium\DNSServer\API;
+
+class sso extends API {
+    public $API;
+
+    public function __construct(\Technitium\DNSServer\API\API $api){
+        $this->API = $api;
+    }
+
+    /**
+     * `status()` - Returns the SSO status of the server.
+     * @return array|bool Returns the SSO status or `false` if the request failed.
+     */
+    public function status(): array|bool {
+        $response = $this->API->sendCall([], "sso/status");
+        if($response["status"] == "ok"){
+            return $response["response"];
+        } else {
+            return false;
+        }
+    }
+
+    /**
+     * `getConfiguration()` - Returns the SSO configuration of the server.
+     * @param bool $includeGroups Whether to include group information in the response.
+     * @return array|bool Returns the SSO configuration or `false` if the request failed.
+     */
+    public function getConfiguration(bool $includeGroups = false): array|bool {
+        $response = $this->API->sendCall(["includeGroups" => $includeGroups ? "true" : "false"], "sso/get");
+        if($response["status"] == "ok"){
+            return $response["response"];
+        } else {
+            return false;
+        }
+    }
+
+    /**
+     * `setConfiguration()` - Sets the SSO configuration of the server.
+     * @param array $data The configuration data to set. Seee the API documentation for the list of configuration options.
+     * @return array|bool Returns the updated SSO configuration or `false` if the request failed.
+     */
+    public function setConfiguration(array $data): array|bool {
+        $response = $this->API->sendCall($data, "sso/set");
+        if($response["status"] == "ok"){
+            return $response["response"];
+        } else {
+            return false;
+        }
+    }
+
+    /**
+     * `createUser()` - Creates a new SSO user.
+     * @param string $username The username of the new user.
+     * @param string $displayName The display name of the new user.
+     * @param string $ssoIdentifier The SSO identifier for the new user. This should match the identifier provided in the SSO token by the Identity Provider.
+     * @param array|null $groups An array of group names to assign to the user. This is optional and can be set later.
+     * @return bool Returns `true` if the user was created successfully, `false` otherwise.
+     */
+    public function createUser(string $username, string $displayName, string $ssoIdentifier, ?array $groups): bool {
+        $data = [
+            "username" => $username,
+            "displayName" => $displayName,
+            "ssoIdentifier" => $ssoIdentifier
+        ];
+        if ($groups) {
+            $data["groups"] = implode(",", $groups);
+        }
+        $response = $this->API->sendCall($data, "sso/users/create");
+        return $response["status"] == "ok";
+    }
+
+    /**
+     * `updateUser()` - Updates an existing SSO user.
+     * @param string $username The username of the user to update.
+     * @param string|null $newUsername The new username for the user. This is optional.
+     * @param string|null $displayName The new display name for the user. This is optional.
+     * @param array|null $groups An array of group names to assign to the user. This is optional.
+     * @return bool Returns `true` if the user was updated successfully, `false` otherwise.
+     */
+    public function updateUser(string $username, ?string $newUsername, ?string $displayName, ?array $groups): bool {
+        $data = ["username" => $username];
+        if ($newUsername) {
+            $data["newUsername"] = $newUsername;
+        }
+        if ($displayName) {
+            $data["displayName"] = $displayName;
+        }
+        if ($groups) {
+            $data["groups"] = implode(",", $groups);
+        }
+        $response = $this->API->sendCall($data, "sso/users/set");
+        return $response["status"] == "ok";
+    }
+}