Skip to main content

Admin Dashboard

Blocksi Filter - Mosyle iOS Configuration Guide

The following contains procedures for deploying Blocksi Filter (full URL + granular YouTube filtering solution) through Mosyle.

Mosyle delivers three components to each device:

  1. Blocksi Filter app - The filter itself.

  2. Blocksi certificate profile - Allows the filter to protect web traffic on the device.

  3. Per-app VPN profile - Turns on filtering for the built-in Safari browser and provides the connection that managed apps are attached to.

Prerequisites

Ensure the following prerequisites are in place before proceeding with deployment:

  • Administrator access to Mosyle.

  • Your Blocksi Super-Admin account email address.

  • Send your Organization ID and organization name to Blocksi Support to authorize your district's use of the Blocksi Filter app. Refer to the Getting Your Organization ID and Name section for more information.

  • Ensure that Custom Apps and the Volume Purchase Program (VPP) are fully enabled and configured. Refer to the Configuring Volume Purchasing section for more information.

  • Your Mosyle account is connected to Apple Business Manager or Apple School Manager.

  • Supervised iPads or iPhones running iOS 16 or later are enrolled in Mosyle through Apple School Manager or Apple Business Manager. A device group exists that contains the target devices.

  • A filtering policy must be created and configured on the Blocksi Admin Dashboard.

  • The Blocksi Filter app is assigned to the location that your MDM uses in Apple School Manager or Apple Business Manager, and has synced into Mosyle.

Getting Your Organization ID and Name
To get your organization ID and name:

  1. Sign in to your Apple School Manager account with your Administrator credentials.

  2. Click your account name in the lower left-hand corner, and then click Preferences from the pop-up menu.

  3. Go to Organization Information.

  4. Locate your Organization ID and Organization Name.

  5. Send this information to Blocksi. It is required to add your organization to the approved list of customers who can use Blocksi's filtering app.

Configuring Volume Purchasing
To download the service token:

  1. Sign in to your company's account at business.apple.com (Apple Business Manager) or school.apple.com (Apple School Manager).

  2. Click your account name in the top right corner, then click Settings from the drop-down menu.

  3. Click Payments and Billing.

  4. Under the Apps and Books tab, scroll to the Content Tokens section and click Download next to the correct server location token. The token is downloaded to the Downloads folder on your computer.

Uploading the Service Token
To upload the service token:

  1. In Mosyle, navigate to Management > Manage iOS / iPadOS / watchOS, then click Applications on the left and select Apple Apps and Books (VPP). The Apple Apps and Books page opens.

    Apple Apps and Books Page

  2. Click Add account and enter a name in the Account name text box.

    Upload VPP Token

  3. Click Select file and select the .vpptoken file that you downloaded.

    Tip

    To install free apps faster during Automated Device Enrollment, select YES, Pre-Assign App Licenses for Automated Device Enrollment Devices from the drop-down list, then click Select and choose the Automated Device Enrollment profiles.

  4. Click Save.

Configuring the Blocksi Filter App in Mosyle
To configure the Blocksi Filter app:

  1. In Mosyle, navigate to Management > Manage iOS / iPadOS / watchOS, then select Install App from the Management Profiles menu on the left.

    Install App Management Profiles

  2. Click Add new profile. The Install Apps panel opens to the right.

    Install Apps Side Panel

  3. Configure the following:

    • Profile Name - Enter Blocksi Filter App.

    • Installation source - Select the Apps and Books (VPP) location that the Blocksi Filter app is assigned to.

    • Assignment method - Select Device based - Assign licenses to device serial number.

    Install Apps Configuration

    Note

    Device-based assignment is recommended for shared, device-enrolled devices.

  4. Click Click to add an app. The Select the apps window opens.

    Select the Apps Window

  5. Select Blocksi Filter, then click the Checkmark Button button in the top right.

    Blocksi Filter Install Apps Configuration

    Note

    Blocksi Filter and the legacy Blocksi For iPad app can both appear in this list. Make sure that you select Blocksi Filter.

  6. Under Profile Assignment, click the Add Assignment Button button to open the Profile Assignment window and select your target devices.

    Note

    Note which devices you assign here. The Blocksi certificate profile and the per-app VPN profile must be assigned to the same devices.

    Add Profile Assignment Window

  7. Click Save.

