apple-device-management-mdm/mdm/profiles/com.apple.webcontent-filter.yaml

title: Web Content Filter
description: The payload that configures web content filters.
payload:
  payloadtype: com.apple.webcontent-filter
  supportedOS:
    iOS:
      introduced: '7.0'
      multiple: true
      supervised: false
      allowmanualinstall: true
      sharedipad:
        mode: allowed
        devicechannel: true
        userchannel: false
      userenrollment:
        mode: allowed
    macOS:
      introduced: '10.15'
      multiple: true
      devicechannel: true
      userchannel: false
      requiresdep: false
      userapprovedmdm: false
      allowmanualinstall: true
      userenrollment:
        mode: forbidden
    tvOS:
      introduced: n/a
    visionOS:
      introduced: '1.1'
      multiple: true
      supervised: false
      allowmanualinstall: true
      userenrollment:
        mode: allowed
    watchOS:
      introduced: n/a
  content: As of iOS 16.0 and visionOS 1.1, this can be installed on unsupervised
    devices and user enrollments if ContentFilterUUID is specified. Previously it
    could only be installed on supervised devices.
payloadkeys:
- key: FilterType
  title: FilterType
  supportedOS:
    iOS:
      introduced: '8.0'
  type: <string>
  presence: optional
  rangelist:
  - BuiltIn
  - Plugin
  default: BuiltIn
  content: The type of filter, built-in or plug-in. In macOS, the system only supports
    the plug-in value.
- key: SafariHistoryRetentionEnabled
  title: SafariHistoryRetentionEnabled
  supportedOS:
    iOS:
      introduced: '26.0'
      supervised: true
      userenrollment:
        mode: forbidden
    macOS:
      introduced: '26.0'
    visionOS:
      introduced: '26.0'
      supervised: true
      userenrollment:
        mode: forbidden
  type: <boolean>
  presence: optional
  default: true
  content: If `true`, this payload enforces a policy which requires retention of browsing
    history. This causes Safari to disable clearing of browsing history, and prevents
    the use of private browsing mode because that mode doesn't keep browsing history.
- key: AutoFilterEnabled
  title: Web filter enabled
  supportedOS:
    macOS:
      introduced: n/a
  type: <boolean>
  presence: optional
  default: false
  content: If `true`, the system enables automatic filtering. Use when `FilterType`
    is `BuiltIn`.
- key: PermittedURLs
  title: PermittedURLs
  supportedOS:
    macOS:
      introduced: n/a
  type: <array>
  presence: optional
  content: An array or URLs that are accessible whether or not the automatic filter
    allows access. Use when `FilterType` is `BuiltIn`. Requires that `AutoFilterEnabled`
    is `true`.
  subkeys:
  - key: PermittedURLItems
    title: Permitted url items
    type: <string>
- key: BlacklistedURLs
  title: BlacklistedURLs
  supportedOS:
    iOS:
      deprecated: '14.5'
    macOS:
      introduced: n/a
    visionOS:
      introduced: n/a
  type: <array>
  presence: optional
  content: Use `DenyListURLs` instead.
  subkeys:
  - key: BlacklistedURLItems
    title: Blacklisted url items
    type: <string>
- key: DenyListURLs
  title: DenyListURLs
  supportedOS:
    iOS:
      introduced: '14.5'
    macOS:
      introduced: n/a
  type: <array>
  presence: optional
  content: An array of URLs that are inaccessible. Use when `FilterType` is `BuiltIn`.
    Limit the number of these URLs to no more than 500.
  subkeys:
  - key: DenyListURLItems
    title: Denylisted url items
    type: <string>
- key: HideDenyListURLs
  title: HideDenyListURLs
  supportedOS:
    iOS:
      introduced: '18.0'
    macOS:
      introduced: n/a
    visionOS:
      introduced: '2.0'
  type: <boolean>
  presence: optional
  default: false
  content: If `true`, the device hides the `DenyListURLs` item in the profiles that
    display in Settings > General > VPN & Device Management.
- key: WhitelistedBookmarks
  title: White list
  supportedOS:
    iOS:
      deprecated: '14.5'
    macOS:
      introduced: n/a
    visionOS:
      introduced: n/a
  type: <array>
  presence: optional
  content: Use `AllowListBookmarks` instead.
  subkeys:
  - key: WhitelistedBookmarksItem
    title: Identifier
    type: <dictionary>
    subkeys:
    - key: URL
      title: URL
      type: <string>
      presence: required
      content: The URL of the bookmark in the allow list.
    - key: Title
      title: Title
      type: <string>
      presence: required
      content: The title of the bookmark.
