GSAClientDiagnosticsToolkit

Author(s)

• Michael Morten Sonne

Tags

GSA GlobalSecureAccess Global-Secure-Access MicrosoftEntra Entra EntraID AzureAD EntraInternetAccess EntraPrivateAccess PrivateAccess InternetAccess ZTNA SSE ZeroTrust Troubleshooting Diagnostics Connectivity HealthCheck mTLS DNS Microsoft Windows

Functions

Invoke-GSAClientConnectivityCheck Get-GSAEndpoints Get-GSAAppProtectionExclusionServicePrincipals Export-GSAEdgeAddresses Test-GSAServiceStatus Test-DeviceEntraStatus Test-GSAPrimaryRefreshToken Test-GSAForwardingProfileRegistry Test-GSAForwardingProfileTimestamp Test-GSASecureDnsStatus Test-GSAIPv6Status Test-GSASyntheticRoutes Test-GSAPrivateDnsResolver Test-GSAVpnSplitDnsInteroperability Test-GSAEventLog Test-InternetConnectivity Test-DnsResolution Test-GSATenantInternetDnsResolution Test-TLSConnection Test-mTLSConnectivity Test-ProxyDetection Test-EntraIDConnectivity Test-EntraIDUserAuthentication Test-GSADiagnosticUriConnectivity Test-GSAPrivateAccessRule Test-GSAPrivateAccessTunnel Test-GSAForwardingProfileAssignment Test-GSAClientProfileConnectivity Test-GSAPrivateAccessApplicationSegment Test-GSAPrivateAccessApplication Test-GSAIntelligentLocalAccessConfiguration Test-GSAHomeNetworkSupport Test-GSAAuthCertificate Export-GSAAuthCertificate Repair-GSAAuthCertificate

PSEditions

Desktop

Dependencies

This module has no dependencies.

Release Notes

### Added

- Microsoft Graph-based checks, adapted to this module's conventions:
 - `Test-GSAForwardingProfileAssignment` - tenant onboarding, forwarding profile enablement, and user/group assignment.
 - `Test-GSAClientProfileConnectivity` - local edge/diagnostic connectivity per forwarding profile channel (`m365`/`private`/`internet`), testing all three by default when `-ProfileType` is omitted.
 - `Test-GSAPrivateAccessApplicationSegment` - Private Access application enablement, assignment, and application segment (FQDN/IP/port/protocol) matching via Graph.
 - `Test-GSAPrivateAccessApplication` - end-to-end Private Access application check combining the segment check with a live tunnel test.
