VPP Notifications (Apple VPP API v2)

What

Starting from FileWave version 14.6.0 we added support for a new Apple API for App and Book Management within the Apple Volume Purchase Program. With FileWave 15.1.0 this API became the default. The main difference compared to the previous version is that the new API is asynchronous. When we send a request to create / update / retire users or associate / disassociate assets we get a unique event identifier in response, which we use in the scheduler task to retrieve the status of an asynchronous event. There are no visual changes in your environment, except that the new API is more reliable, and expandable.

When/Why

In short, the new VPP 2.0 protocol is better, but out of an abundance of caution, it was not enabled by default on FileWave version 14.6.0 through 15.0.1 but with FileWave 15.1.0 it will become the default.  

How

The new implementation was not yet turned on by default, until FileWave 15.1.0. To turn it on for prior releases you need to add a line to your /usr/local/filewave/django/filewave/settings_custom.py and after that restart server.

If you are a hosted customer you will have it enabled since your server was upgraded to 15.1.0 or beyond.

VPP_V2 = True

For troubleshooting it can be set to VPP_V2 = False to go back to the VPP v1 API. 

The next step must be done for every server no matter if you are hosted or not.

In FileWave Central to go to Preferences → VPP & DEP and if the Enable VPP Notifications item can be enabled then VPP 2.0 is active (14.7+ only). It will be greyed out otherwise, and the checkbox will not be selectable. You should check the box to Enable VPP Notifications as shown below.

Once you Enable VPP Notifications, you should click Synchronize on the same preference screen and if it is successful then VPP v2 Notifications are working. If you get an error 9720: The provided notification URL is not reachable, then Apple is unable to connect to your server.  Apple must be able to reach your FileWave server directly from their 17.0.0.0/8 network. 

Digging Deeper

Logging

If you enable it or are running a version of FileWave of 15.1.0 or newer, you can check filewave_django.log. Lines with 'Sync VPP v2' is the confirmation that the new API is activated.

Email Address

One important change in the new API is that when we create a user we need to specify an email address. For BYOD devices we are using Managed Apple ID, for DEP devices - Device Assigner Email (it is not available when option 'Create VPP users for newly enrolled devices' is checked), if before mentioned is not available, we use Organization Email Address, and as last resort - 'email.not.set@<your_mdm_host>'.

Reachable by Apple

By default, FileWave uses the following endpoint:

This endpoint needs to be reachable and valid from Apple services.
You need to make sure that the TSL certificate is trusted by Apple and that Apple services are not blocked by any networking rule.

Server Port refers to the port configured in Mobile Preferences, which is likely either 20445 or 20443:

https://{server_host}:{server_port}/api/vppv2/notification

If the FileWave Server is not accessible by Apple on the defined port, disable VPP Notifications, otherwise VPP will fail to work correctly.

If for security reasons or due to your network configuration, your FileWave server can't be reached by Apple services directly, it is possible to define a different URL that will be used by Apple. This can be done by editing the /usr/local/filewave/django/filewave/settings_custom.py file adding the below line and then restarting the server. For hosted customers, you will need support to set this for you.

settings.VPP_NOTIFICATIONS_CUSTOM_URL = "https://server:port/url"

Then you need to make sure requests to this endpoint are forwarded to your FileWave instance.