A free open source IT asset/license management system
<?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,
};
}
}