We’ve been using App Center (former HockeyApp, which got retired and replaced by App Center) for distributing our iOS applications within the company. And when we learned about a year ago that App Center also is going to be retired on 2025-03-31, we started looking at alternatives. Having found none that would be good enough, we decided to implement our own.

Installing an iOS application from a website

Since we already had a .NET/MVC-based website for distribution-related stuff, we added this functionality there, and that turned out to be a rather trivial task. The .NET/MVC has nothing to do with it really - that’s just what we had, and you’ll see for yourself that this can be done with any other framework or even with a bare static website.

I should have published this article much earlier before the App Center retirement date, and I was intending too, but I just never found time, sorry about that.

Why would one need App Center or a similar service

Because fucking Apple didn’t make it simple to distribute iOS applications. You cannot just place an .ipa binary on your website, so users could download and install it.

Well, actually, you can, and that is what this article is about, but more on that a bit later. For now, assuming that it’s all black magic to you and that you don’t want to touch App Store / TestFlight with a 100 meters long pole, the only possibility one might have is to use a special service that could host .ipa binaries and perform required voodoo passes to make them installable on users devices. And App Center is one of such services. Was.

To clarify, here I am talking about distributing “internal” iOS applications within a company, so this is not about publishing applications for general public - for that, I imagine, you would still need to submerge yourself into the great marsh of App Store / TestFlight things, so if that is your case, then this article will likely be of no use for you.

Alternatives

Having announced the retirement of App Center, Microsoft suggested App Store and TestFlight as alternatives, but we were using (HockeyApp and then) App Center exactly because we did not want to deal with App Store and TestFlight, so that suggestion wasn’t helpful at all.

We did find some other alternatives (the list is sorted chronologically - when we discovered those services, starting from oldest):

but neither of them looked like an improvement over App Center. If anything, they look considerably more complicated to deal with than App Center. And there probably is some pricing involved too (App Center was free of charge).

If I was forced to choose from this list, I’d probably go with Buildstash, but for our single need of simply distributing iOS applications their lots of other functionality would be a total overkill.

There is actually one more alternative - DistApp - which seems to be providing exactly that one functionality that we need, but by the moment we saw that service, we already had implemented our own solution.

App Center itself wasn’t great either

We actually started slowly looking for an alternative to App Center at least a couple of years ago, so way before its retirement was announced, as over time we eventually came to realization that for us App Center was quite an inconvenient way of distributing applications. Namely, because of:

  • the process of downloading/installing the applications was so not intuitive to users, we had to create a step-by-step tutorial (even a video) for that;
  • at some point it became impossible to create a new account with a bare e-mail, and they started to force users into using one of the OAuth providers;
  • not very well-defined access management:
    • applications can have users;
    • but there are also distribution groups, which also can have users;
    • at the same time, every version of the same application can have different distribution groups;
    • it is quite difficult to keep track of all that and have an overview of who has access to what.

Out of those the worst was the access management. Aside from the already listed points, there was one other issue - despite the fact that App Center belongs to Microsoft and even provides a SAML SSO login, and that it even has an option to “integrate” with Azure AD - none of that provides any means for access management (or anything useful, really). For example, every time there was a new user who needed to be granted access to an application, administrator needed to do that manually - that scales very poorly.

A related request was reported in their repository back in 2019, but got no development whatsoever over all these years.

So we weren’t happy with App Center, but we were tolerating it, as the service was provided free of charge and it worked quite well for the essential part of distributing iOS applications. But now has come the time to find something else.

How is it even possible to distribute iOS applications without App Store

But how is it even possible to distribute iOS applications without App Store / TestFlight? Did (HockeyApp and) App Center do something shady?

As we learned (should’ve googled that years ago), there is nothing shady about it - that is a very official feature, which meant to be used exactly for distributing internal applications via one’s own website. You just need to know about it.

In short, all that is required (aside from having Apple Developer (Enterprise?) account) is:

  • a particular manifest.plist file;
  • a URI with itms-services:// scheme.

The “Enterprise” part I am not sure about, and in general my knowledge about these Apple certificates/profiles/things is very, very vague. You certainly(?) do need to have an Apple Developer account (99 USD per year?), but from my understanding that needs to be not just a “regular” account but one that belongs to Apple Developer Enterprise Program (299 USD per year?). From what I read in the eligibility requirements, our company does not qualify to have that, and yet it seems that we do have it somehow. I really cannot say for sure and I have no idea where to check this.

But assuming that your company has all the required memberships/certificates/whatever, the technical details are the following.

Building the application

Speaking about fucking Apple not making things simple, before you can build your application you need to prepare quite a lot of things, which include getting signing/distribution certificates, provisioning profiles and god knows what else.

