Skip to content

A free open source IT asset/license management system

12.0 KB
Raw Blame
<?php

namespace App\SyncAdapters\WorkspaceOne;

use App\Models\Asset;
use App\SyncAdapters\HostInventoryRecord;
use App\SyncAdapters\PushableSyncAdapter;
use Carbon\Carbon;
use Illuminate\Support\Arr;
use Illuminate\Support\Facades\Log;

/**
 * Omnissa Workspace ONE adapter (formerly VMware Workspace ONE UEM,
 * originally AirWatch). Pulls managed devices from the REST device
 * search endpoint via OAuth 2.0 client credentials. Also pushes
 * Snipe-IT asset_tag back via WS1's AssetNumber field on the
 * device-update endpoint.
 *
 * Modern Workspace ONE tenants use OAuth 2.0 client credentials
 * against a per-region auth endpoint (na.uemauth.workspaceone.com,
 * emea.uemauth.workspaceone.com, apac.uemauth.workspaceone.com, etc.).
 * The vendor renamed from VMware to Omnissa in 2024 and the auth
 * hosts moved from *.vmwservices.com to *.workspaceone.com. Full
 * regional list: https://kb.omnissa.com/s/article/6000867.
 * The access token is carried as `Authorization: Bearer` on Dashboard
 * API calls plus an `aw-tenant-code` header identifying which tenant
 * to scope the call to. tenant_code and client_id are non-secret.
 * Only client_secret encrypts at rest.
 *
 * The Base URL field on the settings page controls the Dashboard API
 * host (e.g. asXXX.awmdm.com). The region-appropriate auth endpoint
 * is derived from the same host convention below.
 *
 * Legacy tenants on Basic-auth + admin credentials aren't covered by
 * this schema. If someone needs it, a WorkspaceOneBasicAuthAdapter
 * sibling with a different schema is the right shape rather than
 * making this schema conditional on auth mode.
 */
class WorkspaceOneAdapter extends PushableSyncAdapter
{
    public static function typeLabel(): string
    {
        return 'Omnissa Workspace ONE';
    }

    public static function typeSlug(): string
    {
        return 'workspace_one';
    }

    public static function docsUrl(): ?string
    {
        return 'https://developer.omnissa.com/workspace-one-uem-apis/';
    }

    public function baseUrlPlaceholder(): ?string
    {
        return 'https://as###.awmdm.com';
    }

    public function settingsSchema(): array
    {
        return [
            [
                'key' => 'tenant_code',
                'label' => trans('admin/settings/sync_adapters.label_tenant_code'),
                'help' => trans('admin/settings/sync_adapters.workspace_one_tenant_code_help'),
            ],
            [
                'key' => 'client_id',
                'label' => trans('admin/settings/sync_adapters.label_client_id'),
                'help' => trans('admin/settings/sync_adapters.workspace_one_client_id_help'),
            ],
            [
                'key' => 'client_secret',
                'label' => trans('admin/settings/sync_adapters.label_client_secret'),
                'secret' => true,
                'help' => trans('admin/settings/sync_adapters.workspace_one_client_secret_help'),
            ],
        ];
    }

    public function pull(): iterable
    {
        $apiBaseUrl = $this->url();

        $client = new WorkspaceOneClient(
            apiBaseUrl: $apiBaseUrl,
            authBaseUrl: $this->deriveAuthBaseUrl($apiBaseUrl),
            tenantCode: $this->credential('tenant_code'),
            clientId: $this->credential('client_id'),
            clientSecret: $this->credential('client_secret'),
        );

        foreach ($client->devices() as $device) {
            yield $this->normalize($device);
        }
    }

