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 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.

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.

When the deployment script runs without any parameters, it performs a complete system-wide configuration that applies to all users on the device. This default deployment is suitable for single-user devices or scenarios where admins want consistent proxy settings for all users on a machine.

The default deployment performs the following operations:

The GUID identifier included in the PAC URL helps associate native application traffic with the users making requests, which improves reporting accuracy and user activity tracking in the SurePath AI platform.

To perform a default system-wide deployment, run the script as an admin:

This configuration requires admin privileges and creates a system-level deployment that persists across all user sessions on the device.

For shared computers or multi-user environments where admins need user-specific proxy configuration, the deployment process requires two steps: a one-time machine setup and a per-user configuration.

The machine setup installs the SurePath AI root CA certificate and configures security policies without setting the proxy URL. This step requires admin privileges and only needs to be performed once per machine.

Run the deployment script with the -NoProxy parameter:

This command installs the certificate to the Local Machine store and locks proxy settings to prevent user modification, but skips configuring the PAC URL. The certificate installation is necessary for SurePath AI to intercept and apply policy to HTTPS traffic.

After completing the machine setup, each user account needs its own proxy configuration. This step configures the PAC URL in the user's registry (HKCU) and does not require admin privileges.

Run the deployment script with the -User parameter:

This command configures the proxy settings for the current user only. Organizations typically deploy this as a login script so that the configuration runs automatically when each user logs in to the device for the first time. The script needs to run once per user per machine to establish the user-specific proxy configuration.

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:

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:

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 PowerShell script supports several additional parameters that provide fine-grained control over which components are configured during deployment.

Parameter

Description

-Force

Overwrites an existing SurePath AI deployment with new settings

-NoPerUser

Skips configuring system-wide proxy settings (does not apply computer-wide policies)

-NoPrevent

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

-NoRootCA

Skips installing the root CA certificate

-Remove

Switches the script to removal mode instead of deployment

-Check

Re-verifies registry settings after 10 seconds and re-applies them if they have been changed

-Allow32Bit

Allows the script to run in 32-bit PowerShell (not recommended)

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.

User-level deployment with email detection:

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.

User-level deployment with custom email detection priority:

This configuration specifies that the script should only check Entra ID and Intune sources for email detection, in that order. This is useful in environments where only specific identity sources are reliable or available.

User-level deployment requiring email (no GUID fallback):

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.

System-wide deployment with fail-open enabled:

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.

System-wide deployment without certificate installation:

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.

Force overwrite existing deployment:

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.

User-level removal:

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.

System-wide removal:

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.

Post-deployment verification:

This configuration performs the standard deployment and then waits 10 seconds before re-verifying all registry settings. If any settings have been changed or removed by Group Policy or other management tools, the script automatically re-applies them. This is useful in environments where other policies might conflict with or overwrite the SurePath AI configuration.

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

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:

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.

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, 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.