The entire procedure is so convoluted that I won’t be able to reproduce it even having done everything just 5 minutes ago. I am not even sure that the links that I provided are the correct ones. We even have a special “iOS guy” in the team, and he is the only one who knows how to set things up. On a good day.

When you have all the signing-related things in order, then you can produce an .ipa binary like this:

$ cd /path/to/your/application/project/

# our applications Xcode projects are generated with CMake (as they are cross-platform),
# so you can skip this step
$ mkdir build && cd $_
$ cmake -G Xcode ..

$ xcodebuild \
    -scheme SomeApplication archive \
    -archivePath SomeApplication.xcarchive \
    -allowProvisioningUpdates \
    -destination "generic/platform=iOS"

$ xcodebuild \
    -exportArchive \
    -exportPath ./ipa \
    -archivePath "SomeApplication.xcarchive" \
    -exportOptionsPlist ../export-options.plist \
    -allowProvisioningUpdates

where export-options.plist contains the following:

<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>method</key>
    <string>enterprise</string>
    <key>teamID</key>
    <string>SOME-ID-HERE</string>
</dict>
</plist>

As a result you will have a SomeApplication.ipa file, which you will need to upload to your server. Nothing special about that procedure, just a regular file upload via SFTP or whatever you use for that. Although you will probably also want to protect that file with authentication/authorization, but more on that later.

The manifest.plist

Next thing you need is a special manifest.plist file. For example, if the application name is LidarScanner, then manifest.plist will have the following contents:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>items</key>
    <array>
        <dict>
            <key>assets</key>
            <array>
                <dict>
                    <key>kind</key>
                    <string>software-package</string>
                    <key>url</key>
                    <string>https://your.company.com/downloads/lidar-scanner.ipa</string>
                </dict>
                <dict>
                    <key>kind</key>
                    <string>display-image</string>
                    <key>url</key>
                    <string>https://your.company.com/favicon-32x32.png</string>
                </dict>
                <dict>
                    <key>kind</key>
                    <string>full-size-image</string>
                    <key>url</key>
                    <string>https://your.company.com/favicon-256x256.png</string>
                </dict>
            </array>
            <key>metadata</key>
            <dict>
                <key>bundle-identifier</key>
                <string>com.company.LidarScanner</string>
                <key>bundle-version</key>
                <string>1.0</string>
                <key>kind</key>
                <string>software</string>
                <key>platform-identifier</key>
                <string>com.apple.platform.iphoneos</string>
                <key>title</key>
                <string>LidarScanner</string>
            </dict>
        </dict>
    </array>
</dict>
</plist>

For this to work you will need to upload the lidar-scanner.ipa binary and this manifest.plist file to /downloads/ path in your website root directory on the server. Actually, manifest.plist can be placed anywhere (and it doesn’t even have to be a “physical” file), but the location of lidar-scanner.ipa should match the one specified in the <string> value for that software-package section in the manifest.

One more requirement is that the *.ipa URL must be with HTTPS, and the certificate needs to be trusted on the installing device (so you might have some troubles if your SSL/TLS certificate is self-signed).

The itms-services URI

The last thing to do is adding this link anywhere on your website:

itms-services://?action=download-manifest&url=https://your.company.com/downloads/manifest.plist

So on a HTML page it would be something like this:

<a href="itms-services://?action=download-manifest&url=https://your.company.com/downloads/manifest.plist">
    Install iOS application
</a>

Here it assumes that the manifest.plist file is located at the /downloads/ path in your website root directory on the server. If you placed it elsewhere, then obviously you’ll need to adjust that link. And similar to the .ipa URL, it most likely also needs to be with HTTPS (and trusted SSL/TLS certificate).

Now, once you click on that link in Safari web-browser on one of your iOS devices, the following modal dialog should appear:

Modal dialog for installing an iOS application from a website

and after you click Install, the application will start downloading/installing on your iPhone/iPad.

This is it, that’s the whole magic - just a manifest.plist file and a itms-services:// link.

Caveats and other Apple specifics

It was never Apple’s intention to make developers life easier, so be prepared for various caveats, nuances and limitations.

Authentication/authorization

You most likely do not want your applications to be available to anyone on the internet, so there definitely should be some authentication on your website (unless it’s an internal in-house website, but even then it should probably still have authentication in place). Having said that, the next thing I’ll say is that actually your applications kind of will be available to anyone on the internet!

When I was investigating how the downloads from App Center work, I discovered that the *.ipa files were in fact available for downloading without authentication. In reality it is not as scary as it sounds, because the generated download URLs look like this:

