Using your university’s free Apple Developer account to eliminate the “Unknown Developer” Error in your 3rd-party-developed macOS App

If you work for a university and have developed a macOS app (as a part of your academic job) using 3rd party software (e.g. a Java app developed with Eclipse and built with Gradle), you’re probably familiar with telling your users how to deal with the annoying “Unidentified Developer” error they get when they double-click your app:

negcontrol.png

They get a window saying “<your app> can’t be opened because it is from an unidentified developer“.  The user is given no clear option on how to run the app except a vague reference to “security preferences”.

There are things the user can do to get around this error without you becoming an “identified developer”.  A user can perform a one-time bypass by right-clicking the app and selecting open or they can muck around with their Security & Privacy System Preferences settings.  They can even execute some commands in the Terminal to reveal a setting that has been hidden in the past few versions of macOS to always allow apps from anywhere.  But what would be nicer is to eliminate this error so that the user doesn’t have to do any of that.  Normally that involves giving Apple money to pay for membership in their developer program, but if you’re in academia, Apple has free such accounts for “Educational Institutions”.

Chances are, your university has already enrolled in this program and all you have to do is hook into that resource.  But be aware that universities have an image to uphold and that digital identity extends into the App Store, so they’re not likely to welcome any app to sit alongside their custom campus, reunions, and transit apps.  You can belay their fears about your app by noting that you intend to distribute your app outside of the App Store.  Users who download your app won’t even ever see the university’s name unless you added it to your app yourself.  All you need is a certificate that will allow you to code-sign your app so that Apple can know who you are.

It took me awhile to navigate this system.  I initially ran off on this tangent trying to create a free “education” Apple Developer account by digging up and supplying my University’s D-U-N-S number, official address, etc… and ran into a form that asked me to assert that I could commit the university to legally binding agreements, at which point I realized that I was on the wrong path.  Free educational institution Apple Developer accounts aren’t per person, faculty, or department.  They’re 1 per university.  I already had a couple of official university apps on my iPhone, so I knew there already existed an account, and made a number of calls before I got put in touch with the Apple Developer Account “holder”.

Those in charge of the Apple Developer Account here were only familiar with iOS app development, so they didn’t know how to advise me on accomplishing what I wanted to accomplish.  My sole goal was to eliminate the “Unidentified Developer” error.  No-one knew whether that meant I had to distribute my app on the app store or what, and they were of course concerned about the app showing up alongside all their campus-centric apps.  I managed to convince them that I wouldn’t be distributing on the app store and that I believed all I needed was a code-signing certificate.  Since no-one here knew how to do that, I called Apple again.

Apple really pushes their developers into Apple’s canned development resources (XCode) to do their development.  In fact, even their developer support team members tend not to know anything about code-signing and certificates, because it’s all handled in the background behind XCode.  I had numerous phone calls with Apple Developer Support and they proclaimed that it sounded like I was “speaking a different language”.  They weren’t even familiar with the “Unidentified Developer” error and immediately referred me to the makers of the 3rd party development apps I was using, implying it was a problem with their software.  I persisted however, because I had already tried code-signing using apple’s codesign command line utility and managed to get them to at least confirm that what I suspected was happening was happening.  And that is, that not any certificate will do… but I’m getting ahead of myself.

Here, I will walk you through, in detail, the steps I took to eliminate the error from my latest app (TreeView3)…

How to distribute an academic (e.g. “scientific”) macOS app outside the app store

Purpose

To eliminate the “Unidentified Developer” error when users try to run our app downloaded from a third party repository (e.g. BitBucket or github)

Requirements

  • Gradle (and the macAppBundle plugin)
  • You are employed by an educational institution
  • A Mac computer
  • An Apple ID
  • A personal Apple Developer ID (obtained using your Apple ID from here)
  • Apple’s Developer Tools (In Terminal.app, run `xcode-select –install`)
  • Contact info of your university’s Apple Developer account holder (either the team agent or a team admin).  If your university hasn’t enrolled in the Apple Developer Program, someone who can bind the university to legal agreements must start the process here (selecting “Accredited Educational Institution” under “Entity Type”)

Desired Result

  1. Distribution of your .app distributed inside a .dmg, outside of Apple’s App Store
  2. No “Unidentified Developer” error when a user downloads & runs your app
  3. Your app will not impact your university’s campus-centric digital identity on the App Store