- Automatic interactive `Connect-MgGraph` sign-in fallback (via the optional `Microsoft.Graph.Authentication` module) when `-AccessToken` isn't supplied to the Graph-based checks, reusing any already-active session.
- Local/offline Private Access checks: `Test-GSAPrivateAccessRule` (matches a target FQDN/IP + port + protocol against the locally cached forwarding profile's rules) and `Test-GSAPrivateAccessTunnel` (verifies a live tunnel connection resolves to a synthetic `6.6.x.x` address and resolves via the GSA Private DNS resolver).
- `-PassThru` switch on the new Private Access and Graph-based functions so they stay silent by default and only return a `$true`/`$false` result when explicitly requested.
- `-LogLevel` parameter on public functions to override the module's logging verbosity per call.
- New connectivity tests: `Test-GSAPrimaryRefreshToken`, `Test-GSAForwardingProfileRegistry`, `Test-GSAForwardingProfileTimestamp`, `Test-GSAServiceStatus`, `Test-GSASecureDnsStatus`, `Test-GSAIPv6Status`, `Test-GSASyntheticRoutes`, `Test-GSAPrivateDnsResolver`, `Test-GSAEventLog`, `Test-DeviceEntraStatus`, and `Test-EntraIDConnectivity`.
- `Test-GSATenantInternetDnsResolution` - validates `<tenantId>.internet.client.globalsecureaccess.microsoft.com` and `<tenantId>.internet-backup.client.globalsecureaccess.microsoft.com`, expects synthetic `6.6.0.0/16` answers (with CNAME aliases), compares against direct DNS (`-NoHostsFile`), and flags local hosts-file/private-IP overrides.
- Converted the original monolithic `GSAClientDiagnosticsToolkit.ps1` script into a proper PowerShell module (`src/GSAClientDiagnosticsToolkit.psd1`/`.psm1`) with `Public`/`Private` folder structure and `Invoke-GSAClientConnectivityCheck` as the orchestrator.
- Module manifest metadata: `LicenseUri`, `CompatiblePSEditions`, `HelpInfoURI`, and `ReleaseNotes`.
- Pester test suite (`tests/Public`, `tests/Private`) covering the module manifest/export consistency, private helper logic, and public function behavior via mocked dependencies.
- `Test-GSAAuthCertificate` - checks whether a valid GSA mTLS authentication certificate (subject ending in `gsa.client`) exists in the LocalMachine\My store and hasn't expired, mirroring the client's built-in "Authentication certificate exists"/"Authentication certificate is valid" Health check tests.
- `Export-GSAAuthCertificate` - read-only backup of the GSA authentication certificate(s) (password-protected `.pfx` with the private key when exportable, otherwise a public-key-only `.cer`), usable standalone or as the backup step reused by `Repair-GSAAuthCertificate`.
- `Repair-GSAAuthCertificate` - remediation for a missing/invalid authentication certificate: always backs up the certificate first via `Export-GSAAuthCertificate`, requires two separate confirmations before deleting it (standard `-WhatIf`/`-Confirm` plus typing the exact thumbprint), clears the `CertCommonName` registry value, and can optionally restart `GlobalSecureAccessEngineService` via `-RestartEngineService`.
- `Get-GSAAppProtectionExclusionServicePrincipals` - returns the known Global Secure Access-related service principals/app IDs to exclude in App Protection policies (based on field validation on Windows and iOS), and validates each App ID in-tenant via Microsoft Graph to report existence and current state.
- `Test-GSAIntelligentLocalAccessConfiguration` - checks Intelligent Local Access (ILA) Private Network definitions via Microsoft Graph (`networkAccess/privateNetworks`) for probe FQDNs that are publicly resolvable, and DNS server/expected IP addresses that are public rather than private (RFC1918) - a confirmed real-world root cause of GSA incorrectly bypassing Private Access traffic to a local connection for users who were never on the corporate network (e.g. on hotel/home Wi-Fi). Resolves each Private Network's associated App IDs to friendly display names (via the same `tags/Any` filter the Entra portal uses) and flags App IDs that no longer resolve to a known ZTNA/Quick Access application. Public resolvability is checked via DNS-over-HTTPS instead of a classic port-53 query, since the latter can be silently intercepted/answered by the local GSA client (WFP driver) or a router's own local DNS records; a resulting GSA synthetic `6.6.x.x` address is detected and reported as inconclusive rather than a false failure. Supports a `-FQDN` manual mode (with optional `-DnsServerAddress`/`-ExpectedIPAddress`) to check a single candidate FQDN without calling Microsoft Graph.
- `Test-GSAVpnSplitDnsInteroperability` - local/offline interoperability check for Cisco VPN + GSA private DNS/NRPT overlap scenarios that can produce `REFUSED` DNS lookups for a private suffix. Detects active Cisco adapter + matching NRPT rule + REFUSED probe lookup and recommends allowing source `6.6.0.0/16` in Cisco split-DNS/extended ACL source networks.
- `Test-GSAHomeNetworkSupport` - local/offline check of Private Access home network support ("Allow local subnet bypass"). Reads the Private Access channel of the cached forwarding profile and verifies that the `localNetwork.isLocalNetworkFeatureEnabled` setting is present (a missing setting suggests a client without home network support) and enabled, calculates the directly connected RFC1918 IPv4 subnets from active adapters (IP + mask, as the client does), and warns when a local subnet overlaps tunneled Private Access IP rules (corporate destinations that become unreachable while "Prefer Local Network" is on). See [Configure home network support for Microsoft Entra Private Access](https://learn.microsoft.com/en-us/entra/global-secure-access/how-to-configure-home-network-support?wt.mc_id=MVP_353010).

### Changed

- Refactored PowerShell scripts for improved readability and consistency.
- Enhanced logging and error handling across connectivity tests, including detailed DEBUG-level information for DNS chain retrieval, Entra ID status, GSA event log scanning, and service status checks.

### Fixed

- Incorrect `tenantId` reference in `Test-GSAForwardingProfileRegistry` logging.
- Noisy `Resolve-DnsName` output in `Test-GSAPrivateDnsResolver`.
- Missing/failed GSA service test result handling.
- `Select-Object -ExpandProperty` failing with "Property cannot be found" when Graph responses came back as `Hashtable` objects from `Invoke-MgGraphRequest` (as opposed to `PSCustomObject` from `Invoke-RestMethod`).