iOS Per-App VPN: Match the App's VPNUUID, Not PayloadUUID

Two UUID values decide whether one managed iPhone app rides the per-app tunnel, and neither of them is the identifier of the profile that carries them. The app's VPNUUID attribute must equal the VPNUUID inside the per-app VPN payload. The deployed app must also be managed by the same device management service, and the command you send must actually carry the attribute. Work through the four stages below in order, because each one produces a value the next stage needs.

Collect four identifiers before touching the device

Write down four values: the bundle identifier from your management inventory, the identifier of the per-app VPN payload, the VPNUUID inside that payload, and the identifier of the command you are about to send. The bundle identifier names the application that receives the settings, and the label on the home screen is no substitute for it. Keep PayloadUUID out of this list entirely, since it identifies a payload inside a profile and answers a different question. Substituting it because both fields look like UUIDs is the most common way to build an association that can never match.

If the VPN administrator has not handed you the per-app payload and its identifier, ask for them rather than scraping a UUID from whatever configuration file is nearest.

Apply the attribute through the management channel

Confirm that the target app is managed on that device, because a known bundle identifier does not make an unmanaged installation eligible for the association. Then send a settings item of type ApplicationAttributes through your product's per-app VPN assignment or its supported implementation of the Settings command. The item identifies the app by bundle identifier and carries an Attributes dictionary whose VPNUUID matches the payload. Nothing in that item is a full command envelope, and nothing in it can be installed as a profile by hand.

Treat removal as deliberately as installation. The schema says that omitting the Attributes dictionary removes the app's existing attributes, so a partially built update quietly becomes a reset. The similarly named Managed Application Attributes command reads attributes back for verification; it does not set them, and using it as the setter is a wasted deployment window.

Read the command result, not the app icon

Check the acknowledgement for the command you sent and confirm that the managed app now reports the attribute. A VPN badge in the status bar only says a tunnel exists somewhere on the phone. It cannot tell you that this particular app is assigned to the per-app configuration, and on a device where the tunnel opens on demand the badge may never appear at all. Compare identifiers in the assignment rather than looking for a visual cue.

If two per-app configurations exist on the same fleet, compare their identifiers before assuming your assignment landed in the intended one.

Test with the resource, then record the pair

Have an authorised user open the private resource from the assigned app and watch whether the per-app tunnel comes up for it. Then repeat from a non-managed app on the same phone and confirm the treatment differs. That contrast is the actual test, because a working private resource could also have been reached through a device-wide tunnel nobody mentioned in the change record. Record the result while the device is in front of you.

Store the bundle identifier, the payload identifier, the shared VPNUUID and the command result together, so the next investigation starts from the same four values instead of from memory.

Roll back without collateral

To remove the assignment, resend the app attribute with an empty Attributes dictionary in the form your product documents, rather than dropping the app from the command. Verify afterwards that the app no longer opens the per-app tunnel and that other managed apps kept theirs. If the same phone also has a device-wide VPN profile, confirm it still behaves as it did before the rollback, since two VPN configurations on one device is where this step usually goes wrong. Then update the record you kept.

An audit asking why a particular app was ever tunneled will want the pair of UUIDs and a date, not a description of the deployment.