VPN plugin declarative configuration for Apple devices

Use the VPN plugin configuration to set up a VPN connection that’s handled by a third-party VPN app installed on the device. The device passes the connection settings to the app identified by its VPN subtype.

The VPN plugin configuration supports the following:

Minimum supported operating system versions and channels: iOS 27, iPadOS 27, Shared iPad device, macOS 27 device, tvOS 27, visionOS 27.
Requires supervision: No.
Supported enrollment methods: Device Enrollment, Automated Device Enrollment.

VPN plugin

Setting	Description	Required
Visible name	The name of the VPN connection that the operating system displays on the device.	Yes
Hostname	The IP address or hostname of the VPN server.	Yes
VPN subtype	An identifier for a vendor-specified configuration dictionary. If the configuration targets a VPN solution that uses a VPN plugin, then this field contains the bundle identifier of the plugin. If the configuration targets a VPN solution that uses a network extension provider, then this field contains the bundle identifier of the app that contains the provider. Contact the VPN solution vendor for the value of the identifier.	Yes
Vendor configuration dictionary	The vendor-specific configuration dictionary, which the operating system reads only when VPN subtype has a value. See the Vendor configuration dictionary.	No
Authentication details	Settings that control authentication. See the Authentication details settings.	No
Provider details	Specifies details about the provider. See the Provider details settings.	No
Network routing details	Specifies details about how the VPN routes different types of network traffic. See the Network routing details settings.	No
Disconnect on idle settings	Specifies details about how the operating system handles idle VPN connections. See the Disconnect on idle settings.	No
On Demand details	Specifies details about how the operating system controls VPN On Demand. See the On Demand details settings.	No
DNS	A dictionary to use for all VPN types. See the DNS settings.	No
Proxies	The dictionary to use to configure Proxies for use with VPN. See the Proxy settings.	No

Vendor configuration dictionary

Setting	Description	Required
Group	The group to connect to on the head end. Valid for Cisco AnyConnect and Cisco Legacy AnyConnect.	No
Login group or domain	The login group or domain. Valid only for SonicWALL Mobile Connect.	No
Realm	The Kerberos realm name, which needs to be properly capitalized. Valid only for Juniper SSL and Pulse Secure.	No
Role	The role to select when connecting to the server. Valid only for Juniper SSL and Pulse Secure.	No

Authentication details settings

Setting	Description	Required
Authentication method	The authentication method to use. Possible options are password, certificate, or password and certificate.	Yes
Credentials asset reference	The identifier of an asset declaration that contains the credentials to authenticate with the VPN server for password authentication.	No
Identity asset reference	The identifier of a credential asset declaration that contains the identity that this account requires to authenticate with the VPN server for certificate authentication.	No

Provider details settings

Setting	Description	Required
Composed identifier	If the VPN subtype field contains the bundle identifier of an app that contains multiple VPN providers of the same type (app-proxy or packet-tunnel), then the operating system uses this field to choose which provider to use for this configuration. If the VPN provider is implemented as a System Extension, then this field is required. In iOS, iPadOS, tvOS, and visionOS, the identifier is a bundle ID, for example, “`com.melardclothing.app`.” In macOS, the identifier is a composed identifier. The format of the composed identifier is either “`Bundle-ID`”or “`Bundle-ID {Designated-Requirement}`.” “`Bundle-ID`” is the bundle identifier string of the provider. For example, “`com.melardclothing.app`” for the bundle ID format, or “`com.melardclothing.app {anchor apple generic}`” for the designated requirement format.	No
Type	The type of VPN service. App proxy tunnels traffic at the app level, packet tunnel tunnels traffic at the IP layer.	No

Setting

Description

Required

Composed identifier

If the VPN subtype field contains the bundle identifier of an app that contains multiple VPN providers of the same type (app-proxy or packet-tunnel), then the operating system uses this field to choose which provider to use for this configuration.

If the VPN provider is implemented as a System Extension, then this field is required. In iOS, iPadOS, tvOS, and visionOS, the identifier is a bundle ID, for example, “com.melardclothing.app.”

In macOS, the identifier is a composed identifier. The format of the composed identifier is either “Bundle-ID”or “Bundle-ID {Designated-Requirement}.” “Bundle-ID” is the bundle identifier string of the provider. For example, “com.melardclothing.app” for the bundle ID format, or “com.melardclothing.app {anchor apple generic}” for the designated requirement format.

Type

The type of VPN service. App proxy tunnels traffic at the app level, packet tunnel tunnels traffic at the IP layer.

Network routing details settings

Setting	Description	Required
Enforce routes	If turned on, all the VPN’s non-default routes take precedence over any locally defined routes. If include all networks is turned on, the operating system ignores the value of enforce routes.	No
Exclude APNs	If turned on and include all networks is turned on, then the operating system excludes the network traffic for the Apple Push Notification service (APNs) from the tunnel.	No
Exclude cellular services	If turned on and include all networks is turned on, then the operating system excludes internet-routable network traffic for cellular services (VoLTE, Wi-Fi Calling, IMS, MMS, Visual Voicemail, and so on) from the tunnel. Note that some cellular carriers route cellular services traffic directly to the carrier network, bypassing the internet. Such cellular services traffic is always excluded from the tunnel.	No
Exclude device communication	If turned on and include all networks is turned on, the device excludes network traffic used for communicating with devices connected through USB or Wi-Fi from the tunnel.	No
Exclude local networks	If turned on and include all networks is turned on, routes all local network traffic outside the VPN.	No
Include all networks	If turned on, routes all traffic through the VPN, with some exclusions. Several of the exclusions can be controlled with the exclude local networks, exclude cellular services, exclude APNs, and exclude device communication properties. The following traffic is always excluded from the tunnel: Traffic necessary for connecting and maintaining the device’s network connection, such as DHCP. Traffic necessary for connecting to captive networks. Certain cellular services traffic that’s not routable over the internet and is instead directly routed to the cellular network. See the `ExcludeCellularServices` property for more details.	No