https://appcenter-filemanagement-distrib2ede6f06e.azureedge.net/dlz9e271-7016-61va-9640-ac0b1k457der/SomeApplication.ipa?sv=2025-02-01&sr=c&sig=YPKVqmfXpecBzveG1nWDPnd4Lh37XM%2F2pLM6D0GWX%2Bg%3D&se=2025-03-20T15%3A05%3A50Z&sp=r&download_origin=appcenter

so it won’t be trivial to guess that long GUID, which probably can count as a kind of “credentials”. Moreover, these URLs have an expiration time, so eventually they will expire and will be returning 403.

But while the URL was still valid, I tested the download from a different device in a private browser tab (where I was not authenticated on App Center), and I also tried it with a bare cURL from a desktop PC, even with a different internet provider (to make sure that I have a different IP address), and it still succeeded:

$ curl -sI 'https://appcenter-filemanagement-distrib2ede6f06e.azureedge.net/dlz9e271-7016-61va-9640-ac0b1k457der/SomeApplication.ipa?sv=2025-02-01&sr=c&sig=YPKVqmfXpecBzveG1nWDPnd4Lh37XM%2F2pLM6D0GWX%2Bg%3D&se=2025-03-20T15%3A05%3A50Z&sp=r&download_origin=appcenter' \
    -H 'User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:124.0) Gecko/20100101 Firefox/124.0' \
    -H 'Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.5' \
    -H 'Accept-Encoding: gzip, deflate, br' \
    -H 'DNT: 1' \
    -H 'Connection: keep-alive' \
    | grep -i Content-Length \
    | awk '{print $2/1024/1024 " MB"}'
10.5228 MB

As you can see, it is indeed available with no authentication. So if the generated URL is somehow known/leaked and has not expired yet, then anyone on the internet can download the application.

But why is it so? Did App Center people do something wrong? Because Apple’s documentation says:

Make sure that users are authenticated and that the website is accessible from your intranet or the internet, depending on your needs.

[...]

Upload these items to an area of your website that your authenticated users can access:

  • The manifest file (with a .plist filename extension)
  • The app file (with a .ipa filename extension)

…so authentication is explicitly mentioned there. But it turned out to be a goddamn lie (or at least it is for some authentication methods/schemas?), as actually both the manifest.plist and the *.ipa file have to be available without authentication.

I don’t know why, and at first I thought that this is because Apple needs to query stuff on the website from their servers, but there were no requests from Apple IP addresses in my web server logs (there were only requests from my iOS devices). So then my next guess is that it’s iOS internals who needs to query stuff on the website, and those requests apparently are happening outside of the authenticated Safari session(?), so they are quite naturally failing.

Specifically, below you can take a look at NGINX logs for requests from my iOS device when I was trying to download an application from our website.

Both routes are protected

When the manifest.plist route is protected with authentication/authorization:

MY-IOS-DEVICE-IP-ADDRESS - - [02/Feb/2025:14:37:02 +0100] "GET /files/applications/lidar-scanner/v1.3.42/manifest.plist HTTP/1.1" 302 0 "https://your.company.com/applications/lidar-scanner" "Mozilla/5.0 (iPhone; CPU iPhone OS 18_3 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.3 Mobile/15E148 Safari/604.1"
MY-IOS-DEVICE-IP-ADDRESS - - [02/Feb/2025:14:37:04 +0100] "GET /downloads/applications/lidar-scanner/v1.3.42/ipa/694277a0-a42c-4f83-a8e9-f74207d217d1/manifest.plist HTTP/1.1" 302 0 "-" "com.apple.appstored/1.0 iOS/18.3 model/iPhone16,2 hwp/t8130 build/22D63 (6; dt:311) AMS/1"
MY-IOS-DEVICE-IP-ADDRESS - - [02/Feb/2025:14:37:04 +0100] "GET /Account/Login?ReturnUrl=%2Fdownloads%2Fapplications%2Flidar-scanner%2Fv1.3.42%2Fipa%2F694277a0-a42c-4f83-a8e9-f74207d217d1%2Fmanifest.plist HTTP/1.1" 200 1581 "-" "com.apple.appstored/1.0 iOS/18.3 model/iPhone16,2 hwp/t8130 build/22D63 (6; dt:311) AMS/1"

then it doesn’t even get to the *.ipa route, which is also protected with authentication/authorization, but it didn’t matter in this case, as it failed already on getting the manifest.plist and got redirected to the login route, which results in nothing, as these requests are happening behind the scenes (so user gets no prompts).

Only the application file route is protected

Then I removed authentication/authorization requirement from the manifest.plist route but kept it for the *.ipa route, and for that scenario I got the following logs:

MY-IOS-DEVICE-IP-ADDRESS - - [02/Feb/2025:14:40:21 +0100] "GET /files/applications/lidar-scanner/v1.3.42/manifest.plist HTTP/1.1" 302 0 "https://your.company.com/applications/lidar-scanner" "Mozilla/5.0 (iPhone; CPU iPhone OS 18_3 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.3 Mobile/15E148 Safari/604.1"
MY-IOS-DEVICE-IP-ADDRESS - - [02/Feb/2025:14:40:21 +0100] "GET /downloads/applications/lidar-scanner/v1.3.42/ipa/694277a0-a42c-4f83-a8e9-f74207d217d1/manifest.plist HTTP/1.1" 200 496 "-" "com.apple.appstored/1.0 iOS/18.3 model/iPhone16,2 hwp/t8130 build/22D63 (6; dt:311) AMS/1"
MY-IOS-DEVICE-IP-ADDRESS - - [02/Feb/2025:14:40:23 +0100] "HEAD /downloads/applications/lidar-scanner/v1.3.42/ipa/694277a0-a42c-4f83-a8e9-f74207d217d1 HTTP/1.1" 302 0 "-" "com.apple.appstored/1.0 iOS/18.3 model/iPhone16,2 hwp/t8130 build/22D63 (6; dt:311) AMS/1"
MY-IOS-DEVICE-IP-ADDRESS - - [02/Feb/2025:14:40:23 +0100] "HEAD /Account/Login?ReturnUrl=%2Fdownloads%2Fapplications%2Flidar-scanner%2Fv1.3.42%2Fipa%2F694277a0-a42c-4f83-a8e9-f74207d217d1 HTTP/1.1" 405 0 "-" "com.apple.appstored/1.0 iOS/18.3 model/iPhone16,2 hwp/t8130 build/22D63 (6; dt:311) AMS/1"
MY-IOS-DEVICE-IP-ADDRESS - - [02/Feb/2025:14:40:23 +0100] "GET /favicon-32x32.png HTTP/1.1" 200 2004 "-" "com.apple.appstored/1.0 iOS/18.3 model/iPhone16,2 hwp/t8130 build/22D63 (6; dt:311) AMS/1"
MY-IOS-DEVICE-IP-ADDRESS - - [02/Feb/2025:14:40:23 +0100] "GET /favicon-32x32.png HTTP/1.1" 200 2004 "-" "com.apple.appstored/1.0 iOS/18.3 model/iPhone16,2 hwp/t8130 build/22D63 (6; dt:311) AMS/1"
MY-IOS-DEVICE-IP-ADDRESS - - [02/Feb/2025:14:40:23 +0100] "HEAD /downloads/applications/lidar-scanner/v1.3.42/ipa/694277a0-a42c-4f83-a8e9-f74207d217d1 HTTP/1.1" 302 0 "-" "com.apple.appstored/1.0 iOS/18.3 model/iPhone16,2 hwp/t8130 build/22D63 (6; dt:311) AMS/1"
MY-IOS-DEVICE-IP-ADDRESS - - [02/Feb/2025:14:40:23 +0100] "HEAD /Account/Login?ReturnUrl=%2Fdownloads%2Fapplications%2Flidar-scanner%2Fv1.3.42%2Fipa%2F694277a0-a42c-4f83-a8e9-f74207d217d1 HTTP/1.1" 405 0 "-" "com.apple.appstored/1.0 iOS/18.3 model/iPhone16,2 hwp/t8130 build/22D63 (6; dt:311) AMS/1"
MY-IOS-DEVICE-IP-ADDRESS - - [02/Feb/2025:14:40:23 +0100] "GET /downloads/applications/lidar-scanner/v1.3.42/ipa/694277a0-a42c-4f83-a8e9-f74207d217d1 HTTP/1.1" 302 0 "-" "com.apple.appstored/1.0 iOS/18.3 model/iPhone16,2 hwp/t8130 build/22D63 (6; dt:311) AMS/1"
MY-IOS-DEVICE-IP-ADDRESS - - [02/Feb/2025:14:40:23 +0100] "GET /Account/Login?ReturnUrl=%2Fdownloads%2Fapplications%2Flidar-scanner%2Fv1.3.42%2Fipa%2F694277a0-a42c-4f83-a8e9-f74207d217d1 HTTP/1.1" 200 1565 "-" "com.apple.appstored/1.0 iOS/18.3 model/iPhone16,2 hwp/t8130 build/22D63 (6; dt:311) AMS/1"

