SurePath AI provides MDM deployment files for configuring Windows and Apple devices to use the secure proxy service. These files are designed to be deployed at scale through Mobile Device Management (MDM) platforms such as Microsoft Intune, JAMF, or other enterprise management tools. The deployment files support customizable options to meet diverse organizational needs, including system-wide or user-level configurations, user identification methods, and automated certificate installation.

The MDM deployment files are available from the Proxy Connector configuration page in the SurePath AI admin interface.

The downloaded ZIP file contains deployment files for both Windows and Apple platforms:

Organizations can deploy SurePath AI proxy configurations through standard MDM configuration policies such as Microsoft Intune's Custom OMA-URI profiles or basic Apple configuration profiles. However, these standard approaches typically set a basic PAC URL without user-specific identifiers, which means all traffic from a device is associated only with the Proxy Connector itself. This approach is known as Connector authentication, where SurePath AI can identify which connector the traffic came from but cannot distinguish between individual users on shared devices or associate native application traffic with specific users.

The SurePath AI MDM files enhance this capability by including unique identifiers in the PAC URL. For Windows devices, the PowerShell script can add a GUID or email identifier that associates traffic with individual user sessions. For Apple devices, JAMF-specific and Intune-specific configuration profiles can include user email addresses or device UDIDs. When user-specific identifiers are included in the PAC URL, SurePath AI can accurately attribute all traffic—including native application requests—to individual users rather than just the connector.

This improved user identification provides several operational benefits. First, it significantly reduces instances of Connector authentication in User Activity logs, making it easier for admins to audit and report on individual user behavior. Second, it enables more granular policy application based on user identity rather than just device or connector identity. This is particularly valuable for organizations that need to apply different policies to different users or groups, as SurePath AI can enforce user-specific or group-specific policies even for traffic that would otherwise only be identifiable at the connector level.

The PowerShell script (SurePath.AI.deploy.ps1) provides flexible deployment options for Windows devices, supporting both system-wide and user-level configurations with optional email-based user identification.

As of script version 4.1.0, the deployment package adds optional PAC URL query parameters for upstream proxy fallbacks (-nextHTTP, -nextHTTPS, -nextDirect), stores those values in deployment tracking for compliance checks, and can automatically repair installs when registry-only drift is detected on a rerun with the same parameters (see Intune Remediations and Additional deployment parameters). -Force reuses the persisted user identifier (GUID or email) instead of minting a new one when repair or overwrite runs.

The deployment script requires 64-bit PowerShell by default. This requirement ensures compatibility with system registry operations and certificate management functions. If the script detects that it is running in 32-bit PowerShell, it will display an error message and exit:

To run the script in 64-bit PowerShell, use the following path:

Most PowerShell environments default to 64-bit mode on 64-bit Windows systems. However, some deployment tools or scheduled task configurations may inadvertently launch scripts in 32-bit mode. If an environment requires running the script in 32-bit mode, admins can use the -Allow32Bit parameter to bypass the architecture check, though this is not recommended for production deployments.

To run the deployment script from a command prompt or a remote execution tool, use the following syntax:

To add parameters, append them after the script path:

[!WARNING] When using powershell.exe -File, PowerShell does not evaluate expressions — everything after the script path is treated as literal values. This means the @() array constructor syntax does not work. Always pass array values as comma-separated lists with no spaces (e.g., Outlook,Office).

If you need the full PowerShell expression syntax (including @()), use -Command instead of -File:

[!NOTE] When using -Command, wrap the entire command string in double quotes, use & to invoke the script, enclose the script path in single quotes, and use single quotes for string values inside the array.

The sections below describe the three deployment patterns admins use most often. For the full parameter reference, certificate-only modes, removal, and Intune Remediations, see the later sections in Windows PowerShell deployment.

When the deployment script runs with no parameters, it performs a complete system-wide configuration. The proxy and PAC settings apply to every Windows account on the device, but this pattern is intended for machines where one person is the primary user in practice—not shared workstations where different people sign in and need separate attribution. For the latter, use Shared devices (multi-user).