- key: AllowListBookmarks
  title: Allow list
  supportedOS:
    iOS:
      introduced: '14.5'
    macOS:
      introduced: n/a
  type: <array>
  presence: optional
  content: An array of dictionaries that define the pages that the user can bookmark
    or visit. Use when `FilterType` is `BuiltIn`.
  subkeys:
  - key: AllowListBookmarksItem
    title: Identifier
    type: <dictionary>
    subkeys:
    - key: URL
      title: URL
      type: <string>
      presence: required
      content: The URL of the bookmark in the allow list.
    - key: Title
      title: Title
      type: <string>
      presence: required
      content: The title of the bookmark.
- key: UserDefinedName
  title: UserDefinedName
  type: <string>
  presence: optional
  content: The display name for this filtering configuration. Required when `FilterType`
    is `Plugin`.
- key: PluginBundleID
  title: PluginBundleID
  type: <string>
  presence: optional
  content: The bundle ID of the plug-in that provides filtering service. Required
    when `FilterType` is `Plugin`. Otherwise, it ignores this value. Consult your
    filtering solution vendor to determine what to specify for this value. Required
    when `FilterType` is `Plugin`.
- key: ServerAddress
  title: ServerAddress
  type: <string>
  presence: optional
  content: The server address, which may be the IP address, hostname, or URL. Use
    when `FilterType` is `Plugin`.
- key: UserName
  title: Username
  type: <string>
  presence: optional
  content: The user name for the service. Use when `FilterType` is `Plugin`.
- key: Password
  title: Password
  type: <string>
  presence: optional
  content: The password for the service. Use when `FilterType` is `Plugin`.
- key: PayloadCertificateUUID
  title: Certificate UUID
  type: <string>
  presence: optional
  format: ^[0-9A-Za-z]{8}-[0-9A-Za-z]{4}-[0-9A-Za-z]{4}-[0-9A-Za-z]{4}-[0-9A-Za-z]{12}$
  content: The UUID of the certificate payload within the same profile that the system
    uses to authenticate the user. Use when `FilterType` is `Plugin`.
- key: Organization
  title: Organization
  type: <string>
  presence: optional
  content: The organization string to pass to the third-party plug-in. Use when `FilterType`
    is `Plugin`.
- key: VendorConfig
  type: <dictionary>
  presence: optional
  content: The custom dictionary that the filtering service plug-in needs. Use when
    `FilterType` is `Plugin`.
  subkeys:
  - key: ANY
    type: <any>
    presence: required
    content: The custom key/value pairs for the filtering service.
- key: FilterBrowsers
  title: FilterBrowsers
  supportedOS:
    macOS:
      introduced: n/a
  type: <boolean>
  presence: optional
  default: false
  content: |-
    If `true`, the system enables filtering WebKit traffic. Use when `FilterType` is `Plugin`.

    > Note:
    > At least one of `FilterBrowsers` or `FilterSockets` needs to be `true`.
- key: FilterSockets
  title: FilterSockets
  type: <boolean>
  presence: optional
  default: false
  content: |-
    If `true`, enables the filtering of socket traffic. Use when `FilterType` is `Plugin`.

    > Note:
    > At least one of `FilterBrowsers` or `FilterSockets` needs to be `true`.
- key: FilterDataProviderDesignatedRequirement
  title: Filter data provider designated requirement
  supportedOS:
    iOS:
      introduced: n/a
    visionOS:
      introduced: n/a
  type: <string>
  presence: optional
  content: The designated requirement string that the system embeds in the code signature
    of the filter data provider system extension. This string identifies the filter
    data provider when the filter starts running. Required if `FilterSockets` is `true`.
- key: FilterDataProviderBundleIdentifier
  title: Filter data provider bundle identifier
  type: <string>
  presence: optional
  content: The bundle identifier string of the filter data provider system extension.
    This string identifies the filter data provider when the filter starts running.
    Required if `FilterSockets` is `true`.
- key: FilterPackets
  title: Filter network packets
  supportedOS:
    iOS:
      introduced: n/a
    macOS:
      introduced: '10.15'
    visionOS:
      introduced: n/a
  type: <boolean>
  presence: optional
  default: false
  content: |-
    If `true` and `FilterType` is `Plugin`, the system enables filtering network packets. Use when `FilterType` is `Plugin`.

    > Note:
    > At least one of `FilterPackets` or `FilterSockets` needs to be `true`.
- key: FilterPacketProviderDesignatedRequirement
  title: Filter packet provider designated requirement
  supportedOS:
    iOS:
      introduced: n/a
    macOS:
      introduced: '10.15'
    visionOS:
      introduced: n/a
  type: <string>
  presence: optional
  content: The designated requirement string that the system embeds in the code signature
    of the filter packet provider system extension. This string identifies the filter
    packet provider when the filter starts running. Required if `FilterPackets` is
    `true`.
- key: FilterPacketProviderBundleIdentifier
  title: Filter packet provider bundle identifier
  supportedOS:
    iOS:
      introduced: n/a
    macOS:
      introduced: '10.15'
    visionOS:
      introduced: n/a
  type: <string>
  presence: optional
  content: The bundle identifier string of the filter packet provider system extension.
    This string identifies the filter packet provider when the filter starts running.
    Required if `FilterPackets` is `true`.
