Skip to content

A free open source IT asset/license management system

10.5 KB
Raw Blame
<?php

namespace App\SyncAdapters\AppleBusinessManager;

use App\SyncAdapters\Traits\RetriesTransientHttpErrors;
use Firebase\JWT\JWT;
use Illuminate\Http\Client\PendingRequest;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Str;

/**
 * Thin wrapper around Apple Business Manager (ABM) and Apple School
 * Manager (ASM) REST APIs. Both products share the same endpoint shape
 * and JWT client-assertion auth model. Only the base host differs
 * (api-business.apple.com vs api-school.apple.com). The mode toggle in
 * the adapter's credential schema picks which host + scope to use.
 *
 * Auth model: Apple issues an OAuth application (Settings > API in the
 * ABM/ASM console) as a Client ID + Key ID + downloaded EC P-256
 * private key (.pem). This client signs a JWT client-assertion with
 * ES256, exchanges it at account.apple.com for a short-lived bearer,
 * and caches that bearer for the life of the sync run.
 *
 * Pagination: /v1/orgDevices uses `limit` + `cursor` for forward
 * paging. `Meta.Paging.Total` gives the total record count when the
 * caller wants to size progress reporting.
 */
class AppleBusinessManagerClient
{
    use RetriesTransientHttpErrors;

    private const APPLE_AUDIENCE = 'https://account.apple.com/auth/oauth2/v2/token';

    private const APPLE_TOKEN_ENDPOINT = 'https://account.apple.com/auth/oauth2/v2/token';

    private ?string $accessToken = null;

    /**
     * @param  'business'|'school'  $mode
     */
    public function __construct(
        private readonly string $clientId,
        private readonly string $keyId,
        private readonly string $privateKeyPem,
        private readonly string $mode = 'business',
    ) {}

    /**
     * Iterate every device in the org. Devices come back with an
     * `Attributes` object carrying SerialNumber, PartNumber,
     * ProductFamily, Color, OrderNumber, OrderDateTime, and other
     * pre-provisioning fields. Hostnames / OS versions / last-seen
     * are NOT here (ABM is a purchase-registration portal, not a
     * runtime inventory), so downstream mapping leaves those null.
     *
     * @return iterable<int, array<string, mixed>>
     */
    public function devices(int $pageSize = 100): iterable
    {
        $cursor = null;

        do {
            $params = ['limit' => $pageSize];
            if (is_string($cursor)) {
                $params['cursor'] = $cursor;
            }

            $response = $this->request()
                ->get('/v1/orgDevices', $params)
                ->throw()
                ->json();

            $devices = $response['data'] ?? [];
            foreach ($devices as $device) {
                yield $device;
            }

            $cursor = $response['meta']['paging']['nextCursor'] ?? null;
        } while (is_string($cursor) && $cursor !== '');
    }

    /**
     * Fetch every AppleCare coverage plan for a single device. Apple
     * returns an array (a device can carry multiple overlapping plans
     * for various renewals / extensions), so callers pick the best
     * one for their purposes. Each entry has an attributes object
     * with agreementNumber, startDateTime, endDateTime, status,
     * paymentType, isCanceled, isRenewable, description.
     *
     * @return array<int, array<string, mixed>>
     */
    public function deviceAppleCareCoverage(string $deviceId): array
    {
        $response = $this->request()
            ->get('/v1/orgDevices/'.$deviceId.'/appleCareCoverage')
            ->throw()
            ->json();

        return $response['data'] ?? [];
    }

    /**
     * Fetch Activation Lock status for one device. Apple returns a
     * single Device-shaped object with an attributes.activationLockEnabled
     * boolean. Handy at asset-checkin time since Activation Lock has
     * to be cleared before a device can be redeployed to a new user.
     *
     * @return array<string, mixed>
     */
    public function deviceActivationLockStatus(string $deviceId): array
    {
        $response = $this->request()
            ->get('/v1/orgDevices/'.$deviceId.'/activationLockStatus')
            ->throw()
            ->json();

        return $response['data'] ?? [];
    }

    /**
     * List every device enrolled in Apple Business Manager's built-in
     * MDM (formerly Apple Business Essentials, now folded into AxM).
     * Cheap: one call per sync run. The id on each entry IS the
     * device's serial number, so the adapter joins straight to
     * orgDevices by serial. Records that don't appear here just
     * aren't enrolled in the built-in MDM and stay un-enriched.
     *
     * @return iterable<int, array<string, mixed>>
     */
    public function mdmDevices(int $pageSize = 100): iterable
    {
        $cursor = null;

        do {
            $params = ['limit' => $pageSize];
            if (is_string($cursor)) {
                $params['cursor'] = $cursor;
            }

            $response = $this->request()
                ->get('/v1/mdmDevices', $params)
                ->throw()
                ->json();

            foreach ($response['data'] ?? [] as $device) {
                yield $device;
            }

            $cursor = $response['meta']['paging']['nextCursor'] ?? null;
        } while (is_string($cursor) && $cursor !== '');
    }