Run the script as an admin:

This default deployment:

Because the PAC URL uses a machine-scoped identifier rather than a resolved user email, SurePath AI typically attributes traffic using Connector authentication unless users complete explicit authentication flows. Organizations that need transparent per-user attribution without those prompts should use Email-based identification or a Shared-device (multi-user) deployment instead.

On reruns with the same parameters, version 4.1.0 and later can repair registry drift automatically when deployment tracking exists and the only mismatches are registry tampering (for example PAC URL, proxy lock, or certificate state). Parameter changes still require -Force or matching skip flags as described in Intune Remediations. Installs with no tracking registry cannot be drift-repaired this way; the script exits with an error so admins can reconcile intent. -Forcepreserves the persisted user identifier (GUID or email) instead of generating a new one when possible.

Email-based identification passes the user’s email in the PAC URL so SurePath AI can attribute traffic without relying on Connector authentication alone. Before rolling this out broadly, admins should discover which email source works on a representative device.

Review the output to see which source supplied the address, then deploy with -Email and tune order using -EmailPriority (comma-separated list, no spaces when using powershell.exe -File). Example:

For detection sources, precedence, -NoGUID, and argument-override examples, see Email-based user identification. Misconfigured email sources can mis-attribute User Activity events, so validating with -FindEmail first is strongly recommended.

Shared workstations, session hosts, and other multi-user Windows systems need machine preparation plus a per-user proxy configuration so each account gets its own PAC URL and identifier.

Optionally combine the user step with email identification:

Organizations typically run the user step as a logon script or Intune Run script in user context. For an alternative machine prep that does write tracking metadata (useful when compliance detection must see a machine record), see Certificate-only deployments and the -NoProxy / -NoPerUser combination there.

By default, the script includes a GUID identifier in the PAC URL. Admins can instead configure the script to detect and use the user's email address for identification. Email-based identification eliminates the need for users to authenticate when accessing GenAI services through SurePath AI, as the platform can automatically identify users based on their email address passed in the PAC URL.

To enable email-based identification, run the deployment script with the -Email parameter:

Before production rollout, admins should run -FindEmail from an elevated 64-bit PowerShell session as described under Email-based identification, then set -EmailPriority to match the reliable sources in their environment. Failure to confirm the correct source order may result in mis-attributed User Activity events.

When email-based identification is enabled, the script attempts to detect the user's email address from multiple sources. The default detection order prioritizes the most reliable and commonly available sources:

The script uses the first successfully detected email address and includes it in the PAC URL. If no email can be detected from any source, the script falls back to using the GUID identifier by default.

Admins can customize which sources the script checks and the order in which they are evaluated using the -EmailPriority parameter. This is useful in environments where only specific identity sources are available or where certain sources provide more reliable results.

To specify custom detection sources and order:

Note: Do not use the @() array syntax when passing -EmailPriority on the command line or via powershell.exe -File. Use comma-separated values with no spaces (e.g., Outlook,Office). The @() syntax is only evaluated in interactive PowerShell sessions, not when scripts are invoked with -File.

Available source identifiers for the -EmailPriority parameter include: Entra, Outlook, Office, Intune, ActiveDirectory, EntraID, UserEnvironment, and IdentityStore.

In scenarios where organizations require email-based identification without fallback to GUID, admins can use the -NoGUID parameter. This configuration causes the deployment to fail if email detection is unsuccessful, rather than falling back to GUID mode.

This strict email requirement ensures that all deployments use consistent email-based identification, but requires that the device environment supports at least one of the email detection sources.

The script intelligently removes SurePath AI configurations based on how the deployment was originally performed. The script tracks deployment metadata to ensure complete and accurate removal of all configured components.

To remove a system-wide (admin) deployment, run the script with the -Remove parameter as an admin:

The removal process performs an intelligent three-step process:

This approach ensures complete removal whether the original deployment was tracked or performed with an earlier version of the script. Admin privileges are required for system-wide removal operations.

