Active Directory Group Policy offers multiple deployment methods, and this document covers both the recommended PowerShell script approach and the manual Group Policy configuration method.

This document provides two methods for deploying SurePath AI proxy configurations through Active Directory Group Policy. The recommended approach uses a PowerShell script that simplifies deployment, supports both single-user and shared devices, enables email-based user identification, and provides greater flexibility for managing configurations. The alternative manual method uses Group Policy Objects for organizations that prefer policy-based deployment or need to integrate with existing Group Policy configurations.

Both methods deploy the SurePath AI PAC URL to configure proxy settings and the SurePath AI root CA certificate to enable traffic interception. This document does not cover how to connect devices to an Active Directory or how to manage or distribute Group Policy within Active Directory.

SurePath AI distributes its proxy information via a Proxy Auto-Config (PAC) file. This PAC file contains all the information needed to direct only generative AI traffic to the SurePath AI proxy service while sending other traffic via their normal route.

The use of a PAC file also allows SurePath AI to update the list of generative AI domains. Most operating systems and browsers will request the PAC file every 1-2 hours and if a new file can't be retrieved the current one will continue to be used.

Just like other network security and SASE vendors, certificate trust allows SurePath AI to intercept and apply policy to connections to generative AI websites. The SurePath AI root CA certificate needs to be trusted by all devices that need to be governed by SurePath AI.

All configuration in this section takes place within the Group Policy Management console available on an Active Directory server or on a client system with the Remote Server Administration Tools (RSAT) tools installed.

The following items are needed before deploying SurePath AI through Active Directory Group Policy:

The PowerShell deployment script provides a flexible and automated way to configure proxy settings on Windows devices. To download the script:

The PowerShell deployment script provides the most flexible and streamlined approach for deploying SurePath AI proxy configurations to Windows devices through Active Directory Group Policy. This method is recommended for most deployments because it simplifies configuration management, supports both single-user and shared device scenarios, enables email-based user identification for improved reporting, and allows for easier updates to proxy settings compared to managing multiple individual Group Policy settings.

The PowerShell script offers several advantages over manual Group Policy configuration:

When deploying PowerShell scripts through Group Policy, admins need to understand how Computer Configuration and User Configuration scripts work:

Computer Configuration startup scripts execute during system startup before any user logs in. These scripts run with Local System privileges and can modify machine-wide settings in HKLM registry, install certificates to the Local Machine store, and make system-level changes. Use Computer Configuration startup scripts for single-user device deployments and for machine setup in shared device scenarios.

User Configuration logon scripts execute when a user logs in and run under that user's credentials. These scripts can modify user-specific settings in HKCU registry but have limited privileges. Use User Configuration logon scripts for deploying user-specific configurations in shared device scenarios.

When a Group Policy Object containing a logon script is linked to an Organizational Unit, the script executes for every user who logs into devices within that OU.

Important: 64-bit PowerShell requirement

The SurePath AI deployment script must run in 64-bit PowerShell on 64-bit Windows systems. When adding scripts to Group Policy, always use the full path to 64-bit PowerShell: %SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe. This ensures proper script execution and compatibility with modern Windows environments. Only use the 32-bit path (%SystemRoot%\SysWOW64\WindowsPowerShell\v1.0\powershell.exe) if deploying to 32-bit Windows systems, which are rare in enterprise environments.

For devices where only one user regularly signs in, the PowerShell script can be configured to deploy a complete system-wide configuration through a Computer Configuration startup script. This approach is ideal for personal work devices, dedicated workstations, or scenarios where each device is assigned to a specific user. Since there is only one user per device, the script can run with Local System privileges to install the certificate, configure the PAC URL, and apply security policies all at once.

Before deploying the script through Group Policy, admins need to configure the argumentOverride variable to specify the deployment parameters.

Recommended configuration (default with GUID identifier):

