The Proxy connector deployment files set up Windows, macOS, iOS, and iPadOS devices to send traffic through F5 Workforce AI Security. You deploy the files with mobile device management (MDM) tools such as Microsoft Intune or Jamf Pro, or with other enterprise management tools. Each Windows deploy script already contains the proxy auto-config (PAC) URL of your connector. It also contains the root certificate authority (CA) certificate named SurePath AI Root CA Certificate, and its thumbprint. You don't paste in any of them. Each detect script contains only the thumbprint.

Download the deployment files

If you use an existing Proxy connector, skip steps 3 through 5.

In CONFIGURE, go to Connectors.
Select a Proxy connector, or select ADD CONNECTOR.
Enter a name.
Select Proxy as the connector type.
Select SAVE.
In the MDM Files section, select DOWNLOAD.

When you download the files, Workforce AI Security builds the ZIP file for your connector. The ZIP file has these folders:

mac/
  f5.wais.macos.mobileconfig
  f5.wais.macos.jamf.email.mobileconfig
  f5.wais.macos.jamf.udid.mobileconfig
  f5.wais.macos.intune.email.mobileconfig
  f5.wais.macos.intune.udid.mobileconfig
ios/
  f5.wais.ios.mobileconfig
  chatgpt.ios.appconfig.plist
windows/
  default/          f5.wais.deploy.ps1, f5.wais.detect.ps1                                   # default rollout
  email/            f5.wais.deploy.email.ps1, f5.wais.detect.email.ps1                       # email rollout
  user-email/       f5.wais.deploy.user-email.ps1, f5.wais.detect.user-email.ps1             # per-user setup with email
  baseonly/         f5.wais.deploy.baseonly.ps1, f5.wais.detect.baseonly.ps1                 # setup for shared devices, once per device
  user/             f5.wais.deploy.user.ps1, f5.wais.detect.user.ps1                         # setup for shared devices, once per user
  remove/           f5.wais.deploy.remove.ps1, f5.wais.detect.remove.ps1                     # removal of the system-wide deployment
  remove-baseonly/  f5.wais.deploy.remove-baseonly.ps1, f5.wais.detect.remove-baseonly.ps1   # full removal, same as remove/
  remove-user/      f5.wais.deploy.remove-user.ps1, f5.wais.detect.remove-user.ps1           # removal of one user's setup
  findemail/        f5.wais.deploy.findemail.ps1                                             # test of which email source answers
  configmgr-detect/ f5.wais.configmgr.detect.ps1, f5.wais.configmgr.detect.<FOLDER>.ps1         # detect scripts with -ConfigMgr, one for each folder

Each Windows folder has scripts with a preset value for $argumentOverride. The detect script in a folder has the same preset as the deploy script. The table lists the preset values.

Windows folder	Preset value of `$argumentOverride`	Run as
`default`	`""` (empty)	An admin or the system account
`email`	`"-Email"`	An admin or the system account
`user-email`	`"-User -Email"`	The logged-in user
`baseonly`	`"-BaseOnly"`	An admin or the system account
`user`	`"-User"`	The logged-in user
`remove`	`"-Remove"`	An admin or the system account
`remove-baseonly`	`"-Remove -BaseOnly"`	An admin or the system account
`remove-user`	`"-Remove -User"`	The logged-in user
`findemail`	`"-FindEmail"` (deploy script only)	An admin, in elevated PowerShell

User identification

The PAC URL carries an identifier so that Workforce AI Security can link traffic to a person. The Windows scripts use a globally unique identifier (GUID) by default. Users with a GUID log in to Workforce AI Security once in a browser. That login links the GUID to the user, and Workforce AI Security then attributes traffic from native apps to the user.

The scripts can use the user's email address instead. An email address needs no login.

For how authentication affects User Activity, see Understanding the Proxy Connector (PAC).

Windows PowerShell scripts

Before you start

Before you run a script, verify these conditions:

The script runs in 64-bit PowerShell. The path of 64-bit PowerShell is %SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe.
You run default, email, baseonly, remove, remove-baseonly, and findemail as an admin or as the system account.
You run user, user-email, and remove-user in the context of the logged-in user. These scripts need no admin rights.