So this time it:

  1. Succeeded with the manifest.plist route, as it is now available for unauthenticated requests;
  2. Tried to query the *.ipa route with HEAD, which failed the same way and again got redirected to the login route (and then failed there with 405, because that route doesn’t allow HEAD requests in our backend);
  3. However, it didn’t stop there, as then it fetched one of the images specified in the manifest (twice, for some reason);
  4. Then it tried to send the same HEAD request again, with the same unsuccessful result, and apparently it still didn’t matter;
    • so what is the point of those HEAD requests, if their (double) failure does not interrupt the process?
  5. And then seemingly it actually did try to GET the application’s *.ipa file, but that also resulted in a redirect to the login route, where it finally halted.

On the iOS device though I got the application icon, but with a cloud symbol in front of the title, and trying to open it I got this useless error message:

Description

Both routes are not protected

And only when I removed the authentication/authorization requirement from both the manifest.plist and the *.ipa routes, then everything succeeded (but still queried the same image twice, for some reason):

MY-IOS-DEVICE-IP-ADDRESS - - [02/Feb/2025:15:15:28 +0100] "GET /files/applications/lidar-scanner/v1.3.42/manifest.plist HTTP/1.1" 302 0 "https://your.company.com/applications/lidar-scanner" "Mozilla/5.0 (iPhone; CPU iPhone OS 18_3 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.3 Mobile/15E148 Safari/604.1"
MY-IOS-DEVICE-IP-ADDRESS - - [02/Feb/2025:15:15:28 +0100] "GET /downloads/applications/lidar-scanner/v1.3.42/ipa/97707e38-079e-4844-9cbf-67cf3c4584c1/manifest.plist HTTP/1.1" 200 497 "-" "com.apple.appstored/1.0 iOS/18.3 model/iPhone16,2 hwp/t8130 build/22D63 (6; dt:311) AMS/1"
MY-IOS-DEVICE-IP-ADDRESS - - [02/Feb/2025:15:15:31 +0100] "HEAD /downloads/applications/lidar-scanner/v1.3.42/ipa/97707e38-079e-4844-9cbf-67cf3c4584c1 HTTP/1.1" 200 0 "-" "com.apple.appstored/1.0 iOS/18.3 model/iPhone16,2 hwp/t8130 build/22D63 (6; dt:311) AMS/1"
MY-IOS-DEVICE-IP-ADDRESS - - [02/Feb/2025:15:15:31 +0100] "GET /favicon-32x32.png HTTP/1.1" 200 2004 "-" "com.apple.appstored/1.0 iOS/18.3 model/iPhone16,2 hwp/t8130 build/22D63 (6; dt:311) AMS/1"
MY-IOS-DEVICE-IP-ADDRESS - - [02/Feb/2025:15:15:31 +0100] "GET /favicon-32x32.png HTTP/1.1" 200 2004 "-" "com.apple.appstored/1.0 iOS/18.3 model/iPhone16,2 hwp/t8130 build/22D63 (6; dt:311) AMS/1"
MY-IOS-DEVICE-IP-ADDRESS - - [02/Feb/2025:15:15:31 +0100] "GET /downloads/applications/lidar-scanner/v1.3.42/ipa/97707e38-079e-4844-9cbf-67cf3c4584c1 HTTP/1.1" 200 11874414 "-" "com.apple.appstored/1.0 iOS/18.3 model/iPhone16,2 hwp/t8130 build/22D63 (6; dt:311) AMS/1"

Thus, the only thing that can have authentication/authorization is the page where you publish the itms-services:// link.

So App Center (and all other similar services?) had no other choice but to implement those generated short-lived unauthenticated download URLs in order not to expose static *.ipa URLs for anonymous downloads. And that is what we did on our side too (as you can see in the web server logs above).

Launching downloaded applications on iOS devices

After downloading/installing the application you will need to perform a certain ritual in order to be able to launch it. To clarify, this applies no matter what solution you will choose for hosting your applications: it was there with HockeyApp, it was there with App Center, and it will be there with any other similar service, including a self-hosted solution which we are talking about here.

So, thanks to Apple, the downloaded application cannot be launched right away (unless this device already had other applications from this organization/profile before). Trying to launch it for the first time, you will get the following message (I don’t know why it says iPhone Distribution, but it works equally fine on both iPhones and iPads):

Trying to launch iOS application, untrusted enterprise developer

What this message means is that you need to go to Settings → General and there will be this ENTERPRISE APP thing (the last section of the General pane):

Enterprise applications in iPad settings

In there there will be a button/label for trusting this profile:

Enterprise applications in iPad settings, trusting button

pressing on which will give you one final confirmation dialog:

Enterprise applications in iPad settings, trust confirmation

After that you will finally be able to launch the application. I can admit that this is not a terrible security measure against potentially malicious applications, but it is quite tiresome nevertheless.

