Skip to content

A free open source IT asset/license management system

11.1 KB
Raw Blame
<?php

namespace App\SyncAdapters\Intune;

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

/**
 * Thin wrapper around Microsoft Graph for the Intune Managed Devices
 * endpoint. Handles OAuth 2.0 client-credentials token exchange and
 * Graph cursor pagination (via the `@odata.nextLink` response field).
 *
 * Auth model: Azure app registration with a tenant + client_id +
 * client_secret. Token exchange POSTs to the tenant-scoped OAuth 2.0
 * token endpoint with scope `https://graph.microsoft.com/.default`.
 * The returned bearer is valid for ~60 minutes. Pulls that iterate
 * thousands of devices + per-device detail fetches outlast that
 * window, so the bearer is proactively refreshed via expires_in once
 * it enters the TOKEN_REFRESH_WINDOW_SECONDS runway before expiry.
 *
 * Sovereign clouds swap both hosts. The `graphBaseUrl` and
 * `loginBaseUrl` constructor args let the adapter derive the login
 * host from the Graph host so the settings-page URL field controls
 * both endpoints.
 *
 * Graph API version: the unfiltered device pull uses `/v1.0/`, the
 * stable surface. Two call sites fall over to `/beta/` because the
 * stable version does not expose the data they need: the
 * composed-notes push on `updateManagedDevice()` (notes is a
 * beta-only writable field), and the entire scope-tag filter flow
 * (roleScopeTags resource and the roleScopeTagIds filter on
 * managedDevices). Microsoft does not guarantee beta stability, so a
 * Graph side change can break those paths without warning.
 */
class IntuneClient
{
    use RetriesTransientHttpErrors;

    /**
     * Refresh the bearer when it has fewer than this many seconds of
     * validity left. 60s is enough to cover the HTTP request round-trip
     * plus any retry backoff on the next Graph call, while staying tight
     * enough that we only re-fetch when there is a real risk of expiry.
     */
    private const TOKEN_REFRESH_WINDOW_SECONDS = 60;

    private ?string $token = null;

    private ?int $tokenExpiresAt = null;

    public function __construct(
        private readonly string $graphBaseUrl,
        private readonly string $loginBaseUrl,
        private readonly string $tenantId,
        private readonly string $clientId,
        private readonly string $clientSecret,
    ) {}

    /**
     * Iterate every managed device visible to the app registration.
     * Uses Graph's `@odata.nextLink` for cursor pagination.
     *
     * Server-side scope-tag filtering (via `$filter=roleScopeTagIds/any(...)`)
     * was tried first but Microsoft rejects the clause on both v1.0
     * and beta managedDevices endpoints (BadRequest, see #19849).
     * Scope-tag filtering is now applied client-side by the adapter
     * via per-device beta detail fetches, so this method stays on the
     * stable list surface and returns every device.
     *
     * @return iterable<int, array<string, mixed>>
     */
    public function managedDevices(): iterable
    {
        $graphOrigin = $this->origin($this->graphBaseUrl);
        $url = rtrim($this->graphBaseUrl, '/').'/v1.0/deviceManagement/managedDevices';

        do {
            // Pass no second argument. Laravel forwards it as Guzzle's
            // `query` option, which replaces the URL's query string even
            // when empty, stripping the $skiptoken off `@odata.nextLink`.
            // Tenants with more than one page would loop on page 1 forever.
            // See #19916.
            $response = $this->request()->get($url)->throw()->json();

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

            $url = $this->rebasedCursor($response['@odata.nextLink'] ?? null, $graphOrigin);
        } while ($url !== null);
    }

    /**
     * Fetch every role scope tag defined in the tenant. Used by the
     * adapter to resolve admin-entered scope tag names into the IDs
     * the managedDevices filter needs, and (eventually) to populate
     * a settings-page multiselect of available tags.
     *
     * Returns an array of ['id' => '...', 'displayName' => '...'].
     *
     * @return array<int, array{id: string, displayName: string}>
     */
    public function roleScopeTags(): array
    {
        $graphOrigin = $this->origin($this->graphBaseUrl);
        // The roleScopeTag resource is only exposed on /beta/. The
        // stable v1.0 surface returns a 400 "Resource not found for
        // the segment 'roleScopeTags'" so there is no fallback.
        $url = rtrim($this->graphBaseUrl, '/').'/beta/deviceManagement/roleScopeTags';

        $out = [];
        do {
            $response = $this->request()->get($url)->throw()->json();
            foreach (($response['value'] ?? []) as $tag) {
                $id = $tag['id'] ?? null;
                $name = $tag['displayName'] ?? null;
                if (is_scalar($id) && is_string($name)) {
                    $out[] = ['id' => (string) $id, 'displayName' => $name];
                }
            }
            $url = $this->rebasedCursor($response['@odata.nextLink'] ?? null, $graphOrigin);
        } while ($url !== null);

        return $out;
    }