By default, the script includes a unique GUID identifier in the PAC URL for user identification. This approach is recommended because it works reliably in all environments without requiring email address detection, which can vary in availability across different identity configurations. The GUID provides consistent user tracking in SurePath AI's User Activity logs and enables user-specific policy application.

To use the default GUID-based identification, leave the argumentOverride variable empty or do not modify the script:

The script will automatically:

Optional: Email-based identification

Alternatively, admins can 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. However, this approach depends on the availability of email information from identity sources (Active Directory, Entra ID, or user environment variables).

To enable email-based identification:

With this configuration, the script attempts to detect the user's email address from multiple sources in this order:

If email detection fails, the script automatically falls back to using a GUID identifier. Organizations that require email-based identification without fallback can add the -NoGUID flag (e.g., $argumentOverride = "-Email -NoGUID"), though this causes deployment to fail if email cannot be detected.

After configuring the argumentOverride variable, admins can deploy the script to target devices through Group Policy Computer Configuration startup scripts:

After creating the GPO, link it to the Organizational Units containing single-user devices:

The script will execute during the next system startup on devices within the linked OU. The complete configuration (certificate, PAC URL, and security policies) will be applied to each device.

For devices where multiple users sign in, such as shared workstations, kiosks, or terminal servers, the deployment requires a two-step approach. The first step installs the root CA certificate and configures security policies at the machine level, while the second step deploys user-specific proxy settings when each user signs in.

Step 1: Machine setup (one-time per device)

The machine setup configures components that apply to all users on the device:

Admins can perform this step using either manual Group Policy configuration or a PowerShell script with the -NoProxy flag deployed via Computer Configuration startup scripts. Both approaches achieve the same result, and organizations can choose based on their existing Group Policy preferences.