    /**
     * Derive the region-scoped OAuth token host from the API host.
     * Workspace ONE uses a per-region auth endpoint. asXXX.awmdm.com
     * → na.uemauth.workspaceone.com etc. The mapping is inferred from
     * the first three chars of the API host (as-, ds-, uat-).
     * Falls back to the NA endpoint when the base URL doesn't parse.
     *
     * Hosts migrated from *.vmwservices.com to *.workspaceone.com
     * following the Omnissa rebrand. Older vmwservices.com URLs no
     * longer resolve. If Omnissa adds a region beyond APAC / EMEA /
     * NA / UAT, add it here and reference the published list at
     * https://kb.omnissa.com/s/article/6000867.
     */
    private function deriveAuthBaseUrl(string $apiBaseUrl): string
    {
        $host = parse_url($apiBaseUrl, PHP_URL_HOST);
        if (! is_string($host)) {
            return 'https://na.uemauth.workspaceone.com';
        }

        $prefix = strtolower(substr($host, 0, 3));

        return match ($prefix) {
            'apa' => 'https://apac.uemauth.workspaceone.com',
            'eme' => 'https://emea.uemauth.workspaceone.com',
            'uat' => 'https://uat.uemauth.workspaceone.com',
            default => 'https://na.uemauth.workspaceone.com',
        };
    }

    /**
     * Convert a Workspace ONE device payload into the normalized record
     * shape. Uuid is the stable identifier across renames + re-enrollments
     * so we key asset_external_sources on it. UserEmailAddress is the
     * OS-level assignment. UserName is the enrollment account and can
     * differ.
     *
     * @param  array<string, mixed>  $device
     */
    private function normalize(array $device): HostInventoryRecord
    {
        return new HostInventoryRecord(
            sourceKey: $this->name(),
            sourceId: (string) (Arr::get($device, 'Uuid') ?? Arr::get($device, 'Id.Value')),
            hostname: Arr::get($device, 'DeviceFriendlyName')
                ?? Arr::get($device, 'HostName'),
            hardwareSerial: Arr::get($device, 'SerialNumber'),
            hardwareModel: Arr::get($device, 'Model'),
            manufacturer: Arr::get($device, 'DeviceManufacturer'),
            primaryMac: Arr::get($device, 'MacAddress'),
            primaryIp: Arr::get($device, 'DeviceNetworkInfo.0.IPAddress')
                ?? Arr::get($device, 'IpAddress'),
            os: Arr::get($device, 'Platform') ?? Arr::get($device, 'OperatingSystem'),
            osVersion: Arr::get($device, 'OperatingSystem'),
            lastSeen: $this->parseTimestamp(Arr::get($device, 'LastSeen')),
            assignedUserEmail: Arr::get($device, 'UserEmailAddress'),
            assignedUserName: Arr::get($device, 'UserName'),
            extra: [
                'workspace_one_enrollment_status' => Arr::get($device, 'EnrollmentStatus'),
                'workspace_one_compliance_status' => Arr::get($device, 'ComplianceStatus'),
                'workspace_one_ownership' => Arr::get($device, 'Ownership'),
                'workspace_one_organization_group' => Arr::get($device, 'LocationGroupName'),
            ],
        );
    }

    private function parseTimestamp(mixed $value): ?Carbon
    {
        if ($value === null || $value === '') {
            return null;
        }

        return Carbon::parse($value);
    }

    /**
     * WS1 writes need the OAuth application's role to include
     * device-write scope. Same credential used for pull works when
     * scoped correctly. No tier gate.
     */
    public function canPush(): bool
    {
        return true;
    }

    /**
     * Workspace ONE's device record has no first-class freeform
     * notes field admins can rely on. Custom Attributes exist but
     * need per-tenant admin setup, same shape as NinjaOne's custom
     * fields. Return null for now. A future extension could accept
     * a Custom Attribute name in the credential schema.
     */
    public function notesFieldTarget(): ?string
    {
        return null;
    }