    /**
     * Strip a server-supplied absolute URL down to path+query and
     * re-base it onto the configured graph origin, so a hostile
     * upstream can't redirect the cursor (and its bearer) to an
     * attacker-chosen target. Returns null when the cursor is
     * absent or unparseable, or when the configured graph URL
     * itself has no usable origin.
     */
    private function rebasedCursor(?string $url, ?string $origin): ?string
    {
        if ($url === null || $url === '' || $origin === null) {
            return null;
        }

        $parsed = parse_url($url);
        if (! is_array($parsed)) {
            return null;
        }

        // Reject path-relative cursors with no leading slash
        // ("page2" rather than "/page2"). Rebasing those produced an
        // unparseable "https://hostpage2" that aborted the sync on the
        // next iteration. Fails safe but we'd rather be explicit
        // (reported post-fix by Zer0Gate as a robustness note).
        // Only path+query is kept from the supplied cursor on purpose,
        // so any path prefix on the configured base URL (not Graph's
        // case, but legal in general) is dropped. Absolute cursors are
        // the standard shape here and this matches that.
        $path = $parsed['path'] ?? '/';
        if (! str_starts_with($path, '/')) {
            return null;
        }

        return $origin.$path.(isset($parsed['query']) ? '?'.$parsed['query'] : '');
    }

    /**
     * Scheme+host(+port) of the given absolute URL, or null when it is
     * not a parseable absolute URL.
     */
    private function origin(string $url): ?string
    {
        $parts = parse_url($url);
        if (! is_array($parts) || empty($parts['scheme']) || empty($parts['host'])) {
            return null;
        }

        return $parts['scheme'].'://'.$parts['host'].(isset($parts['port']) ? ':'.$parts['port'] : '');
    }

    /**
     * Per-device GET against Graph's managedDevice endpoint with a
     * caller-chosen $select set. Used for properties the LIST
     * endpoint always returns null for (ethernetMacAddress,
     * physicalMemoryInBytes, etc. - Microsoft docs explicitly flag
     * these as "requires per-device GET"), and for roleScopeTagIds,
     * which the list surface also returns empty regardless of $select
     * (see #19849). Returns the attributes array on success. Fails
     * soft to null on 4xx/5xx so one bad device doesn't abort the
     * enclosing enrichment pass.
     *
     * $apiVersion is passed through so callers can hit `beta` for
     * fields that only populate there (roleScopeTagIds). Default
     * stays on v1.0 for the existing enrichment call sites.
     *
     * @param  array<int, string>  $select
     * @return array<string, mixed>|null
     */
    public function managedDeviceDetail(string $deviceId, array $select, string $apiVersion = 'v1.0'): ?array
    {
        $url = rtrim($this->graphBaseUrl, '/').'/'.$apiVersion.'/deviceManagement/managedDevices/'.rawurlencode($deviceId);

        try {
            return $this->request()
                ->get($url, ['$select' => implode(',', $select)])
                ->throw()
                ->json();
        } catch (\Throwable) {
            return null;
        }
    }

    /**
     * Fetch (or reuse) a bearer token via OAuth 2.0 client-credentials
     * against the tenant-scoped token endpoint. The token is cached on
     * this instance across requests. When the cached token has fewer
     * than TOKEN_REFRESH_WINDOW_SECONDS of validity left, re-exchange
     * so a long-running pull (thousands of devices + per-device detail
     * calls, routinely 60+ minutes) doesn't trip Microsoft's
     * "InvalidAuthenticationToken: Invalid token lifetime" error part
     * way through.
     */
    private function bearer(): string
    {
        if ($this->token !== null && $this->tokenExpiresAt !== null
            && $this->tokenExpiresAt - time() > self::TOKEN_REFRESH_WINDOW_SECONDS) {
            return $this->token;
        }

        $tokenUrl = rtrim($this->loginBaseUrl, '/').'/'.$this->tenantId.'/oauth2/v2.0/token';

        $response = Http::asForm()
            ->withOptions(['allow_redirects' => false])
            ->timeout(30)
            ->post($tokenUrl, [
                'grant_type' => 'client_credentials',
                'client_id' => $this->clientId,
                'client_secret' => $this->clientSecret,
                'scope' => rtrim($this->graphBaseUrl, '/').'/.default',
            ])
            ->throw()
            ->json();

        // expires_in is seconds from issue (RFC 6749). Fall back to a
        // conservative 55 minutes if the server omits it, matching the
        // old implicit assumption but still letting the refresh window
        // kick in before the real expiry.
        $expiresIn = (int) ($response['expires_in'] ?? 3300);
        $this->tokenExpiresAt = time() + $expiresIn;

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

    /**
     * Push writable metadata to a managed device via Graph beta's
     * per-device endpoint. The v1.0 endpoint doesn't expose notes
     * as writable. Beta does (matches what community integrations
     * like Brady Widener's Snipe-IT-Azure-Integration use). Fields
     * the caller doesn't include stay untouched.
     *
     * @param  array<string, scalar|null>  $payload
     */
    public function updateManagedDevice(string $deviceId, array $payload): void
    {
        $url = rtrim($this->graphBaseUrl, '/').'/beta/deviceManagement/managedDevices/'.$deviceId;

        Http::withToken($this->bearer())
            ->withOptions(['allow_redirects' => false])
            ->asJson()
            ->acceptJson()
            ->timeout(30)
            ->patch($url, $payload)
            ->throw();
    }

    private function request(): PendingRequest
    {
        return $this->withTransientRetry(
            Http::withToken($this->bearer())
                ->withOptions(['allow_redirects' => false])
                ->acceptJson()
                ->timeout(30)
        );
    }
}