Some deployment tools start scripts in 32-bit mode. If your tool can't start 64-bit PowerShell, set the -Allow32Bit parameter to bypass the check. Avoid this option.

Roll out with email identification

Use the email folder to identify users by email address. Users don't log in.

On a test device, open an elevated 64-bit PowerShell session.
Run findemail\f5.wais.deploy.findemail.ps1. The script shows which source supplied the address. It changes nothing.
To change the default order, set -EmailPriority in the preset. Edit the line in f5.wais.deploy.email.ps1, for example:
```
$argumentOverride = "-Email -EmailPriority 'Outlook','Office'"
```
Make the same change in f5.wais.detect.email.ps1.
While the user is logged in, deploy email\f5.wais.deploy.email.ps1 as an admin or as the system account.

A wrong source order can attribute User Activity events to the wrong user. Before you deploy to many devices, check the result of step 2.

The script finds the email address in a different way, depending on who is logged in:

If a user is logged in, the script finds that user and reads the sources of that user. It skips only EntraID, because the process user isn't the logged-in user.
If no user is logged in, for example, when the device starts, the script skips Outlook, Office, OneDrive, UserEnvironment, and EntraID. ActiveDirectory then queries the computer account, not a user. Only the device-level sources remain: Intune, Entra, and IdentityStore. IdentityStore reads a cache for the whole device. If that cache has more than one account, the script uses the first one that it finds.

For an Active Directory deployment, see Deploy to Windows with Active Directory.

The script checks these sources in order and uses the first email address that it finds:

Outlook: reads the primary mailbox of the user in the Outlook profile registry.
Office: reads the registry for the Microsoft 365 or Office identity.
OneDrive: reads the OneDrive for Business account of the user in the OneDrive Accounts registry.
EntraID: runs whoami /upn.
ActiveDirectory: reads the user principal name in on-premises Active Directory. Domain-joined devices only.
UserEnvironment: reads the user principal name in the Volatile Environment registry.
IdentityStore: reads the cache of the Windows identity store.
Intune: reads the MDM enrollment data.
Entra: runs dsregcmd /status, then falls back to the CloudDomainJoin registry.

-EmailPriority takes these exact source names in a comma-separated list. Don't add spaces. Don't use the @() syntax. In a preset, you can put single quotes around each name.

By default, when the script finds no email address, -Email stops with an error. To use a GUID instead, add -FallbackGUID to the preset, for example $argumentOverride = "-Email -FallbackGUID". -FallbackGUID needs -Email. Add -FallbackGUID to both scripts in the folder. When the preset of the detect script also has -FallbackGUID, the detect script treats a GUID as compliant. Otherwise, a GUID isn't compliant.

Roll out the default deployment

If one person is the primary user of a device, use the default folder. Deploy default\f5.wais.deploy.ps1 as an admin or as the system account. The script does these tasks:

Installs the SurePath AI Root CA Certificate in the trusted store for Local Machine.
Sets the PAC URL for the whole device, with a unique GUID.
Sets the proxy settings per machine, so they apply to every account on the device.
Locks the proxy settings so users can't change them.

Each user logs in to Workforce AI Security once in a browser to link the GUID to the user. If many people share a device, use Roll out to shared and multi-user devices instead. To skip the login, use the email rollout.

Roll out to shared and multi-user devices

A shared device needs one machine step and one step for each user, so that each account gets its own PAC URL and identifier.

Run baseonly\f5.wais.deploy.baseonly.ps1 once on each device, as an admin or as the system account. The script installs the certificate and the proxy lock, then exits. It sets no PAC URL and no user identifier. You can run the script again safely.
Run user\f5.wais.deploy.user.ps1 once for each user, in the context of that user. To identify users by email, run user-email\f5.wais.deploy.user-email.ps1 instead. Use a login script or a user-context script.

The user scripts never install certificates, so step 1 comes first.

Remove a deployment

Use these folders to remove a deployment:

remove: removes the system-wide deployment, as an admin.
remove-user: removes the configuration of the logged-in user only. It needs no admin rights.
remove-baseonly: does a full removal, the same as remove.

The remove script checks the system-wide tracking in the HKEY_LOCAL_MACHINE registry hive first. If it finds none, it scans only the user registry hives that are loaded at that time. Those hives belong to the users who are logged in then. The script doesn't check users who aren't logged in. If it finds no deployment in either place, it removes the items that a default deployment creates. It removes the certificate and the policies.

On a multi-user device, run remove-user for each user. Then run remove as an admin.

Use detection scripts

Each folder has a detect script that checks the state that the deploy script in the same folder sets up. Use the two scripts as a pair. The findemail folder has no detect script.

A detect script runs detection by default, so you don't need the -Detect parameter. A detect script never changes the device. A version check also applies, except in baseonly and the remove folders. If the deployed script version differs from the detect script version, the device isn't compliant.

By default, a detect script uses the standard exit codes. Microsoft Configuration Manager (ConfigMgr) and Intune Win32 apps use different detection rules. For these tools, use the scripts in the configmgr-detect folder.

Each script has the preset of its folder, plus -Detect -ConfigMgr. For example, f5.wais.configmgr.detect.email.ps1 checks the email deployment. The configmgr-detect folder has no script for findemail. If the deploy script gets -ConfigMgr, it stops with an error. The table lists the exit codes for each mode.

Result	Standard	With `-ConfigMgr`
Compliant	Exit code 0	Exit code 0, and a line in standard output
Not compliant	Exit code 1	Exit code 0, and empty standard output
Error	Exit code 1	Exit code 1

With an email identifier, a detect script also starts an email recheck. After seven passing runs, the next run reports the device as not compliant one time. A tool such as Intune Remediations then runs the deploy script. The deploy script finds the email address again and resets the count. To change the number of runs, set -EmailRecheckRuns in the preset of the detect script. Set 0 to stop the recheck, for example for a ConfigMgr or Win32 app that you assign as Available.

For Intune Remediations, use the detect script of a folder as the detection script. Use the deploy script of the same folder as the remediation script. Set the same parameters in both, except -Force, which the detect script rejects, and -ConfigMgr, which the deploy script rejects. Don't use the configmgr-detect scripts for Remediations. For step-by-step instructions, see Deploy to Windows with Microsoft Intune.

Update or rerun a deployment

To run or rerun a script by hand, use this command:

powershell.exe -ExecutionPolicy Bypass -File "<SCRIPT_FOLDER_PATH>\f5.wais.deploy.ps1"

Replace <SCRIPT_FOLDER_PATH> with the path of the folder that holds the script.

A rerun with the same parameters and a newer script version updates the deployment. You don't need -Force.
A rerun with the same parameters repairs registry drift. Examples are a removed PAC URL, a proxy lock that is off, or a missing certificate. You don't need -Force.
A rerun with different parameters from the tracked deployment exits with code 1 and the message "Use -Force to overwrite". To apply the change, add -Force to the preset.
-Force keeps a stored GUID. A kept GUID keeps User Activity history and user policies linked.
For email, -Force runs email detection again. If detection fails, the script uses the stored email. Otherwise, the script uses the new result.

The baseonly script skips this check.

Change a preset

A preset is the $argumentOverride = "..." line near the top of a script. To change it:

Open the script in a text editor.
Edit the value in the $argumentOverride line.
Save the script.
Upload the script to your MDM tool.

The preset and the command-line parameters merge. The preset sets only the parameters that it names. Command-line parameters that the preset doesn't name stay set. Use these syntax rules:

Start each parameter with a hyphen (-).
Give a switch parameter no value.
Give a value parameter a value. Put quotes around a value that contains spaces.
Set -FailOpen and -nextDirect to true or false.
Separate parameters with spaces.

The script checks the string and stops with an error if a parameter isn't valid. Before you deploy the change, test it on a device. Make the same change in the detect script of the same folder, but leave out -Force. A detect preset with -Force or -FindEmail stops with "Invalid parameter".

The deploy script also accepts these parameters.