Important

Wait until the app shows as installed on at least one test device before continuing. The profiles in the following sections refer to the network extension of the app, and filtering cannot start until the app is installed.

Uploading the Blocksi Certificate Profile

Download URLs

The relevant .mobileconfig file can be downloaded using the following link:

To upload the Blocksi certificate profile to Mosyle:

  1. In Mosyle, navigate to Management > Manage iOS / iPadOS / watchOS, then select Certificates/Custom Profiles from the Management Profiles menu on the left.

    Note

    If Certificates/Custom Profiles is not listed, click Activate New Profile Type and activate it.

    Certificates/Custom Profiles Page

  2. Click New. The configuration panel opens to the right.

    New Custom Profile Side Panel

  3. Configure the following:

    • Name - Enter Blocksi Certificate.

    • Configuration File - Click Select File and upload Blocksi_Filter_CA.mobileconfig.

    • Profile Assignment - Assign the profile to the same devices you assigned the Blocksi Filter app to.

    Blocksi Certificate Profile

  4. Click Save. The custom profile appears in the Certificates/Custom Profiles section and is enabled by default.

Note

On supervised devices, the certificate is trusted automatically, so it does not need to be enabled manually under Settings > General > About > Certificate Trust Settings.

Configuring Content Filtering

The per-app VPN profile is the working filtering configuration. It turns on filtering for the built-in Safari browser and creates the connection that managed apps are attached to. Configure the file with your Organization ID before you upload it to Mosyle.

Creating the Reference Profile

Mosyle can attach an app only to a profile created under VPN. Because the per-app VPN profile is uploaded as a custom profile, you create a reference profile under VPN for apps to attach to. The reference profile is never installed on devices. It only supplies the identifier that links the app to the connection that the per-app VPN profile delivers.

You need the reference profile only if you filter browsers other than Safari. Safari is filtered by the per-app VPN profile alone.

Important

Never assign the reference profile to devices. If you assign it, it installs alongside the working profile and browsing stops.

To create the reference profile:

  1. In Mosyle, navigate to Management > Manage iOS / iPadOS / watchOS, then select VPN from the Management Profiles menu on the left.

    VPN Page

  2. Click Add new profile. The configuration panel opens to the right.

    New VPN Profile Side Panel

  3. Configure the following:

    • Connection Name - Enter Blocksi per-app VPN (reference).

    • Connection Type - Select Custom SSL.

    • Identifier - Enter com.blocksi.filter.PacketTunnel.

    • Server - Enter 127.0.0.1.

    • Account and Password - Leave both empty. If your browser fills them in, clear them.

    Blocksi Per-App VPN (Reference) Profile

  4. Select Configure add-on App Layer VPN.

  5. In VPNUUID, replace the generated value with the following value, exactly:

    B10C5100-1A2B-4C3D-9E4F-0A1B2C3D4E5F

    Note

    If Mosyle does not accept this value, keep the value that Mosyle generated and enter that same value in the VPNUUID key of Blocksi_Filter_Mosyle.mobileconfig before you upload it.

    Blocksi Per-App VPN (Reference) Profile

  6. Leave Profile Assignment empty.

  7. Click Save. The custom profile appears in the VPN section and is enabled by default.

Configuring the Per-App VPN Profile

Download URLs

The relevant .mobileconfig file can be downloaded using the following link:

To configure the per-app VPN profile for user-based and blanket filtering:

  1. Download the Blocksi_Filter_Mosyle.mobileconfig file.

  2. Open the downloaded .mobileconfig file using any text or code editor.

  3. In the VendorConfig dict, configure the following keys:

    • organizationId - Replace admin@blocksi.net with your Blocksi Organization ID.

    • adminPassword - Leave the default value, or replace it with a password of your choice. This password protects access to the app details in the Blocksi Filter app.

    • userId - Leave the value set to %Email%. Mosyle replaces this variable with the email address of the assigned user.

    • snAnalytics - Leave the value unchanged. This key reports the serial number of the device for analytics only, and is separate from the serialNumber key used for serial number-based filtering.

    • useDhcpDns - Leave the value set to <true/>. The filter uses the DNS servers provided by your network and falls back to public DNS servers if none are available.

    Leave every other value unchanged.

    Default VendorConfig

  4. Save the file.