    /**
     * Push Snipe-IT asset_tag to WS1's AssetNumber field via the
     * device-update endpoint. Keys the device by UUID (WS1's stable
     * identifier across enrollment renames), which we cached as
     * external_id during pull.
     *
     * @param  array<int, string>  $changedFields
     */
    public function push(Asset $asset, array $changedFields = []): bool
    {
        $externalSource = $this->pushPrologue($asset, $changedFields);
        if ($externalSource === null) {
            return false;
        }

        $payload = $this->buildDevicePayload($asset);
        $composedNotes = $this->composeNotesForPush($asset);

        if ($payload === [] && $composedNotes === null) {
            return false;
        }

        $client = $this->isPushDryRun() ? null : $this->buildClient();
        $this->pushDeviceFields($externalSource->external_id, $payload, $client);
        $this->pushCustomAttribute($externalSource->external_id, $composedNotes, $client);

        return true;
    }

    /**
     * Assemble the device-update payload from pushDirectedFields.
     * Fields the vendor doesn't accept map to null and get skipped.
     *
     * @return array<string, mixed>
     */
    private function buildDevicePayload(Asset $asset): array
    {
        $payload = [];
        foreach ($this->pushDirectedFields() as $field) {
            $mapped = self::sourceFieldToWs1Field($field);
            if ($mapped === null) {
                continue;
            }
            $value = $this->assetValueForSourceField($asset, $field);
            if ($value === null) {
                continue;
            }
            $payload[$mapped] = $value;
        }

        return $payload;
    }

    /**
     * Push top-level device fields (AssetNumber, etc.) via PUT
     * /devices/{uuid}. Null $client means dry-run: log the payload
     * and skip the HTTP call.
     *
     * @param  array<string, mixed>  $payload
     */
    private function pushDeviceFields(string $uuid, array $payload, ?WorkspaceOneClient $client): void
    {
        if ($payload === []) {
            return;
        }

        if ($client === null) {
            Log::channel('sync-adapters')->info(sprintf(
                '%s push [dry-run]: would PUT Workspace ONE device %s with %s',
                $this->name(),
                $uuid,
                json_encode($payload, JSON_UNESCAPED_SLASHES),
            ));

            return;
        }

        $client->updateDevice($uuid, $payload);
        Log::channel('sync-adapters')->info(sprintf(
            '%s push: updated Workspace ONE device %s with fields [%s]',
            $this->name(),
            $uuid,
            implode(', ', array_keys($payload)),
        ));
    }

    /**
     * Push composed notes to a WS1 Custom Attribute via POST
     * /devices/{uuid}/customattributes. Separate endpoint from the
     * top-level device fields, so this fires independently.
     */
    /**
     * @param  array{target: string, value: string}|null  $composedNotes
     */
    private function pushCustomAttribute(string $uuid, ?array $composedNotes, ?WorkspaceOneClient $client): void
    {
        if ($composedNotes === null) {
            return;
        }

        if ($client === null) {
            Log::channel('sync-adapters')->info(sprintf(
                '%s push [dry-run]: would set Workspace ONE Custom Attribute %s=%s on device %s',
                $this->name(),
                $composedNotes['target'],
                $composedNotes['value'],
                $uuid,
            ));

            return;
        }

        $client->updateDeviceCustomAttribute($uuid, $composedNotes['target'], $composedNotes['value']);
        Log::channel('sync-adapters')->info(sprintf(
            '%s push: set Workspace ONE Custom Attribute "%s" on device %s',
            $this->name(),
            $composedNotes['target'],
            $uuid,
        ));
    }

    private function buildClient(): WorkspaceOneClient
    {
        $apiBaseUrl = $this->url();

        return new WorkspaceOneClient(
            apiBaseUrl: $apiBaseUrl,
            authBaseUrl: $this->deriveAuthBaseUrl($apiBaseUrl),
            tenantCode: $this->credential('tenant_code'),
            clientId: $this->credential('client_id'),
            clientSecret: $this->credential('client_secret'),
        );
    }

    /**
     * Map a source-field name to Workspace ONE's device-record field
     * name. AssetNumber is WS1's native asset_tag equivalent (a
     * top-level string field on the device object).
     */
    private static function sourceFieldToWs1Field(string $field): ?string
    {
        return match ($field) {
            'asset_tag' => 'AssetNumber',
            default => null,
        };
    }
}