Parameter	What it does
`-FallbackGUID`	If the script finds no email address, uses a GUID. Needs `-Email`. Add it to the deploy script and the detect script.
`-EmailPriority`	Sets which email sources the script checks, and in what order.
`-NoPrevent`	Skips the proxy lock.
`-NoRootCA`	Skips the certificate. If you deploy the certificate another way, use this parameter.
`-CertOnly`	Installs only the certificate, with no proxy lock and no tracking.
`-NoProxy`, `-NoPerUser`	With both set, installs the certificate and the proxy lock with tracking, and sets no PAC URL.
`-addService`	Adds services to the PAC file.
`-chain`	Sends requests that don't match a GenAI service to your existing PAC file.
`-nextHTTP`, `-nextHTTPS`, `-nextDirect`	Set upstream proxy fallbacks. The order is HTTPS fallback, then PROXY, then DIRECT. `-nextDirect` has an effect only with `-nextHTTP` or `-nextHTTPS`.
`-FailOpen`	Sets whether traffic continues when the proxy isn't available.
`-Force`	Applies changed parameters to an existing deployment. The detect script doesn't accept it.
`-Allow32Bit`	Runs the script in 32-bit PowerShell.
`-EmailRecheckRuns`	Sets how many passing detect runs occur before an email recheck. The default is 7. Set `0` to stop the recheck. Only detection reads it.

For what -addService, -chain, and fail-open do, see Overview of proxy auto-config files.

macOS and iOS profiles

Workforce AI Security provides Apple configuration profiles (mobileconfig files) for macOS, iOS, and iPadOS. The macOS profiles are in the mac folder of the ZIP file. The iOS profile and the configuration file for the ChatGPT app are in the ios folder. Each profile installs the SurePath AI Root CA Certificate and sets the PAC URL.

General profiles

These profiles work with any Apple MDM tool.

Profile	Folder	Platform	Description
`f5.wais.ios.mobileconfig`	`ios`	iOS and iPadOS	Sets the proxy and certificate trust for iPhone and iPad devices.
`f5.wais.macos.mobileconfig`	`mac`	macOS	Sets the proxy and certificate trust for Mac computers.

These profiles set the PAC URL without a user identifier. Workforce AI Security associates traffic with the Proxy connector instead of with individual users. If you don't need user-level identification, or if you use other methods to authenticate users, use these profiles.

Upload a profile to your Apple MDM tool and assign it to device groups. The profiles set PayloadRemovalDisallowed to true, so users can't remove them.

Jamf profiles

The Jamf Pro profiles in the mac folder use Jamf payload variables to put a user identifier in the PAC URL. Users don't need to log in.

Profile	Platform	Identifier type	Jamf variable
`f5.wais.macos.jamf.email.mobileconfig`	macOS	User email	`$EMAIL`
`f5.wais.macos.jamf.udid.mobileconfig`	macOS	Unique device identifier (UDID)	`$UDID`

When Jamf deploys a profile, Jamf replaces the variable with a real value:

$EMAIL: Jamf uses the email address from the Jamf user records. Workforce AI Security can then apply user-specific and group-specific policies.
$UDID: Jamf uses the unique identifier of the device. Workforce AI Security links traffic to a device. If Jamf has no user email, use this variable.

When you can, use the email profile. The email profile attributes traffic to users more clearly in User Activity.

To deploy a Jamf profile:

Upload the profile to Jamf Pro as a configuration profile.
Assign the profile to a scope of computers or users.

Jamf processes the payload variables during deployment. For step-by-step instructions, see Deploy to Apple devices with Jamf Pro.

Intune profiles

The Intune profiles in the mac folder put a user identifier in the PAC URL, like the Jamf profiles.

Profile	Platform	Identifier type
`f5.wais.macos.intune.email.mobileconfig`	macOS	User email
`f5.wais.macos.intune.udid.mobileconfig`	macOS	UDID

Email: Workforce AI Security attributes traffic to the email address of the user assigned to the device in Intune. Users never see a login page. The device must have an assigned user with an email address in Intune.
UDID: Workforce AI Security links traffic to the UDID of the device. Users must log in before Workforce AI Security attributes traffic to them. If you prefer an explicit login step, use this profile.