Overview

  1. Setup
  2. Development Testing
  3. Obtaining a Production Level Certificate
  4. Production Testing

Scope

  1. These instructions assume you have finished your app development and are ready to distribute
  2. These instructions assume you are building a working app using Gradle and the macAppBundle plugin
  3. The only topic covered in this article is how to eliminate the “Unidentified Developer” error from an otherwise fully working Java app, though the information contained may be useful in other contexts

How-To Procedure

  1. Setup

    1. Confirm that you have obtained a personal Apple Developer ID mentioned in the requirements above and have identified your academic institution’s point-of-contact for their Apple Developer Account
    2. Contact your University’s Apple Developer Account holder (an Admin or the account Agent) and request to be added to the team as a “member” (the lowest privilege access level) and supply them with your Apple ID so that they can email you an invitation
    3. The invitation you receive will look something like this: appledevinvite.pngClick the invitation link and respond to the invite within 30 days.
  2. We’re going to start off by generating a “Mac Development” certificate in order to test that our code-signing procedure is correctly configured before attempting to use a production certificate, which will involve the time of the team agent:

    1. Log into your Apple Developer account and do the following:

      1. Click “Certificates, Identifiers & Profiles”: certsidsprofs.png
      2. Select “macOS” from the drop-down menu at the top left:macoscerts.png
      3. Under “Certificates”, click “All”: certsall.png
      4. Click the “+” at the top right:pluscert.png
      5. Click the “Mac Development” radio button and “Continue”, leaving this window open:macdevreq.png
    2. Now we switch to an app on all macs called “Keychain Access.app”.  Just do a Spotlight search to find it.  We’re going to use it to create a “Certificate Signing Request” (CRS, for short)

      1. Select Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority:csrmenu.png
      2. Enter your: university email, full name, & saved to disk (leaving “ca email” empty) & click continue
      3. Select a memorable place to save the CSR file & click done
    3. We need to submit our CSR to Apple, so let’s return to the window we left open above (in step 4.1.5) and do the following:

      1. Click continue to indicate we’re ready to upload our CSR
      2. Upload the saved CSR file & click continue on the following page
      3. Click download to retrieve your development certificate and then done
      4. You can move the certificate (ending with .cer) from the downloads folder to a safe place so you don’t lose track of it
    4. Install the Mac Development (.cer file) certificate

      1. Double-click the .cer file.  It will open in Keychain Access.app.
      2. When prompted, select the login keychain (or whichever keychain you prefer) and click add.
      3. Find the certificate in Keychain Access.app.  Narrow your search by clicking on the “Certificates” category.  Your certificate will be named something like this: “Mac Developer: <your name> (<certificate-ID-string>)”.  There should be a triangle next to it that when expanded reveals a private key that Keychain Access created upon installation.  If the key is not there, it dod not install correctly, possibly because the .cer file wasn’t created by you or downloaded from your own Apple Developer account.
      4. Double-click the certificate named “Mac Developer: <your name> (<certificate-ID-string>)” and copy the user ID/certificate-ID-string.  I’ll refer to this as the “cert string” here-on-out.
    5. Now let’s add the cert string to your application build process.  Open your build.gradle script and make the following edits:

      1. Add `certIdentity = “cert string“` to your macAppBundle block, where “cert string” is a string of random characters that looks something like “Z4XE107A5H”.
      2. Then add `createDmg.dependsOn(codeSign)` underneath/outside the macAppBundle block (so that `gradle createDmg` will execute the code-sign).  The final code snippet might look something like this:gradleexample.png
    6. Test your certificate with a new gradle build

      1. cd into your project directory (where your build.gradle script is)
      2. Execute gradle createDmg
  3. Obtain a “Developer ID Application” certificate.


    At this point, if everything worked (i.e. the build above succeeded and there’s a message in the verbose output that says “:codeSign” without an error following it) and you’re ready to release your app, you must obtain a “Developer ID Application” certificate, install it, and replace the cert string with that of the new certificate. This is specifically for distributing your app outside of the mac app store *and* if you’re not creating an installer, but rather a .app inside a dmg.  The following steps may be slightly inaccurate or incomplete, because I did not witness this process, but had emailed the steps to our team agent who followed them…

    1. Request your university’s Apple Developer team agent to create a certificate of type “Developer ID Application”.  (Note: an admin cannot create a certificate of this type.)  This entails the following steps:

      1. Log into the Apple Developer “agentaccount and do the following:
        1. Click “Certificates, Identifiers & Profiles”
        2. Select “macOS” from the drop-down menu at the top left
        3. Under “Certificates”, click “All”
        4. Click the “+” at the top right
        5. Click the “Developer ID Application” radio button:c_create_developer_id_certificate.png
        6. Click continue (and leave this window open, to return to it later)
      2. In the Keychain Access app:
        1. Select Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority
        2. Enter your: university email, full name, & saved to disk (leaving “ca email” empty) & click continue
        3. Save the CSR file in a memorable place & click done
      3. Go back to your apple developer account where you left off and:
        1. Click continue to indicate you’re ready to upload your CSR
        2. Upload the CSR file and click continue on the following page
        3. Click download to obtain the certificate and then click done.
        4. Select a memorable place to save the .cer file
      4. Double-click the certificate in the Finder (which opens in Keychain Access) and do the following:
        1. Select the login keychain & click add
        2. In the Keychain Access window that opens up, click the “Certificates” category to find the cert, which should be named something like “Developer ID Application: <team name> (<cert-ID-string>)”
        3. Expand the certificate by clicking the gray triangle next to it and highlight both the “Developer ID Application…” row and the next row, which is the “team agent name” private key
        4. While both rows are highlighted, right click and select “Export 2 items” in order to share them with the team member who requested them
        5. You will be saving a p12 file to your machine, and you will need to create a password for it in order to share the file (you will need to share the password as well), so note it down
        6. Email both the P12 file and the password to your team member (who does not have to be an admin or agent – just “team member”)
    2. Once you receive the certificate (and private key) in the form of a .p12 file via email, install it by doing the following:

      1. Save the cert/key (.p12 file) in a memorable place
      2. Double-click the p12 file in the Finder (which opens in Keychain Access.app)
      3. Select the login keychain & click add
      4. Click the “Certificates” category to find the cert as before, but this time it will be named like “Developer ID Application: <team name> (<cert-ID-string>)”, and ensure that you can reveal your personal private key with your name on it underneath the certificate.
      5. Double-click the certificate and copy the user ID
    3. Return to your build.gradle script and replace the cert string from your Mac Development certificate with the one you copied in the previous step, then save the file.

    4. Test your certificate with a new gradle build

      1. cd into your project directory (where your build.gradle script is)
      2. Execute gradle createDmg
    5. Test your new code-signed app

      1. Make sure the security & Privacy settings in your System Preferences are set to allow apps installed from known developers
        1. Open System Preferences
        2. Click “Security & Privacy”
        3. Click the lock in the lower left corner (if locked) and enter your system password
        4. Under “Allow apps downloaded from”, select “App Store and Identified Developers”
        5. Click the lock and close the window
      2. Try to provoke an “Unidentified Developer” error
        1. Upload your dmg to bitbucket or whichever repository you intend to distribute your app from
        2. Re-download the dmg from your repository
        3. Double-click the newly downloaded dmg
        4. Drag the app to your Applications folder
        5. Double-click your app
        6. If the app opens without an unidentified developer error, it worked! Note, you will still get a warning that the app was downloaded from the internet, but will be prompted with an open button.openedfrominternet.png Apple’s gotta have some way to get 3rd party app developers to pay-up, after all.

Acknowledgements

This article is an updated variation of devreboot’s “Distributing an app on Mac OS X without Xcode, outside the Mac App Store“.  If you’re not using Gradle, there are some relevant tidbits about doing the signing yourself on the command line in there.  Without devreboot’s article, I would have had a very hard time figuring out what to do.

The macAppBundle gradle plugin only has information on the codesign ability in one of the issues pages, which is a good resource if you’re having trouble with it.

I had had a hard time figuring out which certificate I actually needed.  There are a number of them and I had a couple false-starts, but then I found this article on stack overflow that had some great info.

Without this article by Jonathan Franchell, I’d have been stuck scratching my head as to why an emailed certificate was not working for me.  It explains that the private key must be emailed with the certificate in a .p12 file.

Me and the Admin I worked with from the Apple Developer team at my university would not have known why we could not find the Developer ID Application certificate had it not been for this Apple documentation.

Note, an Apple Developer account can generate 5 Developer ID Application certificates and they need to be renewed/recreated every 5 years.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

w

Connecting to %s