Skip to content

A free open source IT asset/license management system

Added help text for Iru/Kanji and renamed the adapter

snipe92961272affe
diff --git a/app/Exceptions/SyncAdapterVendorException.php b/app/Exceptions/SyncAdapterVendorException.php
new file mode 100644
index 0000000000..e879146892
--- /dev/null
+++ b/app/Exceptions/SyncAdapterVendorException.php
@@ -0,0 +1,18 @@
+<?php
+
+namespace App\Exceptions;
+
+use RuntimeException;
+
+/**
+ * Raised when a sync-adapter vendor call returned a response the
+ * adapter can't consume even though the transport layer didn't
+ * signal an error. Typical trigger: base URL points at the vendor's
+ * web console instead of their API, so the response is a 200 OK
+ * carrying an HTML SPA shell instead of the expected JSON.
+ *
+ * SettingsController::sanitizeSyncErrorSummary handles this class
+ * specially so the flash shows the exception's message instead of
+ * the class-basename fallback.
+ */
+class SyncAdapterVendorException extends RuntimeException {}
diff --git a/app/Http/Controllers/SettingsController.php b/app/Http/Controllers/SettingsController.php
index f02d01ab84..e93f9a8de7 100644
--- a/app/Http/Controllers/SettingsController.php
+++ b/app/Http/Controllers/SettingsController.php
@@ -1311,7 +1311,7 @@ class SettingsController extends Controller
return trans('admin/settings/sync_adapters.sync_failed_network');
}
- // Vendor-shaped adapter errors (wrong base URL, unexpected
+ // Vendor adapter errors (wrong base URL, unexpected
// content type, etc.) carry their own actionable message. Pass
// it through so the admin sees "check your Base URL" instead
// of "SyncAdapterVendorException".
diff --git a/app/Providers/AppServiceProvider.php b/app/Providers/AppServiceProvider.php
index dfda63d247..dd336b3d05 100644
--- a/app/Providers/AppServiceProvider.php
+++ b/app/Providers/AppServiceProvider.php
@@ -2,6 +2,7 @@
namespace App\Providers;
+use App\Exceptions\SyncAdapterVendorException;
use App\Models\Accessory;
use App\Models\Asset;
use App\Models\AssetModel;
@@ -25,6 +26,7 @@ use App\Observers\SettingObserver;
use App\Observers\UserObserver;
use App\View\Composers\ImpersonationBannerComposer;
use App\View\Composers\SidebarComposer;
+use Illuminate\Http\Client\Response as HttpClientResponse;
use Illuminate\Pagination\Paginator;
use Illuminate\Routing\UrlGenerator;
use Illuminate\Support\Facades\Log;
@@ -91,6 +93,27 @@ class AppServiceProvider extends ServiceProvider
Maintenance::observe(MaintenanceObserver::class);
Setting::observe(SettingObserver::class);
User::observe(UserObserver::class);
+
+ // Defense against sync-adapter base URLs pointing at the vendor's
+ // web console instead of their API. A wrong URL commonly returns
+ // 200 OK with an SPA shell (text/html), which slips past
+ // ->throw() and decodes to an empty array in adapter clients,
+ // producing a silent "Sync complete. 0 hosts, 0 errors" flash
+ // instead of a visible failure. Adapter clients chain this
+ // after ->throw() before ->json() so a wrong-URL response
+ // surfaces as a real error the admin can act on.
+ HttpClientResponse::macro('throwIfNotJson', function () {
+ /** @var HttpClientResponse $this */
+ $contentType = $this->header('Content-Type');
+ if (! str_contains(strtolower($contentType), 'json')) {
+ $received = $contentType !== '' ? '"'.$contentType.'"' : 'a response with no Content-Type header';
+ throw new SyncAdapterVendorException(
+ "Expected a JSON response, got {$received}. Verify the adapter Base URL points at the vendor API, not their web console or dashboard."
+ );
+ }
+
+ return $this;
+ });
}
/**
diff --git a/app/SyncAdapters/Kandji/KandjiAdapter.php b/app/SyncAdapters/Kandji/KandjiAdapter.php
index 4c688d3007..11bb24c84f 100644
--- a/app/SyncAdapters/Kandji/KandjiAdapter.php
+++ b/app/SyncAdapters/Kandji/KandjiAdapter.php
@@ -20,7 +20,7 @@ class KandjiAdapter extends SyncAdapter implements PushableAdapter
{
public static function typeLabel(): string
{
- return 'Kandji';
+ return 'Iru (Kandji)';
}
public static function typeSlug(): string
@@ -38,6 +38,11 @@ class KandjiAdapter extends SyncAdapter implements PushableAdapter
return 'https://your-subdomain.api.kandji.io';
}
+ public function baseUrlHelp(): ?string
+ {
+ return trans('admin/settings/sync_adapters.kandji_base_url_help');
+ }
+
public function settingsSchema(): array
{
return [
diff --git a/app/SyncAdapters/Kandji/KandjiClient.php b/app/SyncAdapters/Kandji/KandjiClient.php
index d52c21a954..51d172ae17 100644
--- a/app/SyncAdapters/Kandji/KandjiClient.php
+++ b/app/SyncAdapters/Kandji/KandjiClient.php
@@ -38,6 +38,7 @@ class KandjiClient
'offset' => $offset,
])
->throw()
+ ->throwIfNotJson()
->json();
// Kandji returns a bare array of device objects on this
@@ -74,6 +75,7 @@ class KandjiClient
$response = $this->request()
->get('/api/v1/blueprints', ['limit' => $limit, 'offset' => $offset])
->throw()
+ ->throwIfNotJson()
->json();
$batch = $response['results'] ?? (is_array($response) ? $response : []);
diff --git a/app/SyncAdapters/SyncAdapter.php b/app/SyncAdapters/SyncAdapter.php
index b42102ebd7..99fe65e2fb 100644
--- a/app/SyncAdapters/SyncAdapter.php
+++ b/app/SyncAdapters/SyncAdapter.php
@@ -1351,6 +1351,18 @@ abstract class SyncAdapter
return null;
}
+ /**
+ * Adapter-specific help copy rendered under the base-URL input.
+ * Overridden by adapters whose vendor requires the admin to look
+ * up the API URL in a non-obvious place (e.g. Kandji hides the
+ * API URL behind the Access page's API Token section). Returning
+ * null falls back to the generic base_url_help lang key.
+ */
+ public function baseUrlHelp(): ?string
+ {
+ return null;
+ }
+
/**
* Live-fetch the current list of groups from the vendor.
* Returns an array of ['id' => '...', 'label' => '...']. Called
diff --git a/resources/lang/en-US/admin/settings/sync_adapters.php b/resources/lang/en-US/admin/settings/sync_adapters.php
index 9ac82438c5..135f08ab7a 100644
--- a/resources/lang/en-US/admin/settings/sync_adapters.php
+++ b/resources/lang/en-US/admin/settings/sync_adapters.php
@@ -148,7 +148,8 @@ return [
// Per-adapter credential help
'fleet_token_help' => 'Generate under My Account -> Get API token in your Fleet instance. Needs an admin or observer role with read access to hosts (and to teams if you use group-to-company mapping).',
- 'kandji_token_help' => 'Generate under Settings -> Access -> API Token in your Kandji tenant. Needs the Device list read permission (and Blueprint list if you use group-to-company mapping).',
+ 'kandji_token_help' => 'Generate under Settings -> Access -> API Token in your Iru (Kandji) tenant. Needs the Device list read permission (and Blueprint list if you use group-to-company mapping).',
+ 'kandji_base_url_help' => 'Your Iru (Kandji) API URL is listed on the Access page of your Iru (Kandji) admin console under the API Token section. It is not the same as the URL you use to sign into the admin console. Save the URL that ends with <code>.api.kandji.io</code>, not the dashboard URL.',
'jamf_token_help' => 'Generate a Personal Access Token under Settings -> System -> API Roles and Clients in Jamf Pro. The role needs Read on Computers (and Sites if you use group-to-company mapping).',
'jamf_school_network_id_help' => 'Find your Network ID under Organization -> Settings -> API in the Jamf School admin console.',
'jamf_school_api_key_help' => 'Generate under Organization -> Settings -> API in Jamf School. Needs read access to Devices (and Locations if you use group-to-company mapping).',
@@ -343,7 +344,7 @@ return [
'vendor_group_fleet_team' => 'Fleet Team',
'vendor_group_jamf_site' => 'Jamf Site',
'vendor_group_jamf_school_location' => 'Jamf School Location',
- 'vendor_group_kandji_blueprint' => 'Kandji Blueprint',
+ 'vendor_group_kandji_blueprint' => 'Iru (Kandji) Blueprint',
'vendor_group_jamf_platform_blueprint' => 'Jamf Platform Blueprint',
'vendor_group_mosyle_location' => 'Mosyle Location',
'vendor_group_kaseya_organization' => 'Kaseya Organization',
diff --git a/resources/views/blade/sync-adapter/form.blade.php b/resources/views/blade/sync-adapter/form.blade.php
index a7518d1c2e..c1f51be6be 100644
--- a/resources/views/blade/sync-adapter/form.blade.php
+++ b/resources/views/blade/sync-adapter/form.blade.php
@@ -111,7 +111,7 @@
:label="trans('admin/settings/sync_adapters.base_url')"
:name="$urlField"
input_div_class="col-md-8"
- :help_text="trans('admin/settings/sync_adapters.base_url_help', ['type' => $adapter::typeLabel()])"
+ :help_text="$adapter->baseUrlHelp() ?? trans('admin/settings/sync_adapters.base_url_help', ['type' => $adapter::typeLabel()])"
required
>
<x-slot:input>
diff --git a/tests/Feature/SyncAdapters/Kandji/KandjiAdapterTest.php b/tests/Feature/SyncAdapters/Kandji/KandjiAdapterTest.php
index 9b15907eb1..13340b9382 100644
--- a/tests/Feature/SyncAdapters/Kandji/KandjiAdapterTest.php
+++ b/tests/Feature/SyncAdapters/Kandji/KandjiAdapterTest.php
@@ -84,6 +84,31 @@ class KandjiAdapterTest extends TestCase
$this->assertNotNull($record->lastSeen);
}
+ public function test_pull_raises_when_base_url_returns_html_instead_of_json()
+ {
+ // Regression: when the admin pastes the Iru (Kandji) web
+ // console URL as the Base URL instead of the API host, Kandji
+ // returns 200 OK with an SPA shell (text/html). ->throw() sees
+ // 200 and doesn't fire, ->json() decodes to null, and the
+ // sync used to complete silently with "0 hosts synced". The
+ // throwIfNotJson macro registered in AppServiceProvider now
+ // surfaces this as a real error so the admin gets an
+ // actionable flash instead of a zero-hosts warning.
+ $adapter = $this->configuredKandjiAdapter();
+
+ Http::fake([
+ '*/api/v1/devices*' => Http::response(
+ '<!DOCTYPE html><html><body><div id="app"></div></body></html>',
+ 200,
+ ['Content-Type' => 'text/html'],
+ ),
+ ]);
+
+ $this->expectException(\App\Exceptions\SyncAdapterVendorException::class);
+ $this->expectExceptionMessage('Verify the adapter Base URL points at the vendor API');
+ iterator_to_array($adapter->pull());
+ }
+
private function configuredKandjiAdapter(): KandjiAdapter
{
$instance = SyncAdapterInstance::where('slug', 'kandji')->firstOrFail();