Note

The profile reports the assigned user of the device to Blocksi so that activity is attributed correctly. This requires the device to have a user assigned in Mosyle. Devices without an assigned user, such as shared devices, receive a blanket filtering policy instead.

(Optional) Configuring the Per-App VPN Profile for Serial Number-Based Filtering

By default, the profile identifies devices by their assigned user. Configure the profile as described in this section when you want the filter to identify devices by serial number instead, such as on shared devices without an assigned user.

To configure the per-app VPN profile for serial number-based filtering:

  1. Download the Blocksi_Filter_Mosyle.mobileconfig file.

  2. Open the downloaded .mobileconfig file using any text or code editor.

  3. In the VendorConfig dict, configure the following keys:

    • organizationId - Replace admin@blocksi.net with your Blocksi Organization ID.

    • adminPassword - Leave the default value, or replace it with a password of your choice. This password protects access to the app details in the Blocksi Filter app.

    • userId - Replace the key name with serialNumber, and replace the %Email% value with %SerialNumber%, so that the two lines read as follows:

      <key>serialNumber</key>
<string>%SerialNumber%</string>

    • snAnalytics - Leave the value unchanged. This key reports the serial number of the device for analytics only, and is separate from the serialNumber key used for serial number-based filtering.

    • useDhcpDns - Leave the value set to <true/>. The filter uses the DNS servers provided by your network and falls back to public DNS servers if none are available.

    Leave every other value unchanged.

    Important

    Enter %SerialNumber% exactly as shown, including both percent signs and the capitalization. Each MDM uses a different variable name, and Mosyle does not resolve the variable if the name does not match.

    Serial Number-Based VendorConfig

  4. Save the file.

Note

You must still select Enable Variables for this profile when you upload this profile, otherwise %SerialNumber% is sent to the device as literal text. Refer to the Uploading the Per-App VPN Profile to Mosyle section for more information.

(Optional) Configuring the Per-App VPN Profile for Custom DNS Servers

By default, the filter resolves DNS through the DNS servers that DHCP provides on your network. If DHCP does not provide DNS servers, or they do not respond, the filter falls back to built-in public DNS servers. Configure the profile as described in this section when you want the filter to use specific DNS servers instead. You can combine this configuration with the other optional configurations by editing the relevant keys in the same profile.

To configure the per-app VPN profile for custom DNS servers:

  1. Download the Blocksi_Filter_Mosyle.mobileconfig file.

  2. Open the downloaded .mobileconfig file using any text or code editor.

  3. In the VendorConfig dict, configure the following keys:

    • organizationId - Replace admin@blocksi.net with your Blocksi Organization ID.

    • adminPassword - Leave the default value, or replace it with a password of your choice. This password protects access to the app details in the Blocksi Filter app.

    • userId - Leave the value set to %Email%. Mosyle replaces this variable with the email address of the assigned user.

    • snAnalytics - Leave the value unchanged. This key reports the serial number of the device for analytics only, and is separate from the serialNumber key used for serial number-based filtering.

    • useDhcpDns - Leave the value set to <true/>. The filter uses the DNS servers provided by your network and falls back to public DNS servers if none are available.

    • dnsServers - Add the dnsServers key after the useDhcpDns key and enter your DNS server addresses as an array, in priority order, as shown in the following example. These servers are used instead of the DHCP DNS servers.

      <key>dnsServers</key>
<array>
   <string>10.0.0.53:5353</string>
   <string>[2001:db8::1]:5353</string>
</array>

    Leave every other value unchanged.

    Note

    Each dnsServers entry is an IPv4 or IPv6 address and can include a port. Enclose IPv6 addresses in square brackets when you add a port, as shown in the example.

    Custom DNS Servers VendorConfig

  4. Save the file.