Step 2: User-level proxy configuration (runs at each user's first login)

After the machine is set up, each user who signs in needs their own proxy configuration. This step deploys the PAC URL with user-specific identifiers (GUID by default, or optionally email addresses) to each user's registry (HKCU) using User Configuration logon scripts, enabling SurePath AI to track activity by individual users rather than just by device.

Option A: Use manual Group Policy for certificate and lockdown

Admins can deploy the root CA certificate and proxy lockdown policies using standard Group Policy settings. This approach integrates well with existing certificate and policy management workflows.

For certificate deployment, follow the steps in the "SurePath AI root certificate distribution" section under Method 2 (Manual Group Policy configuration) below.

For proxy lockdown policies, follow the steps in the "Prevent users from changing proxy settings" section under Method 2 (Manual Group Policy configuration) below.

Option B: Use PowerShell script with -NoProxy flag

Alternatively, admins can use the PowerShell deployment script to install the certificate and configure security policies without setting the PAC URL. This approach is useful for organizations that prefer a single script-based approach for all components.

To configure the script for machine setup:

Deploy this version of the script using Group Policy Computer Configuration startup scripts:

The script will install the certificate and configure lockdown policies without setting the PAC URL.

After completing the machine setup, deploy a second PowerShell script configured for user-level proxy settings. This script should run when each user signs in to ensure every user receives the proper proxy configuration with their own unique identifier.

Recommended configuration (default with GUID identifier):

By default, the script includes a unique GUID identifier in the PAC URL for each user. This approach is recommended because it works reliably in all environments and provides consistent per-user tracking in SurePath AI without requiring email address detection. Each user who signs into the shared device receives their own unique identifier in the PAC URL.

To configure the script with default GUID-based identification:

Optional: Email-based identification

Alternatively, admins can enable email-based identification, which eliminates the need for users to authenticate when accessing GenAI services. The script will detect each user's email address from multiple identity sources (including Entra ID, Outlook, Office, Intune, Active Directory, and others) and include it in the PAC URL. If email detection fails for a particular user, the script automatically falls back to GUID.

To enable email-based identification, use:

When configured with the -Email flag, the script attempts to detect the user's email address from multiple sources including Active Directory, Entra ID Registry, and user environment variables. The first successfully detected email address is included in the PAC URL.

Deploy this version through Group Policy User Configuration logon scripts:

This configuration sets the PAC URL in each user's registry (HKCU) with their unique identifier (GUID by default, or email address if the -Email flag was configured). Because the machine setup already installed the certificate, this script completes quickly for each user. Each user receives their own personalized proxy configuration the first time they log in to the shared device, enabling SurePath AI to track activity and apply policies on a per-user basis rather than just by connector or device.

The manual Group Policy configuration method provides an alternative approach for deploying SurePath AI proxy settings through standard Group Policy Objects. This method may be preferred by organizations that use policy-based management exclusively or need to integrate SurePath AI settings with existing Group Policy configurations.

The manual method requires creating multiple Group Policy settings: one for the PAC URL and proxy settings, one for preventing users from changing proxy settings, and one for distributing the root CA certificate. While this approach provides fine-grained control over each component, it requires more administrative effort to create and maintain compared to the PowerShell script method.

The PAC URL can be distributed using either Internet Settings preferences or Registry preferences. Only configure one of these settings to avoid potentially conflicting Group Policy configurations.

After configuring the Group Policy settings, link the GPO to the appropriate Organizational Units:

After deploying SurePath AI configurations through either the PowerShell script method or the manual Group Policy method, admins can verify that endpoints are properly configured by using the Ready tool at https://ready.surepath.ai. The Ready 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 when the page loads 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 endpoint will be processed by SurePath AI.

If the Certificate Trust test shows a red Invalid result, the SurePath AI root certificate is not trusted by the device or browser. This could indicate that the certificate has not been deployed to the device yet, or that the device needs to be restarted for the browser to recognize the newly installed certificate. Admins should check the device's local certificate trust store for the SurePath AI Root CA certificate.

If the Network Configuration test shows a red Invalid result, the SurePath AI platform is not receiving traffic from the endpoint. This is most likely because the proxy configuration has not been pushed to the device, or because Group Policy has not yet been applied or refreshed. Admins can run gpupdate /force from a command prompt to force Group Policy refresh. Some browsers or applications, like Firefox, ignore system-level proxy settings and have internal proxy settings that will need to be configured separately from the system-level settings documented in this guide.

Admins should reach out to their SurePath AI account team if they have questions or issues with the SurePath AI integration.

This section outlines a few user experiences and other caveats that admins should be aware of when using this deployment model.

Group Policy can take a significant amount of time to propagate throughout an organization. To test on a specific Windows host immediately a simple command can be given to the device to force it to download the latest Group Policy from Active Directory.

Open a command prompt (CMD) on the Windows device with administrative privileges

SurePath AI is designed to enhance security and control access to generative AI web services, such as ChatGPT, by requiring users to authenticate through a web browser. This authentication process ensures that only authorized individuals have access. However, this approach presents a challenge for certain applications and platforms that have integrated or embedded generative AI capabilities directly into their systems.

These embedded AI services are tightly integrated within their host applications and are not designed to operate through external web browsers. As a result, they cannot complete the web-based authentication process required by SurePath AI. When attempts are made to route these embedded services through SurePath AI, they may encounter difficulties and may not function as intended.

Recognizing this limitation, the development team at SurePath AI is actively working on a solution to support these embedded generative AI services. This effort aims to expand the versatility of SurePath AI and ensure it can work seamlessly with a wider range of AI-powered applications and platforms.

As progress is made in developing this support for embedded services, this documentation will be updated to reflect new features and capabilities. Users and admins are encouraged to check back regularly for the latest information on how SurePath AI can be used with various types of generative AI services, including embedded ones.

Some applications have the ability to bypass system-level network configurations such as proxies. Mozilla Firefox is an example of a browser that can either use the system-level settings or be configured to override those settings. These applications usually have the ability to control this behavior through the use of group policies or configurations, but some may not.