And you guessed it right, you will need to teach/explain this procedure to every single user/employee that you have. It might not look like much to you now, but wait until you’ll be helping with the same bloody set of problems for the 1000th time, as no one ever fucking reads any manuals/tutorials. You can even make a super detailed step-by-step video (we did, in addition to the one we already had for downloading applications from App Center), but even then there will be individuals who will manage to fail to follow the procedure.

Limited number of devices

From the little I know about the Apple side of things, there are different “types” of distribution. If I am not mistaken, the most common ones are a so-called “Ad Hoc” distribution and a so-called “Enterprise” distribution. Both of these seem to have different limitations, but for the love of god I could not find a clear explanation in Apple documentation. So the following details are just my silly understanding of what I could find all over the internet.

With “Ad Hoc” type of distribution there seems to be a limit of 100 devices of each type (100 iPhones, 100 iPads, etc) to which you can install your applications. And each of those devices (their unique identifiers - UDID) has to be registered to your Apple Developer account before you’ll try to install/run your applications on it. Or at least I read something about that somewhere, probably here.

With the “Enterprise” type of distribution (which is apparently the one we have) those limitations do not apply, as we just keep installing our iOS applications on more and more employees devices without registering shit anywhere (unless it happens automatically behind the scenes?), and nothing “bad” has happened yet, everything keeps working fine. And this section in Updraft documentation seems to be describing the same.

Applications expiration

With Apple being Apple there is a surprise awaiting for you where you discover that applications expire in one year. Or rather their “provisioning profile” does. So in one year all your users will get a pumpkin instead of an application that was working fine just yesterday:

Error on trying to launch expired iOS application, integrity could not be verified

To fix that you will need to re-build and re-sign the absolutely fucking same application project just to “refresh” the expiration countdown. And then you will need to tell all your users/employees that they need to go to your website and re-install that “renewed” but otherwise absolutely identical application on their devices.

Again, I don’t remember where I read about this, probably here. Or actually here’s what Microsoft’s documentation says about this:

The enterprise signing certificate that you use to sign apps typically lasts for three years. However, the provisioning profile expires after a year. While the certificate is still valid, Intune gives you the tools to proactively assign a new provisioning profile to devices that have apps that are nearing expiry. After the certificate expires, you must sign the app again with a new certificate and embed a new provisioning profile with the key of the new certificate.

So there is one more surprise: in addition to provisioning profile expiring after 1 year, your signing certificate will also be expiring every 3 years.

Hosting iOS applications on a .NET/MVC website

As I already said in the beginning, now when you know what it takes to distribute an (“Enterprise”) iOS application, it should be rather trivial for you to implement this on your own website, no matter what web-development framework you are using there. In a simplest case even a single static HTML page would do. Or maybe even a bare itms-services:// link sent via e-mail should be enough.

In our case we have a .NET/MVC-based website, so I’ll share the related code fragments. Note that I removed some parts from that code for simplicity/confidentiality, so there might be missing variables or other errors in there. This is just a general example after all, so don’t expect it to work “out of the box”.

To reiterate the key point of having some backend code instead of just a “plain” HTML page: the goal here is to auto-generate short-lived download URLs in order not to expose static *.ipa files without authentication.

Template string for manifest.plist

As you’ll probably have more than one application to distribute, and given that every application will likely have more than one version, it quickly becomes impractical to compose static manifest.plist manually. You could probably auto-generate them with a script every time a new application/version is published, but instead we decided to generate them “on the fly” using a template string:

private const string _manifestPlist = """
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>items</key>
    <array>
        <dict>
            <key>assets</key>
            <array>
                <dict>
                    <key>kind</key>
                    <string>software-package</string>
                    <key>url</key>
                    <string>https://your.company.com/downloads/applications/{0}/v{1}/ipa/{2}</string>
                </dict>
                <dict>
                    <key>kind</key>
                    <string>display-image</string>
                    <key>url</key>
                    <string>https://your.company.com/favicon-32x32.png</string>
                </dict>
                <dict>
                    <key>kind</key>
                    <string>full-size-image</string>
                    <key>url</key>
                    <string>https://your.company.com/favicon-256x256.png</string>
                </dict>
            </array>
            <key>metadata</key>
            <dict>
                <key>bundle-identifier</key>
                <string>{3}</string>
                <key>bundle-version</key>
                <string>1.0</string>
                <key>kind</key>
                <string>software</string>
                <key>platform-identifier</key>
                <string>com.apple.platform.iphoneos</string>
                <key>title</key>
                <string>{4}</string>
            </dict>
        </dict>
    </array>
</dict>
</plist>
""";

Not sure if bundle-version value should also be templated or not, but having it hardcoded to 1.0 didn’t seem to affect anything so far.