(Optional) Configuring the Per-App VPN Profile for Captive Portal Detection

Configure the profile as described in this section when your network uses the captive portal of the Blocksi Appliance. Captive portal detection works only with the Blocksi Appliance, not with captive portals from other providers. When captive portal detection is turned on, the filter detects the Blocksi Appliance captive portal on the network and hands off DNS resolution to the Blocksi DNS-over-HTTPS (DoH) service. You can combine this configuration with the other optional configurations by editing the relevant keys in the same profile.

To configure the per-app VPN profile for captive portal detection:

  1. Download the Blocksi_Filter_Mosyle.mobileconfig file.

  2. Open the downloaded .mobileconfig file using any text or code editor.

  3. In the VendorConfig dict, configure the following keys:

    • organizationId - Replace admin@blocksi.net with your Blocksi Organization ID.

    • adminPassword - Leave the default value, or replace it with a password of your choice. This password protects access to the app details in the Blocksi Filter app.

    • userId - Leave the value set to %Email%. Mosyle replaces this variable with the email address of the assigned user.

    • snAnalytics - Leave the value unchanged. This key reports the serial number of the device for analytics only, and is separate from the serialNumber key used for serial number-based filtering.

    • useDhcpDns - Leave the value set to <true/>. The filter uses the DNS servers provided by your network and falls back to public DNS servers if none are available.

    Leave every other value unchanged.

  4. Add the following lines after the useDhcpDns key:

    <key>capPortalEnabled</key><true/>
<key>capPortalHost</key>
<string>capportal.blocksi.net</string>
<key>capPortalPort</key>
<integer>81</integer>
<key>capPortalDohUrl</key>
<string>https://capportal.blocksi.net/dns-query/normaldns</string>

    Enter the lines as shown. The capPortalDohUrl value is the recommended server URL for Blocksi Filter. Refer to the Choosing a Server URL section.

    Captive Portal VendorConfig

  5. Save the file.

Uploading the Per-App VPN Profile to Mosyle

Important

Upload the file as a custom profile. Rebuilding it in the Mosyle VPN editor produces a profile that Mosyle either refuses with a status of Removed by compatibility, or installs without filtering ever starting.

To upload the per-app VPN profile to Mosyle:

  1. In Mosyle, navigate to Management > Manage iOS / iPadOS / watchOS, then select Certificates/Custom Profiles from the Management Profiles menu on the left.

    Note

    If Certificates/Custom Profiles is not listed, click Activate New Profile Type and activate it.

    Certificates/Custom Profiles Page

  2. Click New. The configuration panel opens to the right.

    New Custom Profile Side Panel

  3. Configure the following:

    • Name - Enter Blocksi per-app VPN.

    • Configuration File - Click Select File and upload the .mobileconfig file you configured under the Configuring the Per-App VPN Profile section.

    • Profile Settings - Select Enable Variables for this profile. Without it, the user identifier is sent literally instead of being resolved.

    • Profile Assignment - Assign the profile to the same devices you assigned the Blocksi Filter app to.

    Blocksi Per-App VPN Profile

  4. Click Save. The custom profile appears in the Certificates/Custom Profiles section and is enabled by default.

Configuring Managed Apps for Filtering

Safari is covered by the per-app VPN profile and needs nothing further. Other browsers are filtered only if they are installed as managed apps through Mosyle and attached to the Blocksi Filter connection. Repeat the relevant procedure for each browser that you want filtered.

Important

The Blocksi per-app VPN (reference) profile appears in the VPNs Selector window only after you create it. Refer to the Creating the Reference Profile section.

Attaching the VPN to an Installed Managed App

If the browser is already deployed and managed by Mosyle, you do not need to add it again. Attach it to the Blocksi Filter connection instead.