To remove a user-level deployment, run the script with both -Remove and -User parameters:

This command removes the proxy configuration from the current user's registry (HKCU) only and does not affect system-level settings or other user accounts. Admin privileges are not required for user-level removal.

For multi-user deployments where both machine and user setups were performed, admins should run the user-level removal for each affected user account, then run the system-wide removal to remove the certificate and system policies.

The combination of -NoProxy and -NoPerUser parameters enables certificate-only deployments where the script installs the SurePath AI root CA certificate and configures proxy lockdown policies without setting any proxy configuration. This deployment mode is useful in scenarios where organizations want to pre-install the certificate and establish security policies but configure the actual proxy settings separately or through a different mechanism.

When the script runs with both -NoProxy and -NoPerUser parameters, it performs the following operations:

To perform a certificate-only deployment:

This command requires admin privileges because it modifies the Local Machine certificate store and system security policies. After running this deployment, admins can configure the PAC URL through other means while ensuring that the necessary certificate trust and proxy protection are already established on the device.

These parameters can be combined with other parameters such as -Force to overwrite existing deployments or -NoPrevent to skip the proxy lock configuration. Organizations can also use this combination in the $argumentOverride configuration for MDM deployments where certificate installation and proxy lockdown need to be separated from proxy configuration.

For scenarios that require a lighter-weight alternative without deployment tracking, the script also provides two dedicated fast-path modes:

The key difference between -NoProxy -NoPerUser and these modes is that -NoProxy -NoPerUser writes a tracking registry entry (enabling subsequent removal and compliance detection), while -BaseOnly and -CertOnly are stateless operations that skip the conflict check and tracking write entirely.

The PowerShell script supports several additional parameters that provide fine-grained control over which components are configured during deployment.

Parameter

Description

Use case

-Remove

Switches the script to removal mode to uninstall SurePath AI configurations

Decommissioning SurePath AI from devices or preparing for fresh deployment

-Detect

Runs in detection-only mode — checks if the current deployment matches the intended parameters and exits with code 0 (compliant) or 1 (non-compliant) without making changes, including when the device is out of compliance due to registry drift (drift is not auto-repaired in this mode)

Intune Remediations detection script, compliance checks, deployment verification

-BaseOnly

Admin-only mode that installs the SurePath AI root CA certificate and configures the proxy lock, then exits — skipping PAC URL configuration, ProxySettingsPerUser, user identifier detection, and the tracking registry. Idempotent: safe to run repeatedly without triggering conflict checks.

Machine preparation step in a two-step multi-user deployment: run -BaseOnly once as admin to install the certificate and proxy lock, then run -User per user to configure per-user PAC URLs. Unlike -NoProxy -NoPerUser, this mode does not write a tracking registry entry.

-CertOnly

Admin-only mode that installs only the SurePath AI root CA certificate to the Local Machine trusted root store, then exits — no proxy lock, no PAC URL, no ProxySettingsPerUser, no tracking registry. Idempotent: skips installation if the certificate is already present.

Environments where the certificate must be deployed separately from all other proxy configuration (e.g., certificate via an Intune device script, proxy settings via Group Policy or a separate user-context script)

-User

Configures proxy settings in the current user's registry (HKCU) only, without requiring admin privileges

Multi-user environments where each user needs their own proxy configuration, or MDM deployments running in user context

-Email

Enables email-based user identification by detecting the user's email address from system sources

Organizations that want to eliminate authentication prompts and improve user attribution in User Activity logs

-NoProxy

Installs certificate and security policies without configuring the PAC URL

Multi-user machine setup step - prepares the device for per-user proxy configurations

-NoPerUser

Installs certificate and security policies without configuring any proxy settings

Scenarios where certificate trust needs to be established separately from proxy configuration (e.g., proxy set via Group Policy)

-Force

Overwrites an existing SurePath AI deployment with new settings; preserves the persisted user identifier (GUID or email) when redeploying or repairing drift instead of generating a new one