Disconnect on idle settings

Setting	Description	Required
Disconnect on idle time	The length of time to wait, in seconds, before disconnecting an On Demand connection.	No
Enable disconnect on idle	If turned on, disconnects after an On Demand connection idles.	No

On Demand details settings

Setting	Description	Required
Enable VPN On Demand	Turns on VPN On Demand.	No
On Demand rules	A list of dictionaries defining On Demand rules. Each item is described in the On Demand rules settings.	No
Prevent users from toggling VPN On Demand	Turns off the Connect On Demand toggle in Settings or System Settings for this configuration.	No

On Demand rules settings

Setting	Description	Required
Action parameters	A list of dictionaries that provides rules that are evaluated on each connection instead of when the network changes. This value is only for use with dictionaries in which the On Demand action option is evaluate. The operating system evaluates these dictionaries in order and the first dictionary that matches determines the behavior. Each item specifies a list of domains, domain action, a list of required DNS servers, and required URL string probe.	No
DNS domain match	A list of domain names. This rule matches if any of the domain names in the specified list matches any domain in the device’s search domains list. The operating system supports a wildcard (`\`) prefix. For example, `\.melardclothing.com` matches against either `mydomain.melardclothing.com` or `yourdomain.melardclothing.com`.	No
DNS server address match	A list of IP addresses. This rule matches if any of the network’s specified DNS servers match any entry in the list. The operating system supports matching with a single wildcard. For example, `17.\*` matches any DNS server in the `17.0.0.0/8` subnet.	No
Interface type match	An interface type. If specified, this rule matches only if the primary network interface hardware matches the specified type.	No
On Demand action	The action to take if this dictionary matches the current network. Possible options are: Unconditionally initiate a VPN connection on the next network attempt. Tear down the VPN connection and don’t reconnect On Demand as long as this dictionary matches. Evaluate the action parameters list for each connection attempt. Leave any existing VPN connection up, but don’t reconnect On Demand as long as this dictionary matches.	Yes
SSID match	A list of SSIDs to match against the current network. If the network isn’t a Wi-Fi network or if the SSID doesn’t appear in this list, the match fails. Omit this key and the corresponding list to match against any SSID.	No
URL string probe	A URL to probe. This rule matches when this URL is successfully fetched (returns a 200 HTTP status code) without redirection.	No

DNS settings

Setting	Description	Required
DNS search domains	The list of domain strings used to fully qualify single-label hostnames.	No
DNS server addresses	The list of DNS server IP address strings. These IP addresses can be a mix of IPv4 and IPv6 addresses.	Yes
Domain name	The primary domain of the tunnel.	No
Identity asset reference	The identifier of a credential asset declaration that contains the identity that the device uses to authenticate to the DNS resolver.	No
Supplemental match domains	The list of domain strings used to determine which DNS queries use the DNS resolver settings in DNS server addresses. The operating system uses this key to create a split DNS configuration where it resolves only hosts in certain domains using the tunnel’s DNS resolver. The operating system uses the default resolver for hosts that aren’t in one of the domains in this list. If Supplemental match domains contains the empty string it becomes the default domain. Split-tunnel configurations can direct all DNS queries to the VPN DNS servers before the primary DNS servers. If the VPN tunnel becomes the network’s default route, the servers listed in DNS server addresses become the default resolver and the operating system ignores the Supplemental match domains list.	No
Supplemental match domains no search	If turned on, the device doesn’t append the domains in the supplemental match domains list to the resolver’s list of search domains.	No

Proxy settings

Setting	Description	Required
Protocol	The dictionary to use to configure HTTP servers for Proxies for use with VPN. See the Protocol settings.	No
Proxy auto config enable	Turns on automatic proxy configuration.	No
Proxy auto discovery enable	Turns on proxy auto discovery.	No
Proxy server URL	The URL to the location of the proxy auto-configuration file.	No
Supplemental match domains	A list of domains that defines which hosts use proxy settings for hosts.	No

Protocol settings

Setting	Description	Required
Credentials asset reference	The identifier of an asset declaration that contains the credentials to authenticate with the proxy server.	No
HTTP protocol	The dictionary to use to configure the HTTP (non-TLS) server. See the HTTP protocol settings.	No
HTTPS protocol	The dictionary to use to configure the HTTPS (TLS) server. See the HTTPS protocol settings.	No

HTTP protocol settings

Setting	Description	Required
Enable HTTP	Turns on proxy for HTTP traffic.	No
HTTP hostname	The hostname of the HTTP proxy.	No
HTTP port	The port number of the HTTP proxy.	If the HTTP hostname is specified.

HTTPS protocol settings

Setting	Description	Required
Enable HTTPS	Turns on proxy for HTTPS traffic.	No
HTTPS hostname	The hostname of the HTTPS proxy.	No
HTTPS port	The port number of the HTTPS proxy.	If the HTTPS hostname is specified.

Note: Not all configurations and their settings are available in all device management services. Each device management service developer implements these settings differently. To learn which settings are available for your devices, consult your developer’s device management service documentation.

Helpful?

Apple Platform Deployment