To attach the Blocksi Filter connection to an already installed managed app:

  1. In Mosyle, navigate to Management > Manage iOS / iPadOS / watchOS, then select Install App from the Management Profiles menu on the left.

    Install App Management Profiles

  2. Click the name of the profile that installs the browser app to open the Install Apps panel.

    Google Chrome Install Apps Side Panel

  3. Hover over the app tile and click the Gear Button button. The Per-App Configuration window for the browser opens.

    Google Chrome Per-App Configuration Window

  4. Select Configure VPN from the drop-down list, then select the Activate this configuration checkbox.

    Google Chrome Per-App Configuration Window

  5. Under VPN Profile Selected, click Select. The VPNs Selector window opens.

  6. Select the Blocksi per-app VPN (reference) profile you previously created, then click the Checkmark Button button in the top right.

    VPNs Selector Window

  7. Clear the Assign this VPN profile to all devices that are assigned to this profile checkbox.

    Note

    The per-app VPN profile already delivers the working connection. Leaving this checkbox selected installs the reference profile as well and stops browsing.

    Configured Google Chrome Per-App Configuration Window

  8. Click Confirm, then click Save.

Note

The attachment is applied when the app is installed. If the app is already on the device, reinstall it from Mosyle so that the new setting takes effect.

Adding a Managed App and Attaching the VPN
To add a managed app and attach the Blocksi Filter connection:

  1. In Mosyle, navigate to Management > Manage iOS / iPadOS / watchOS, then select Install App from the Management Profiles menu on the left.

    Install App Management Profiles

  2. Click Add new profile. The Install Apps panel opens to the right.

  3. Configure the following:

    • Profile Name - Enter a name for the profile (e.g., Google Chrome).

    • Installation source - Select App Store.

    • Assignment method - Select Device based - Assign licenses to device serial number.

    Browser Install Apps Configuration

  4. Click Click to add an app. The Select the apps window opens.

    Select the Apps Window

  5. Search for the browser, select it, then click the Checkmark Button button in the top right.

    Selected Browser in the Select the Apps Window

  6. Hover over the app tile and click the Gear Button button. The Per-App Configuration window for the browser opens.

    Brave Browser Per-App Configuration Window

  7. Select Configure VPN from the drop-down list, then select the Activate this configuration checkbox.

    Brave Browser Per-App Configuration Window

  8. Under VPN Profile Selected, click Select. The VPNs Selector window opens.

  9. Select the Blocksi per-app VPN (reference) profile you previously created, then click the Checkmark Button button in the top right.

    VPNs Selector Window

  10. Clear the Assign this VPN profile to all devices that are assigned to this profile checkbox.

    Note

    The per-app VPN profile already delivers the working connection. Leaving this checkbox selected installs the reference profile as well and stops browsing.

    Configured Brave Browser Per-App Configuration Window

  11. Click Confirm.

  12. Under Profile Assignment, click the Add Assignment Button button to open the Profile Assignment window and select the same devices you assigned the Blocksi Filter app to.

  13. Click Save.

Validating the Deployment

To validate the deployment, verify that the app and profiles are installed on the target device and that filtering is working correctly.

To check whether the app and profiles are installed:

  • Open Settings on the target device and navigate to General > VPN & Device Management. The Blocksi certificate profile and the per-app VPN profile should both be listed. The reference profile must not appear.

    VPN & Device Management
To check whether filtering is working:

  1. Open Safari on the target device and navigate to a site that your policy allows. The site loads normally.

  2. Navigate to some sites that should be blocked by your policy.

  3. Verify that the Blocksi block page appears, with no certificate warning.

  4. Repeat both checks in each managed browser that you attached to the filter.

    Blocksi Access Denied Page
To check whether Mosyle reports the profiles as installed:

  • In Mosyle, navigate to Management > Devices > Commands Activity Log. There should be no failed commands for the target device.

To check whether the VPN is connected:

  1. Open Safari on the target device so that the filter activates.

  2. Open Settings on the target device and navigate to VPN > Blocksi Filter. The VPN shows a status of Connected.

    VPN Settings
    Blocksi Filter Settings
To check whether the app reports the organization and user:

  1. Open Safari on the target device so that the filter activates.

  2. Open the Blocksi Filter app. The app should report your organization and the assigned user. Until the filter activates, the app may report that no organization is configured.

Important

If the deployment does not behave as expected, refer to the Troubleshooting article.