    /**
     * Fetch runtime detail for one MDM-enrolled device: osVersion,
     * lastCheckInDateTime, MAC addresses, storage, security posture
     * (FileVault, firewall, lock/lost/erase statuses). One call per
     * device, so gated behind hasMappedMdmDeviceDetailFields() at
     * the adapter side.
     *
     * @return array<string, mixed>
     */
    public function mdmDeviceDetails(string $serial): array
    {
        $response = $this->request()
            ->get('/v1/mdmDevices/'.$serial.'/details')
            ->throw()
            ->json();

        return $response['data'] ?? [];
    }

    /**
     * Build a device-id -> MDM server name map by walking every MDM
     * server's device linkages. Devices unassigned to any MDM server
     * simply aren't in the returned map, so a `?? ''` fallback at the
     * adapter side keeps normalize() clean. Called once per sync run.
     *
     * @return array<string, string>
     */
    public function deviceToMdmServerMap(): array
    {
        $servers = $this->request()
            ->get('/v1/mdmServers')
            ->throw()
            ->json();

        $serverNames = [];
        foreach ($servers['data'] ?? [] as $server) {
            $id = $server['id'] ?? null;
            $name = $server['attributes']['serverName'] ?? null;
            if (is_string($id) && is_string($name)) {
                $serverNames[$id] = $name;
            }
        }

        $deviceToServer = [];
        foreach ($serverNames as $serverId => $serverName) {
            $cursor = null;
            do {
                $params = ['limit' => 1000];
                if (is_string($cursor)) {
                    $params['cursor'] = $cursor;
                }
                $response = $this->request()
                    ->get('/v1/mdmServers/'.$serverId.'/relationships/devices', $params)
                    ->throw()
                    ->json();

                foreach ($response['data'] ?? [] as $linkage) {
                    $deviceId = $linkage['id'] ?? null;
                    if (is_string($deviceId)) {
                        $deviceToServer[$deviceId] = $serverName;
                    }
                }

                $cursor = $response['meta']['paging']['nextCursor'] ?? null;
            } while (is_string($cursor) && $cursor !== '');
        }

        return $deviceToServer;
    }

    /**
     * Base HTTP client with resolved bearer token. On 429 the sleep
     * callback honors Apple's `Retry-After` header (capped at 2
     * minutes so a very long server-side cooldown doesn't stall the
     * sync beyond user patience). Falls back to exponential backoff
     * when Retry-After is missing from the API response.
     *
     * The N+1 per-device enrichment calls (AppleCare, Activation Lock,
     * MDM details) are still the biggest cost on large pulls - admins
     * who hit 429 even with this retry logic can trim mappings that
     * drive those extra per-device fetches.
     */
    private function request(): PendingRequest
    {
        return $this->withTransientRetry(
            Http::baseUrl($this->apiBaseUrl())
                ->withOptions(['allow_redirects' => false])
                ->withToken($this->bearer())
                ->acceptJson()
                ->timeout(30)
        );
    }

    /**
     * Exchange a signed JWT client-assertion for a bearer token.
     * Tokens are short-lived (~1 hour) and cached on this instance so
     * a full sync doesn't retrigger auth per request. Failures throw
     * up to the sync runner and land in the sync-adapters log.
     */
    private function bearer(): string
    {
        if ($this->accessToken !== null) {
            return $this->accessToken;
        }

        $assertion = $this->buildClientAssertion();

        $response = Http::asForm()
            ->withOptions(['allow_redirects' => false])
            ->timeout(30)
            ->post(self::APPLE_TOKEN_ENDPOINT, [
                'grant_type' => 'client_credentials',
                'client_id' => $this->clientId,
                'client_assertion_type' => 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
                'client_assertion' => $assertion,
                'scope' => $this->tokenScope(),
            ])
            ->throw()
            ->json();

        return $this->accessToken = (string) ($response['access_token'] ?? '');
    }

    /**
     * Sign an ES256 JWT client-assertion. Apple requires 180-day max
     * expiration. We use 5 minutes, which is more than enough for the
     * single token exchange this triggers. jti keeps replay windows
     * closed even under a rotating fleet of sync processes.
     */
    private function buildClientAssertion(): string
    {
        $now = time();
        $payload = [
            'sub' => $this->clientId,
            'aud' => self::APPLE_AUDIENCE,
            'iss' => $this->clientId,
            'iat' => $now,
            'exp' => $now + 300,
            'jti' => (string) Str::uuid(),
        ];

        return JWT::encode($payload, $this->privateKeyPem, 'ES256', $this->keyId);
    }

    private function apiBaseUrl(): string
    {
        return $this->mode === 'school'
            ? 'https://api-school.apple.com'
            : 'https://api-business.apple.com';
    }

    private function tokenScope(): string
    {
        return $this->mode === 'school' ? 'school.api' : 'business.api';
    }
}