Updating configurations on devices that already have SurePath AI deployed, Intune remediation runs, or correcting misconfigured deployments

Parameter

Description

Use case

-EmailPriority

Specifies which sources to check for email detection and in what order (e.g., -EmailPriority Outlook,Office)

Environments where only specific identity sources are reliable or when optimizing email detection performance

-NoGUID

Prevents fallback to GUID identification if email detection fails, causing deployment to fail instead

Organizations that require strict email-based identification for all deployments

-NoPrevent

Skips configuring the proxy lock, allowing users to modify proxy settings

Testing environments or scenarios where users need the ability to temporarily disable the proxy

-NoRootCA

Skips installing the root CA certificate

Certificate is deployed separately through Group Policy or another MDM policy (not applicable for -User mode, which never installs certificates)

-addService

Adds custom domains to the proxy service list (e.g., -addService "example.com,test.com")

Organizations that need to route additional domains through SurePath AI beyond the default GenAI services

-chain

Specifies a fallback PAC file URL to use when SurePath AI proxy cannot be reached

Environments with existing proxy infrastructure that should be used as a fallback

-nextHTTP

Appends a nextHTTP query parameter to the PAC URL: upstream HTTP proxy fallback as host or host:port (hostname or IPv4-style host; optional port 1–65535). IPv6 literals are not supported in the script because the colon is ambiguous with the port separator.

Environments that must chain to an existing HTTP proxy after SurePath AI routing logic

-nextHTTPS

Appends a nextHTTPS query parameter to the PAC URL: upstream HTTPS proxy fallback with the same host and port rules as -nextHTTP

Environments that must chain to an existing HTTPS proxy after SurePath AI routing logic

-nextDirect

Appends a nextDirect query parameter (true or false). Meaningful only when at least one of -nextHTTP / -nextHTTPS is set; otherwise the script logs a warning and ignores it. SurePath AI evaluates fallback order on the server as HTTPS fallback → PROXY → DIRECT when both upstream proxies are configured.

Scenarios that need explicit direct fallback behavior alongside upstream proxy fallbacks

-FailOpen

Sets fail-open behavior in the PAC file (-FailOpen true or -FailOpen false)

Environments that need network access to continue if the SurePath AI proxy becomes unavailable

-FindEmail

Runs email detection only and displays the result without configuring anything

Diagnosing email detection issues on a device before deploying with -Email

-Allow32Bit

Allows the script to run in 32-bit PowerShell, bypassing the architecture check

Legacy systems or deployment tools that cannot launch 64-bit PowerShell (not recommended for production)

Some MDM platforms, including Microsoft Intune, do not support passing command-line arguments to PowerShell scripts during deployment. This limitation prevents admins from using the parameter-based configuration options described in the previous sections. To address this constraint, the deployment script provides an argument override feature that allows admins to embed the desired parameters directly within the script file before uploading it to the MDM platform.

The argument override feature uses a configuration variable at the beginning of the script that, when set, replaces any runtime parameters with the hard-coded values. This approach enables admins to configure all deployment options—including user-level deployment, email detection, removal operations, and advanced settings—even when the MDM platform cannot pass parameters to the script at execution time.

To configure parameters for MDM deployment, admins need to modify the $argumentOverride variable in the script file before uploading it to the MDM platform. The configuration block is located near the top of the script (around lines 63-77) and contains clear instructions and examples.

To set the argument override:

Once configured, the argument override applies every time the script executes. The script validates the override string when it runs and provides clear error messages if invalid parameters or syntax are detected. Admins should test the parameter configuration by running the script locally before deploying it through the MDM platform to production devices.

The argument override string uses the same parameter syntax as PowerShell command-line execution, with some important formatting requirements:

All parameters documented in the "Additional deployment parameters" section can be used in the argument override string. The script performs validation when processing the override and will display detailed error messages if invalid parameter names, missing values, or incorrect syntax are detected.

The following examples demonstrate common deployment scenarios using the argument override feature. Each example shows the exact string to place between the quotation marks in the $argumentOverride = "" line.