It would probably be more correct to generate the manifest.plist with XDocument, but it didn’t seem to be very trivial in case of Apple’s *.plist files schema, and also performance-wise it is likely (although I haven’t measured it) more efficient to just substitute variables in a template string than to construct a XDocument object every time.

Initial download request

As we want to pre-process the download request first before redirecting it to the itms-services:// URI, the download links on the website look like this:

<a href="/files/applications/some-application/v1.2.3/manifest.plist">
    Install
</a>

And here’s the route/action for processing the download request when user clicks on that link:

// note the absence of the [AllowAnonymous] attribute, as this action is protected
// with authentication/authorization policies on the controller level
[HttpGet("/files/applications/{applicationSlug}/v{applicationVersion}/manifest.plist")]
public IActionResult ApplicationDownloadFile(
    string applicationSlug,
    string applicationVersion
)
{
    // check in the database if such application even exists
    var application = _databaseContext.GetApplication(applicationSlug);
    if (application == null)
    {
        _logger.Warn($"There is no [{applicationSlug}] application in the database");
        return NotFound();
    }

    var downloadGUID = Guid.NewGuid();

    // check in the database if there is already an anonymous download
    // for this version of the application (and get its data/info)
    var applicationDownloadAnonymous = _databaseContext.GetApplicationVersionDownloadAnonymous(
        applicationSlug,
        applicationVersion
    );

    if (
        // no such download at all
        applicationDownloadAnonymous == null
        ||
        // there was a download, but it has expired by now
        DownloadLinkHasExpired(applicationDownloadAnonymous.Created)
    )
    {
        if (applicationDownloadAnonymous == null) // does not exist at all
        {
            _logger.Debug(
                new StringBuilder()
                    .Append("There is no existing anonymous download for ")
                    .Append($"[{applicationSlug}], will create one")
                    .ToString()
            );
        }
        else // exists but expired
        {
            _logger.Debug(
                new StringBuilder()
                    .Append($"There is an existing anonymous download for ")
                    .Append($"[{applicationSlug}] - {applicationDownloadAnonymous.GUID} ")
                    .Append("-  but it has already expired, will create a new one")
                    .ToString()
            );
        }
        // add a new download to the database
        _databaseContext.AddApplicationVersionDownloadAnonymous(
            applicationSlug,
            applicationVersion,
            downloadGUID,
            $"{applicationSlug}.ipa" // iOS downloads might not be the only downloads of such nature, so there might need to be some additional logic here
        );
    }
    else
    {
        _logger.Debug(
            new StringBuilder()
                .Append($"Found an existing anonymous download for [{applicationSlug}] ")
                .Append($"that has not expired yet: {applicationDownloadAnonymous.GUID}")
                .ToString()
        );
        downloadGUID = applicationDownloadAnonymous.GUID;
    }

    // redirect the request to itms-services:// URI of the actual manifest.plist
    return Redirect(
        new StringBuilder()
            .Append("itms-services://?action=download-manifest&url=")
            .Append("https://your.company.com")
            .Append($"/downloads/applications/{applicationSlug}/v{applicationVersion}")
            .Append($"/ipa/{downloadGUID}/manifest.plist")
            .ToString()
    );
}

The function for checking the download URL expiration:

private bool DownloadLinkHasExpired(DateTime dtCreated)
{
    return (DateTime.Now - dtCreated).TotalHours > _configuration.GetSection(
        // instead of getting it from appsettings.json, you can just as well simply hardcode whatever value you want here
        // (we've set 2 hours)
        "ApplicationsGallery:DownloadLinkExpirationHours"
    ).Get<int>();
}

Downloading the manifest.plist

The route/action for getting the manifest.plist:

// as you saw in the web server logs, this route should not have authentication,
// otherwise iOS device services will fail to query stuff
[AllowAnonymous]
[Route("/downloads/applications/{applicationSlug}/v{applicationVersion}/ipa/{downloadGUID}/manifest.plist")]
public IActionResult ApplicationDownloadIpaManifest(
    string applicationSlug,
    string applicationVersion,
    string downloadGUID
)
{
    _logger.Debug(
        new StringBuilder()
            .Append($"Got a [{HttpContext.Request.Method}] request to download a manifest ")
            .Append($"for the application [{applicationSlug}], version [{applicationVersion}], ")
            .Append($"download GUID [{downloadGUID}]")
            .ToString()
    );

    ApplicationDownloadAnonymous applicationDownloadAnonymous = null;
    try
    {
        // as we don't trust anyone, check for the existence of the requested download
        // in the database (and get its data/info)
        applicationDownloadAnonymous = _databaseContext.GetApplicationVersionDownloadAnonymous(
            new Guid(downloadGUID)
        );
    }
    catch (Exception ex)
    {
        _logger.Error(
            new StringBuilder()
                .Append($"Error on trying to get the download for GUID [{downloadGUID}]. ")
                .Append(ex.Message)
                .ToString()
        );

        return NotFound();
    }

    if (applicationDownloadAnonymous == null)
    {
        _logger.Warn($"There is no download with GUID [{downloadGUID}]");

        // and maybe even do something more here (send an alert to admins, at least), for example
        // if there are way too many "failed" requests, as it might indicate that someone is trying
        // to guess/bruteforce unauthenticated download URLs

        return NotFound();
    }
    else if (DownloadLinkHasExpired(applicationDownloadAnonymous.Created))
    {
        _logger.Warn($"The download link for GUID [{downloadGUID}] has expired");
        // but don't let user know about this
        return NotFound();
    }

    // this is where the manifest template string gets substituted with the actual values
    // to generate the resulting manifest.plist
    var manifest = string.Format(_manifestPlist,
        applicationSlug,
        applicationVersion,
        downloadGUID,
        applicationDownloadAnonymous.AppleManifestBundleIdentifier,
        applicationDownloadAnonymous.AppleManifestTitle
    );

    return new ContentResult
    {
        Content = manifest.ToString(),
        ContentType = "text/xml",
        StatusCode = 200
    };
}

Downloading the application

Finally, the route/action for downloading the *.ipa file:

// as you saw in the web server logs, this route should not have authentication either
[AllowAnonymous]
[Route("/downloads/applications/{applicationSlug}/v{applicationVersion}/ipa/{downloadGUID}")]
public IActionResult ApplicationDownloadIpa(
    string applicationSlug,
    string applicationVersion,
    string downloadGUID
)
{
    _logger.Debug(
        new StringBuilder()
            .Append($"Got a [{HttpContext.Request.Method}] request to download the IPA file ")
            .Append($"for the application [{applicationSlug}], version [{applicationVersion}], ")
            .Append($"download GUID [{downloadGUID}]")
            .ToString()
    );

    ApplicationDownloadAnonymous applicationDownloadAnonymous = null;
    try
    {
        // check in the database if this download even exists (and get its data/info)
        applicationDownloadAnonymous = _databaseContext.GetApplicationVersionDownloadAnonymous(
            new Guid(downloadGUID)
        );
    }
    catch (Exception ex)
    {
        _logger.Error(
            new StringBuilder()
                .Append($"Error on trying to get the download for GUID [{downloadGUID}]. ")
                .Append(ex.Message)
                .ToString()
        );

        // if (_hostingEnvironment.IsDevelopment())
        // {
        //     return new ContentResult
        //     {
        //         Content = "Failed to query the database.",
        //         ContentType = "text/plain",
        //         StatusCode = 500
        //     };
        // }

        return NotFound();
    }

    if (applicationDownloadAnonymous == null)
    {
        _logger.Warn($"There is no download with GUID [{downloadGUID}]");

        // yet again, maybe do something more here (send an alert to admins, at least), for example
        // if there are way too many "failed" requests, as it might indicate that someone is trying
        // to guess/bruteforce unauthenticated download URLs

        return NotFound();
    }
    else if (DownloadLinkHasExpired(applicationDownloadAnonymous.Created))
    {
        _logger.Warn($"The download link for GUID [{downloadGUID}] has expired");
        // still don't let user know about this
        return NotFound();
    }

    var downloadPath = $"{_hostingEnvironment.WebRootPath}/files/applications/{applicationSlug}/v{applicationVersion}/{applicationDownloadAnonymous.FileName}";
    if (!System.IO.File.Exists(downloadPath))
    {
        _logger.Warn($"Could not find the file [{downloadPath}]");
        // user should probabably not know about this either
        return NotFound();
    }

    return PhysicalFile(
        downloadPath,
        "application/octet-stream",
        applicationDownloadAnonymous.FileName
    );
}

It should be obvious and already known by now, but probably won’t hurt to explicitly state this one more time anyway: direct static URLs to the “physical” /files/applications/{applicationSlug}/v{applicationVersion}/some-application.ipa files should never be exposed in your website routes without authentication/authorization. That is the entire point of having those temporary GUID-based URLs in the unprotected/anonymous ApplicationDownloadIpa() route/action, which is meant to be serving the actual files via PhysicalFile.

Now, if it’s all good, your users/employees will be able to download and install iOS applications from your company website:

Installing an iOS application from a website

If anything, the screenshot above shows an admin view with additional controls. Regular users will see a simplified “less capable” variant.