To deploy an Intune profile, create a custom configuration profile in Intune and upload the mobileconfig file. For step-by-step instructions, see Deploy to macOS with Microsoft Intune.

ChatGPT certificate pinning

The ChatGPT desktop app for macOS and the ChatGPT iOS app use certificate pinning. They check the TLS certificate of each connection against a list of allowed public key hashes in the app. When a TLS inspection proxy presents its own certificate, the app rejects the connection and shows a network error. The ChatGPT web app at chat.openai.com isn't affected, because browsers handle TLS differently.

Certificate pinning on macOS

Every macOS mobileconfig file has a com.apple.ManagedClient.preferences payload. The payload sets the com.openai.pinned_cert_hash_list managed preference for the ChatGPT app. The preference tells the app which certificate hashes to trust, in addition to the built-in list of the app. The hash for the SurePath AI Root CA Certificate is already in every macOS profile:

<key>com.openai.pinned_cert_hash_list</key>
<array>
    <string>SvR7vxkWyBgFQXn17BRLU3R6Nkzcrp9WKwR+Qaa8ygk=</string>
</array>

You need no other setup. After you deploy any macOS profile from the mac folder, the ChatGPT desktop app works through the proxy.

Certificate pinning on iOS

The iOS mobileconfig file doesn't have the pinning payload, because iOS delivers managed app preferences in a different way. The ios folder has a separate file, chatgpt.ios.appconfig.plist. Deploy the file as Managed App Configuration through your MDM tool, not as a configuration profile:

Intune:
1. Create an app configuration policy for managed devices.
2. Select the ChatGPT app.
3. Upload the plist file as custom configuration data.
Jamf: Add the app configuration to the ChatGPT entry in the Managed App Catalog.

For the exact steps, see the documentation of your MDM vendor for Managed App Configuration.

Add the hash of a custom root certificate authority

Your network might use a platform for secure access service edge (SASE) or a third-party gateway. If the platform or gateway has its own root CA, add the hash of that CA certificate to the com.openai.pinned_cert_hash_list array. The array holds many entries, so both hashes can be in the array.

To make the hash from a certificate file, run these commands. The output is the base64-encoded SHA-256 hash of the Subject Public Key Info (SPKI) to add to the array. Replace <ROOT_CA_CERTIFICATE_PATH> with the path of the file for your root CA certificate.

On macOS or Linux:

openssl x509 -in <ROOT_CA_CERTIFICATE_PATH> -pubkey -noout \
  | openssl pkey -pubin -outform DER \
  | openssl dgst -sha256 -binary \
  | openssl base64

On Windows, in PowerShell:

openssl x509 -in "<ROOT_CA_CERTIFICATE_PATH>" -pubkey -noout `
  | openssl pkey -pubin -outform DER `
  | openssl dgst -sha256 -binary `
  | openssl base64

Add the new hash as another <string> entry. Replace <ROOT_CA_HASH> with the hash from the previous command.

<key>com.openai.pinned_cert_hash_list</key>
<array>
    <string>SvR7vxkWyBgFQXn17BRLU3R6Nkzcrp9WKwR+Qaa8ygk=</string>
    <string><ROOT_CA_HASH></string>
</array>

Update the mobileconfig files, then deploy the profiles again through your MDM tool. For the iOS app, add the same array to chatgpt.ios.appconfig.plist and deploy the app configuration policy again.

Options for the proxy auto-config address

The PAC URL accepts query parameters that change how traffic is handled, such as extra services, a chained PAC file, and upstream proxy fallbacks. When you set -addService, -chain, -nextHTTP, -nextHTTPS, and -nextDirect in a preset, the Windows scripts add these parameters to the URL. -nextDirect takes true or false. It has an effect only with -nextHTTP or -nextHTTPS. For all parameters and what they do, see Overview of proxy auto-config files.

Verify the integration

After you deploy the files, open the Ready tool on a device that you set up to check certificate trust and network configuration. For how to read the results, see Verify the integration.

Use the Proxy connector deployment files