This configuration deploys the proxy settings to the current user's registry (HKCU) only and attempts to detect the user's email address for identification. This is the most common configuration for Intune deployments where the script runs in the user context and email-based identification is desired. The script will fall back to GUID generation if email detection fails.

Note: When specifying -EmailPriority in $argumentOverride, use comma-separated values, not the @() array syntax. Values can optionally be wrapped in single quotes: 'Outlook','Office'.

This configuration specifies that the script should only check Outlook and Office sources for email detection, in that order—a common pattern for M365 desktop clients. Admins should still confirm order with -FindEmail on representative devices.

This configuration requires successful email detection and will cause the deployment to fail if no email address can be detected from any source. This ensures all deployments use email-based identification consistently, though it requires that devices support at least one email detection method.

This configuration performs a standard system-wide deployment but configures the PAC file to allow traffic to continue if the SurePath AI proxy service is unavailable. This prevents network outages if the proxy becomes unreachable.

This configuration performs a system-wide deployment but skips installing the root CA certificate. This is appropriate when the certificate has been deployed separately through Group Policy or another MDM policy. Note that user-level deployments (-User) never install certificates regardless of this setting.

This configuration overwrites an existing SurePath AI deployment with new settings. This is useful when updating deployment configurations or reconfiguring devices that already have SurePath AI deployed.

This configuration removes the SurePath AI proxy settings from the current user's registry. Organizations can deploy this configuration through the MDM to remove user-level deployments without requiring admin privileges.

This configuration removes the system-wide SurePath AI deployment, including registry settings and the root CA certificate. This requires admin privileges and will scan all registry locations to ensure complete removal.

Admins should be aware of several important behaviors when using the argument override feature:

Starting in version v3.4.0, the deployment script returns meaningful exit codes that can be used with MDM platforms that support remediation or compliance workflows:

Intune Remediations (formerly called Proactive Remediations) allow admins to run a detection script that checks device state and a remediation script that corrects it. The deployment script supports this workflow using the -Detect and -Force parameters.

Both the detection and remediation scripts are the same SurePath.AI.deploy.ps1 file configured with different $argumentOverride values:

When run with -Detect, the script verifies the following:

[!IMPORTANT] The detection and remediation scripts must use identical parameters describing the intended deployment state. The only differences should be that the detection script uses -Detect and the remediation script uses -Force. If the parameters don't match, the remediation will apply a configuration that differs from what the detection expects, causing an infinite detect→remediate loop.

Each example below shows the $argumentOverride value to set in the detection script and the matching value for the remediation script.

Detection script:

Remediation script:

Detection script:

Remediation script:

Detection script:

Remediation script:

Detection script:

Remediation script:

Detection script:

Remediation script:

Detection script:

Remediation script:

Detection script:

Remediation script:

SurePath AI provides Apple configuration profiles (mobileconfig files) for deploying proxy settings to iOS, iPadOS, and macOS devices. These profiles install the SurePath AI root CA certificate and configure the PAC URL for automatic proxy configuration.

The following configuration profiles work with any Apple MDM platform:

Profile

Platform

Description

surepath.ai.ios.mobileconfig

iOS/iPadOS

Configures proxy settings and certificate trust for iPhone and iPad devices

surepath.ai.macos.mobileconfig

macOS

Configures proxy settings and certificate trust for Mac computers

These profiles configure the PAC URL without user-specific identifiers, which means traffic is associated with the Proxy Connector rather than individual users. This is appropriate for scenarios where user-level identification is not required or where organizations use other methods for user authentication.

To deploy these profiles, upload them to your Apple MDM platform and assign them to the appropriate device groups. The profiles are configured with PayloadRemovalDisallowed set to true, which prevents users from removing the configuration.

For organizations using JAMF Pro, SurePath AI provides configuration profiles that leverage JAMF payload variables to include user-specific identifiers in the PAC URL. These profiles enable user-level traffic attribution without requiring users to authenticate.