- key: FilterGrade
  title: Filter grade
  supportedOS:
    iOS:
      introduced: n/a
    macOS:
      introduced: '10.15'
    visionOS:
      introduced: n/a
  type: <string>
  presence: optional
  rangelist:
  - firewall
  - inspector
  default: firewall
  content: The system uses this value to derive the relative order of content filters.
    Filters with a grade of `firewall` see network traffic before filters with a grade
    of `inspector`. However, the system doesn't define the order of filters within
    a grade.
- key: ContentFilterUUID
  title: Content filter UUID
  supportedOS:
    iOS:
      introduced: '16.0'
    macOS:
      introduced: n/a
  type: <string>
  presence: optional
  content: A globally unique identifier for this content filter configuration. The
    content filter processes network traffic for managed apps with the same `ContentFilterUUID`
    in their app attributes. Use when `FilterType` is `Plugin`.This key must be present
    for unsupervised devices and user enrollment.
- key: FilterURLs
  title: FilterURLs
  supportedOS:
    iOS:
      introduced: '26.0'
    macOS:
      introduced: '26.0'
    visionOS:
      introduced: n/a
  type: <boolean>
  presence: optional
  default: false
  content: If `true`, the system filters URL requests. Use when `FilterType` is `Plugin`.
- key: URLFilterParameters
  supportedOS:
    iOS:
      introduced: '26.0'
    macOS:
      introduced: '26.0'
    visionOS:
      introduced: n/a
  type: <dictionary>
  presence: optional
  content: A dictionary containing URL filter parameters. Required when `FilterURLs`
    is `true`.
  subkeys:
  - key: URLFilterControlProviderDesignatedRequirement
    title: URL filter control provider designated requirement
    type: <string>
    presence: optional
    content: The designated requirement string in the code signature of the URL filter
      control provider app extension. The system uses this string to identify the
      URL filter control provider when the filter starts running. Required in macOS.
  - key: URLFilterControlProviderBundleIdentifier
    title: URL filter control provider bundle identifier
    type: <string>
    presence: required
    content: The bundle identifier string of the URL filter control provider app extension.
      The system uses this string to identify the URL filter control provider when
      the filter starts running.
  - key: PIRServerURL
    title: Private information retrieval server URL
    type: <string>
    presence: required
    content: The URL containing the domain name of the private information retrieval
      server.
  - key: PIRPrivacyPassIssuerURL
    title: Privacy pass issuer URL
    type: <string>
    presence: required
    content: The URL containing the domain name of Privacy Pass Issuer.
  - key: PIRAuthenticationToken
    title: Authentication token
    type: <string>
    presence: required
    content: The per-user authentication token string, which is an HTTP bearer token
      for the person using your app. The system uses this token to attest that it
      is a valid user when requesting anonymous authentication tokens for PIR exchanges.
  - key: URLFilterFailClosed
    title: URLFilterFailClosed
    type: <boolean>
    presence: optional
    default: false
    content: If `true`, the system blocks URLs if the filter is enabled, but it fails
      to make any filtering decision; for example, if there's a communication failure
      with the PIR server. If `false`, the system allows URLs if the filter is enabled,
      but it fails to make any filtering decision.
  - key: URLPrefilterFetchFrequency
    title: URLPrefilterFetchFrequency
    type: <integer>
    presence: optional
    range:
      min: 2700
    default: 86400
    content: The time interval in seconds that the system uses to periodically run
      the `NEURLFilterControlProvider` app extension. The default value is 86400 seconds
      (1 day). The minimum allowed value is 2700 seconds (45 minutes). The system
      allows `NEURLFilterControlProvider` implementations to download prefilter Bloom
      filter data onto the device periodically at the specified interval. Implementations
      need to allow for a slight difference between the scheduled time and the actual
      runtime of the task, due to the scheduling mechanism on the system.
notes:
- title: ''
  content: |-
    The system matches URLs using string-based matching. A URL matches an allow list, deny list, or permitted list pattern if the exact characters of the pattern appear as a substring of the URL requested in the web browser. For example, if the system doesn't allow `test.com/a`, it blocks `test.com/a`, `test.com/apple`, and `test.com/a/b`.

    The system matches list entries that terminate with a `/` character explicitly; if the system blocks or allows `test.com/a/`, it blocks or allows `test.com/a` and `test.com/a/b`.

    Matching discards a `www` subdomain prefix if present, so if the system doesn't allow `www.test.com`, it also blocks `m.test.com`.

    All filtering options are active simultaneously. The system only permits URLs and sites that pass all rules.
examples:
- title: Profile example
  files:
  - file: examples/mdm/profiles/com.apple.webcontent-filter/example1.plist