Profile

Platform

Identifier Type

JAMF Variable

surepath.ai.macos.jamf.email.mobileconfig

macOS

User email

$EMAIL

surepath.ai.macos.jamf.udid.mobileconfig

macOS

Device UDID

$UDID

When JAMF deploys these profiles, it automatically substitutes the payload variables with actual values:

The email-based identification is generally preferred because it enables user-specific policy application and provides clearer attribution in User Activity logs. The UDID-based identification is useful as a fallback when user email information is not available in JAMF.

To deploy JAMF-specific profiles:

For organizations using Microsoft Intune, SurePath AI provides configuration profiles specifically designed for Intune deployments. These profiles enable user-specific identifiers to be included in the PAC URL, providing user-level traffic attribution similar to the JAMF-specific profiles.

Profile

Platform

Identifier Type

surepath.ai.macos.intune.email.mobileconfig

macOS

User email

surepath.ai.macos.intune.udid.mobileconfig

macOS

Device UDID

The Intune-specific profiles work similarly to the JAMF profiles but are designed for Microsoft Intune's deployment mechanism:

Organizations should choose between the email and UDID variants based on their security requirements and user experience preferences. The email method provides a seamless experience but automatically attributes traffic without authentication prompts, while the UDID method requires explicit user authentication before traffic can be attributed to individual users.

To deploy Intune-specific profiles, admins need to create a Custom configuration profile in the Microsoft Endpoint Manager admin center and upload the appropriate mobileconfig file. For detailed deployment instructions, see the Microsoft Intune - Distributing configuration for macOS documentation.

The PAC file URL supports several query parameters that modify how traffic is handled. These parameters can be appended directly to the PAC URL when configuring endpoints through MDM or other deployment methods. For comprehensive documentation of all PAC URL parameters including service list customization and PAC file chaining, see the Overview of SurePath AI PAC Files documentation.

The PAC URL can include nextHTTP, nextHTTPS, and nextDirect query parameters so SurePath AI can fall back to an organization’s upstream proxies after applying its own routing rules. On Windows, the deployment script appends these when admins pass -nextHTTP, -nextHTTPS, and -nextDirect (see Advanced configuration parameters); values are validated and persisted in deployment tracking for consistent reruns and -Detect checks. When both upstream proxies are set, SurePath AI evaluates fallback order as HTTPS fallback → PROXY → DIRECT.

By default, certain user agents that do not fully support TLS proxying or PAC semantics are forced to DIRECT mode for matched GenAI service domains. This means traffic from these user agents bypasses SurePath AI governance entirely. The current unsupported user agent is WinHttp-Autoproxy-Service/5.1.

Admins can override this behavior by appending the ignoreUnsupported query parameter to the PAC file URL:

When ignoreUnsupported=true is set:

This parameter is useful when admins have confirmed that a user agent listed as unsupported can successfully complete TLS proxying in their environment, or when organizations want to attempt proxy routing for all traffic regardless of user agent classification.

When configuring this parameter through MDM deployments, admins can include it in the PAC URL that the deployment script or configuration profile uses. For Windows PowerShell deployments, the -addService, -chain, -nextHTTP, -nextHTTPS, -nextDirect, and other PAC URL parameters can be configured using the $argumentOverride variable as described in the "Configuring hard-coded parameters" section.

After deploying the MDM files to Windows or Apple devices, admins can verify that endpoints are properly configured to integrate with SurePath AI by using the Ready tool. This verification tool checks both certificate trust and network configuration to ensure that GenAI traffic will be properly routed through and governed by the SurePath AI platform.

To verify the integration, navigate to https://ready.surepath.ai from a configured endpoint. The tool automatically runs tests and displays validation results. If both the Certificate Trust and Network Configuration tests show green Valid results, the endpoint is properly integrated and GenAI traffic originating from that device will be processed by SurePath AI.

For detailed information about interpreting Ready tool results and troubleshooting integration issues, see the Verifying the SurePath AI Integration documentation.