Distribution – Xojo Programming Blog

Team-based Signing Arrives to macOS

Javier Menendez — Tue, 31 Mar 2026 13:21:00 +0000

In Xojo 2026r1 we revised the macOS Developer ID field and replaced it with a Team-based popup menu that aligns with the style found in iOS projects. This change aims to offer a cleaner, more intuitive way to manage developer certificates for the distribution of your built macOS app.

The Developer ID field was introduced in Xojo 2022r1, allowing you to fill in the developer certificate information needed for signing built macOS apps; however, it could be confusing to know exactly what information was expected.

Developer ID Application
Developer ID Application: Francisco Javier Rodriguez Menendez
Developer ID Application: Francisco Javier Rodriguez Menendez (BW7PU32485)
7D767DB917A45A8976BEB5B92F04E8C18D09501A

And… which certificate should be used for Development builds, Direct Distribution, or Mac App Store publishing? That may not be obvious for someone new to all this.

Additionally, what happens if the entered data comes from an expired certificate or if the certificate isn’t in the Keychain?

The new approach: How it works

The Team-based signing chooser for the Mac Developer ID field follows these steps:

Collects all the developer certificates found under the user Keychain.
Groups the valid certificates by Team (what Apple designates as the TeamID).
Based on the previous information, the new popup menu “Build For” will offer only the code-signing options available for the current selected Team:
- Development. This is the equivalent to using the Apple Development certificate.
- Direct Distribution. This is the equivalent to using the Developer ID Application certificate.
- App Store. This is the equivalent to using the Apple Distribution certificate. In addition, the Publish feature will be enabled if, for the selected Team, there is also a valid 3rd‑party Mac Developer Installer certificate available.

If None is selected in the Developer ID popup menu, the macOS app will be built/debugged using Ad-Hoc signing.

Both menus update on the fly, so if new certificates are added (or removed) from the keychain, or if any have expired since last opened, both the Developer ID and Build For popup menus will reflect those changes.

macOS Certificates Inspector Window

Under the Teams popup menu, there is also an Inspect… option. When selected, it opens a new window where you can view and gather additional information for:

Installed / Missing Apple Intermediate Certificates.
Installed / Missing / Expired Developer Certificates, grouped by Team.

At a glance, you’ll see useful details for each certificate, such as:

The expiration date
The keychain where it is stored.
Serial number, useful for identifying same-kind developer / intermediate certificates under different Macs.
Issuer specific information.

Clicking any certificate provides more detailed information about the role it plays in the macOS signing process.

This Inspector is also useful in order to identify some of the most common issues related with the handling of certificates such as:

Missing certificates for a given Team, determining thus the options that are available under the “Build For” popup menu.
Expired certificates. These also determine the options that are available under the “Build For” popup menu for a given Team. In addition, if you want to do some cleanup, it is possible to delete these expired certificates directly from the Inspector without needing to open the Keychain Access app.
About to expire certificates, so you are aware of it and the impact it could have on apps close to be distributed or on already created Provisioning Profiles, for example.
Certificates with their private key missing. These can’t be used for signing purposes, so you will be able to re-install them in the keychain (if you have a backup) or install a new certificate.
Developer Certificates where some of the required intermediate certificate is missing. You will be able to install the missing Intermediate (active Internet connection required).

Improvements to macOS Builds and Debugged apps

Although Sandboxing, Entitlements, and Provisioning Profiles have been part of macOS app development, this release brings several enhancements in these areas:

Now it is possible debug Sandboxed apps directly from the IDE.
Entitlements and Provisioning Profile are applied when the app is debugged from the IDE.
Improvements in how the required Entitlements are added and signed when the macOS app is built; and also a better handling of the user-added entitlements and provisioning profile files (if required).
Debugged and Built apps can be attached to the Instruments app. Among other things, Instruments can be used to detect issues such as memory leaks in the executed app. The IDE now automatically adds the required entitlement for this when: the app is debugged/built using the “None” (Ad-Hoc signing) from the Team popup menu, or, 2) when the app is built for Development (Build For) for a given Team.

When Build For is set to Direct Distribution or App Store, the required entitlement for Instruments to attach to the app, will be added only when the app is debugged from the IDE. If you want to use Instruments with a built app signed using these certificates, then you need to add that entitlement explicitly.

This decision is because when get-tasks-allow is set to True (the entitlement required in order Instrument being able to function), there are some well documented vulnerabilities that could be used to escalate privileges or inject code into your app. That’s not desirable for your distributed apps for sure (whether using Direct Distribution or if your app is installed through the Mac App Store).

Looking forward

We know there are still some areas to improve regarding code signing on macOS (and iOS) and we are working on some of them already. In the meantime, you’ll likely find the new Team-based Developer ID option more approachable, especially if this is your first experience dealing with certificates, signing, and distributing your freshly built macOS app.

A big THANK YOU to Richard Grafl for all his help and feedback during the beta-testing cycle of this feature.

Happy macOS code-signing!

Javier Menendez is an engineer at Xojo and has been using Xojo since 1998. He lives in Castellón, Spain and hosts regular Xojo hangouts en español. Ask Javier questions on Twitter at @XojoES or on the Xojo Forum.

Learn more about Code Signing in our recent series:

Code Signing on macOS: What Developers Need to Know

Code Signing on macOS: What Developers Need to Know, Part 3

Javier Menendez — Tue, 24 Mar 2026 16:00:00 +0000

If you followed the previous two articles in this series, you should be set up properly now, right? Your Mac developer certificates are stored in Keychain Access, so you only need to fill in the Developer ID field under Build Settings > macOS > Sign with the appropriate certificate value, click Build (or Publish), and distribute your new amazing app worldwide. Well, not quite. There are still other pieces to consider when signing and distributing your macOS app.

For the past 20 years, Apple has increasingly tightened security measures when it comes to running apps distributed by third parties. Let’s take a look at this summarized timeline of code-signing and security measures added by Apple over years:

The most notable developments happened in 2011, 2012 and 2018, when terms like Sandbox and, especially, Containers, Gatekeeper, Hardened Runtime and Notarization were introduced and began to impact other pieces of the puzzle to consider when signing macOS apps. In fact, we could say that technologies such as code-signing, Sandboxing, Entitlements or Provisioning Profiles were among the first iOS technologies to make their way to macOS.

So here is an broad overview what these technologies mean:

Sandboxing– When used, Sandboxing confines applications to a restricted, designated area of the system (its own “container”), preventing them from accessing user data, hardware or other apps without explicit permission. The system requires apps to ask for permission to use hardware resources or access user files. Sandboxing is mandatory for apps distributed through the Mac App Store.
Gatekeeper- This technology is the primary security layer that checks whether a downloaded app comes from a verified/known developer, especially when the application has been Notarized by Apple.
Hardened Runtime– Acts as a proactive, system-enforced shield that protects applications while they run, preventing malicious code from exploiting legitimate software. Enabling Hardened Runtime is required for Notarization.
Notarization– Notarization is an automated security screening process run by Apple that scans software distributed outside the Mac App Store for malicious components and known security issues. Today, notarization is required for software distributed outside the Mac App Store that has been signed with the Developer ID application certificate. As a result of the process, notarization generates and staples a ticket, signed by an Apple certificate, to the app so Gatekeeper can trust it when executed.

So, basically, while Sandboxing is still optional for apps distributed outside the Mac App Store (i.e., signed with your Developer ID certificate), Notarization and Hardened Runtime are the recommended defaults. Enabling Sandboxing for your app is something you should consider based on the needs (features) and the privacy balance you want to offer your users.

If you plan to distribute the app through the Mac App Store as well, it will need to be Sandboxed and signed with your Apple Distribution certificate, while enabling Hardened Runtime is optional.

Entitlements and Provisioning Profiles

Entitlements and Provisioning Profiles are also required for many of these security measures, depending on the features and services your app uses, and they come into play during building and signing.

If you decide to go the Sandboxing route, then using Entitlements is mandatory. The good news is that Sandboxing entitlements are free to use (they don’t require creating or adding a Provisioning Profile to the project). However, if your app needs special access to the Keychain or uses iCloud, Apple Pay, or other services, you’ll need to create a Provisioning Profile in the Apple Developer portal.

Wait—what are Entitlements and Provisioning Profiles, and how do they relate to macOS app code signing?

Entitlements

Entitlements are XML-based .plist files (not unlike the app’s Info.plist) containing a set of key-value pairs. They are embedded directly into the app’s binary as part of the code signing process, typically using your Developer ID Application or Apple Distribution certificates.

Provisioning Profiles

While Entitlements are just a file, Provisioning Profiles are a different beast:

Provisioning Profiles must be created in the Apple Developer Portal. When you create one, you specify the App ID (the combination of your Team ID and the app bundle identifier which are case sensitive so pay attention). Even if you don’t plan to distribute your macOS app via the Mac App Store, you still need a Provisioning Profile, which requires creating an App ID first in the Developer Portal.

There are two kinds of Provisioning Profiles: Development and Distribution. As part of the provisioning profile creation, you must choose which type you will use.

Development Provisioning Profiles are used while you’re developing your app; the app is signed with an Apple Development certificate and is intended to run on a set of Mac computers you’ve registered. During creation, you can add as many Apple Development certificates as you have under your Team ID.
Distribution Provisioning Profiles are used when distributing your app. For direct distribution, sign with the same Developer ID certificate you’ll use for signing the app; for Mac App Store distribution, sign with the Apple Distribution certificate.
Development and Distribution Provisioning Profiles do expire. This is something to keep in mind, especially when deploying new or updated versions of your app, because you may need to create new profiles.
Development and Distribution Profiles are editable. If you make a mistake, note that both types can be edited in the Apple Developer portal, but only for certain fields: the App ID, the profile name, the selected certificate, and (for Development profiles) the included testing devices.

When Certificates and/or Provisioning Profiles expire…

We’ve already noted in previous articles that Apple Developer certificates expire one year after they’re created. We’ve also learned that if your app relies on a Distribution Provisioning Profile, that profile can expire as well. So, what does this mean for your already deployed apps?

No worries. Let’s focus first on directly distributed macOS apps (those signed with the Developer ID certificate) and pull one screenshot from the previous article:

Observe the highlighted Timestamp line. When the app is signed, the date is added automatically (retrieved from Apple’s servers). So, when a user runs an app whose embedded Developer ID Certificate has expired since its release, Gatekeeper will rely on that timestamp, compare it to the embedded certificate’s expiration date, and if everything matches—meaning it was signed before the certificate expired—the app will continue to work, provided the embedded certificate has not been revoked by the developer. In addition, if the app was Notarized, that helps a lot, because the stapled ticket includes its own timestamp and was signed with a longer-lasting Apple Certificate.

If the app is distributed through the Mac App Store, there’s good news. After you submit the app for distribution via App Store Connect and it passes Apple’s review, the app’s signing with your Apple Distribution certificate is replaced by Apple’s own signing. This means that users who install the app from the Mac App Store can continue to run it even if your original Apple Distribution certificate expired long ago.

Distribution Provisioning Profiles behave differently from others: once they expire, the app containing such a Distribution Profile will fail to execute.

The good news is that a Distribution Profile lasts for a very long time (around 18 years) so you’ll likely have ample time to create new distribution provisioning profiles and deploy updates that use renewed profiles well before users are affected.

Of course, as soon as any of your Apple Developer certificates expire, you already know how to request and install new ones in your Mac keychain.

Nearly Concluded

In the next, and last article, we will see how Xojo helps with everything related to signing and distributing your macOS apps. I’ll also show you how to deal with some of the most common issues related with certificates.

Code Signing on macOS: What Developers Need to Know

Code Signing on macOS: What Developers Need to Know, Part 2

Javier Menendez — Wed, 18 Mar 2026 14:00:00 +0000

On the Apple side of code signing with developer certificates, we already know that the required root certificate, acting as the base anchor of the trust chain, is installed already on our Macs under the System Roots keychain.

But before we can reach our leaf developer certificates, we also need to have the Apple Development Intermediate certificates installed in our keychain. These are typically found in the Login keychain, though they can also be found in the System Roots or System keychains.

Installing Apple Developer Intermediate Certificates

Since Xcode 11.4.1 and later, these can be automatically downloaded and installed in the keychain, but if not, they can also can be downloaded from the Apple PKI webpage. The ones we are interested in are:

Developer ID – G2
Worldwide Developer Relations – G2
Worldwide Developer Relations – G3
Worldwide Developer Relations – G4
Worldwide Developer Relations – G5
Worldwide Developer Relations – G6

Note: The Developer ID – G2 certificate corresponds to the Developer ID Certification Authority. The WWDR certificates (G2–G6) correspond to the Apple Worldwide Developer Relations Certification Authority.

As you can see from the list, there are several versions (or generations) for the WWDR Intermediate certificate; so, which one should you download? The short answer: it depends.

On February, 7, 2023 the previous WWDR intermediate certificate expired; so Apple decided to rollout a new renewed version that will expire on February 20, 2030. As part of that update Apple issued additional Intermediate certificates to better segment the purpose of different certificates:

G2: ECDSA signing for Apple Pay.
G3: Software signing and Services.
G4: Features supported by Apple Push Notification Service.
G5: App Store Signing and Services.
G6: ECDSA signing of Software and Services.

In practice, G3, G4, and G5 are sufficient for most scenarios.

Developer Certificates: The final goal!

To focus on the subject, what kind of leaf developer certificates are created from these two types of Intermediate certificates? This scheme will help:

As you can see from the above diagram, there are four main leaf certificates we will use to sign our macOS apps, based on their prefix:

Developer ID Application. Use this one to code sign a macOS app distributed outside the Mac App Store.
Developer ID Installer. Use this one to code sign the Installer, DMG or .pgk file of a macOS app distributed outside the Mac App Store.
Apple Distribution. This certificate is required to code sign a macOS app sent to the AppStore Connect for its distribution through the Mac App Store.
3rd Party Mac Developer Installer. This Certificate is required to code sign the package of the app sent to the AppStore Connect. For example, when using the Publish feature from the Xojo IDE.

Creating and Installing the Developer Certificates

As stated in the first article of this series, you need a paid Apple Developer Program membership. Once that’s in place, the easiest way to install these required certificates in your macOS Keychain is through Xcode.

So, if it is the first time you need to install them on a Mac computer:

Go to Xcode > Preferences.
Select Apple Accounts.
Use your developer credentials to login into your developer account, or select it from the list if you are already logged.
Select the Team from the list.
Click the “Manage Certificates…” button.
Click the “+” popup menu in the lower-left corner of the resulting window, and select the developer certificate you want to install (all of these if it is the first time you install them).

Note: Under the hood, Xcode follows the same process described for installing the developer certificates manually.

If you prefer to go through the manual process instead:

Access the Apple Developer website.
In Certificates, Identifiers & Profiles, click Certificates in the sidebar.
On the top left, click the add button (+).
Under Software, select Developer ID, then click Continue.
- Developer ID Application: This certificate is used to code sign your app for distribution outside of the Mac App Store Connect.
- Developer ID Installer: This certificate is used to sign your app’s installer Package for distribution outside of the Mac App Store Connect.
- Apple Development: Used to run and debug apps on macOS during development.
- Apple Distribution: Used to sign apps for submission to App Store Connect.
- Mac App Distribution: Used to sign macOS apps intended to be distributed through the Mac App Store.
- Mac Installer Distribution: Used to send the macOS app to the App Store Connect for TestFlight or distribution through the Mac App Store.
Follow the instructions to create a certificate signing request.
Click Choose File.
In the dialog that appears, select the certificate request file (a file with a .certSigningRequest file extension), then click Choose.
Click Continue.
Click Download.
The certificate file (a file with a .cer file extension) appears in your Downloads folder.
To install the certificate in your keychain, double-click the downloaded certificate file. The certificate appears in the My Certificates category in Keychain Access.

It’s All About Identities

While Intermediate and Root certificates only have the Public Key on them, so they can verify other (leaf) certificates, the leaf certificates installed on your macOS Login keychain behave a bit different. Let’s see how.

Both if you use Xcode or create the CSR request manually to generate the developer certificates, using the Keychain Access app for that, in both of these scenarios a Private Key will be created and stored locally on your keychain as part of the process. Only the public key section of that private key is sent to the Apple servers so it can be included in the generated developer certificate. Once any of the possible developer certificates is downloaded and installed in the keychain, such certificate will have its private key associated with it:

The pair of the developer certificate and the associated private key is what is called an Identity.

Code signing With Developer Certificates

In fact, while we often say or hear “code signing with certificates,” the real signing of the app is done with the private key associated with that certificate. The certificate itself (and thus the public key portion of that key pair) is included in the signing process. This allows macOS to verify the signature each time the user runs the app

Do you remember the diagram showing how the “Ad-Hoc” code signing process works? Let’s compare it when the same process is done using a “Developer ID Application” Certificate… and, most important, the associated private key:

As you can see, in this case the data is cyphered using the private key from the developer certificate and, then, the certificate itself is stored as part of the app itself. So, if for example we build this time an empty Desktop app for macOS using the Developer ID Application, and open the resulting CodeResources file in a text editor we will see something different compared with the Ad-Hoc signed version:

In this case the field requirement associated with each file and hash value is significantly more strict. In fact, it makes reference to the Chain of Trust Gatekeeper is required to follow and validate. In plain English, the highlighted lines come to say something like:

Hey! make sure there is a Developer ID Application certificate (Apple Extension attribute —OID— 1.2.840.113635.100.6.1.13 for the X.509 certificate), for the developer with a TeamID BW7PU32485.
Next, verify such certificate is issued by the “Apple Developer ID Certificate Authority” (other of the Apple-specific X.509 extension, attribute or OID. In this case: 1.2.840.113635.100.6.2.6).
And finally, go down through the Chain of Trust and verify the previous one with the Anchor certificate (Apple Root CA, do you remember?)

So far so good. But how we can know if the app meets these requirements; and what about the certificates themselves? Well, it’s easy to check both using the codesign tool.

Open a Terminal window and type the following command:

codesign --verify -vvv "MyApp.app"

The output will be something similar to this:

As you can see in the highlighted lines, yes, it satisfies the Designated Requirements we saw in our CodeResources file! Also, the previous line states that it is valid on disk. That means:

All of the expected files are present.
There are no extra files.
None of the files have been modified.
A basic trust evaluation of the leaf certificate was successful.
And it satisfies its own Designated Requirements (DR).

It is even possible to see the Chain of Trust for the code signature issuing:

codesign --display -vv "MyApp.app"

And if you are curious enough, it is even possible to extract the embedded certificates stored in the CMS structure within the code signature:

codesign --display --extract-certificates "MyApp.app"

As result it will, usually, create three files. Take a closer look at the “Issuer” and “Subject” lines; specially on the Subject line for the OU value (Organizative Unit or, using Apple wording, the TeamID) for the codesign0 file. Do you remember the “leaf[subject.OU=BW7PU32485]” data from the CodeResources file? :

codesign0. This is the file for the Leaf certificate; in our example “Developer ID Application”.

codesign1. This one is for the Intermediate Certificate; in our example “Apple Developer ID Certificate Authority”.

codesign2. This one is for the Anchor Certificate; in our example “Apple Root CA”

As shown by the Issuer line in the codesign0 file for our “Developer ID Application,” it points to the previous certificate in the trust chain—the Developer ID Certification Authority. The codesign1 file for the extracted Developer ID Certification Authority points to the Apple Certification Authority in its Issuer field. Finally, the codesign1 certificate points to itself because, as the Root Certificate, it serves as the anchor for the trust chain.

Wrapping up

In this second article, we delved deeper into how Apple Developer certificates work, how a macOS app is signed (Ad-Hoc or with a specific developer certificate), and how the OS’s security features validate the signing when a user tries to run the app.

In the next article, we will cover more details about signing apps for the two main distribution types: Direct distribution and Mac App Store. We will also discuss what happens when certificates expire and how to troubleshoot the most common issues related to development certificates.

Code Signing on macOS: What Developers Need to Know

Code Signing on macOS: What Developers Need to Know, Part 1

Javier Menendez — Wed, 04 Mar 2026 16:00:00 +0000

Your macOS app is finished and ready to go. But unless you plan to run it only on your own machine, there’s one essential step before sharing it with others: code signing with certificates.

This blog series provides a clear, practical overview of how certificates work, with a focus on signing and distributing macOS applications. Some concepts apply to digital certificates in general, while others are specific to the macOS code signing process. By the end of the series, you’ll understand what certificates are, why they matter, and the role they play when building and distributing a macOS app.

The Developer ID field in the Build Settings > macOS > Sign Inspector Panel is our starting point:

By default, this field is empty. When you click Build, the app bundle (and its contents) is signed using a more relaxed security configuration. This does not require an explicit developer certificate and does not verify that the app comes from a known, trusted developer.

This type of signing is called Ad-Hoc signing. It is perfectly fine when debugging from the IDE or when building apps you intend to run locally.

In earlier versions of macOS, it was even possible to distribute and run Ad-Hoc–signed apps on other Macs, as long as the user explicitly chose to trust them. While this is still technically possible on recent versions of macOS, Apple has continued to tighten security, making it increasingly difficult for users to launch Ad-Hoc–signed applications.

In most cases, Gatekeeper will intervene and prevent the app from launching. Since the system cannot verify the identity of a trusted developer, it treats the app as unverified. With Ad-Hoc signing, macOS can only confirm that the app has not been modified since it was signed, it cannot validate who created it.

Under the hood: How “Ad-Hoc” signing works

Every time an app is signed (including all the contents inside its bundle) macOS uses Apple’s codesign tool. When Ad-Hoc signing is applied, the simplified process works roughly like this:

A hash value (a unique digital fingerprint) is calculated for every file in the app bundle, whether it is executable or not, as well as for the bundle itself.
These hash values are stored inside the app bundle, in the _CodeSignature folder.
If the app contains multiple architectures (for example, x86 and ARM), the process is repeated for each supported architecture.

When a user double-clicks the app to launch it, macOS performs a similar verification process:

It recalculates the hash value for every file in the bundle.
It compares the newly calculated values with those stored in the _CodeSignature folder and if any hash differs from the stored value, macOS determines that the bundle has been modified since it was signed and it will refuse to launch the app.

Want to see this in action? Create a new Desktop project in the Xojo IDE, save it to your Documents folder, and build it for macOS.

Next, locate the built app in Finder. Control-click it and choose “Show Package Contents.” Then open the Contents > _CodeSignature folder and inspect the CodeResources file using your favorite text editor. You’ll see a list of hash values and digests corresponding to every file in the app bundle.

Apple Developer Certificates: Establishing Trust on macOS

What must you do so your apps are recognized as first-class citizens on macOS and can be distributed without Gatekeeper intervening? The answer is likely familiar: enroll in the Apple Developer Program (currently US $99 per year).

Among its many benefits, membership in the Apple Developer Program allows you to create your own Developer ID certificates. When you use these certificates to sign your apps, macOS can validate the signature and identify you as the verified developer distributing the software.

But how is this trust established and verified? To answer that, we need to start at the very root, literally!

Every computer, smartphone, tablet, and many other devices come with preinstalled Root Certificates. These certificates are issued by trusted organizations known as Root Certificate Authorities (CAs), including Apple. They serve as the foundation of a chain of trust, allowing other certificates issued by those authorities to be verified.

Technically speaking, a Root Certificate Authority (CA) is the top-level trusted entity in a public key infrastructure (PKI). It issues self-signed root certificates that act as the trust anchor for verifying other digital certificates. In other words, it is the foundation upon which the entire certificate trust model is built.

It is easy to take a look to these installed on your Mac:

Open Keychain Access.
Select Certificates at the top of the window.
In the sidebar, choose System Roots.
You will then see the complete list of root certificates trusted by macOS.

You’ll notice that there are three different Apple Root CA certificates. Why?

Each X.509 certificate contains detailed metadata defining its cryptographic properties and permitted usage. This includes the key type (such as RSA or ECDSA), the public key length, and the signature algorithm used.

Apple Root CA: Is a RSA type, with a public key length of 2048 bits that uses the SHA-1 algorithm.
Apple Root CA-G2: Is a RSA type, with a public key length of 4096 bits that uses the SHA-384 algorithm.
Apple Root CA-G3: Is a ECDSA type, with a public key length of 384 bits that uses the SHA-384 algorithm.

Intermediate Certificates and the Chain of Trust

Root certificates are highly valuable and sensitive, so they are rarely used directly to sign end-user certificates (also called “Leaf” certificates). In the case of macOS app development, the developer’s certificate is the Leaf. This is where Intermediate Certificates come into play.

In simple terms, Intermediate Certificates are signed by Root Certificates and, in turn, are used to sign Leaf certificates. This protects the Root certificate from direct exposure. Together, the Root, Intermediate, and Leaf certificates form what is called the “Chain of Trust.”

The Chain of Trust verification starts with the Leaf certificate and works upward through the Intermediate to the Root. This same process occurs whenever you visit a secure website, make an online payment, or transmit sensitive data securely.

For example, the Leaf certificate is validated against its Intermediate certificate. If the Intermediate certificate is missing or expired, the Leaf certificate is considered invalid. Similarly, the Intermediate certificate itself must be validated against the Root certificate. If the Root certificate is missing or expired, the Intermediate is invalid, and all Leaf certificates signed by it are also invalid.

The same process happens when you sign your macOS apps: macOS validates the entire certificate chain before allowing the app to run.

Finally, certificates closer to the Root generally have longer validity periods. Leaf certificates must be renewed more frequently, while Root certificates are valid for many years.

Wrapping up

In this first article, we covered the fundamentals of digital certificates and their role in macOS app security. In the next article, we will focus specifically on Apple Developer certificates and how they enable trusted app distribution.

Code Signing on macOS: What Developers Need to Know

How to Publish macOS and iOS Apps to the App Store Directly from Xojo

Javier Menendez — Tue, 25 Mar 2025 15:34:03 +0000

Starting with Xojo 2025r1, you can publish macOS and iOS apps to App Store Connect directly from the Xojo IDE. Keep reading to learn how!

App Store Connect is where developers create app records as part of the process to make their apps available on the Mac App Store and/or iOS App Store. All apps must go through Apple’s review process for approval. Once an app record exists in App Store Connect, every new app build uploaded from the Xojo IDE will be available there!

First Things, First

Before exploring how to use Xojo’s new Publish feature, let’s review the requirements and previous processes to better understand how it works.

You may have already met these requirements, but it’s always a good idea to review them.

A paid Apple Developer membership (approximately US $99/yr).
Xcode installed on your Mac, preferably the latest version (Xcode 16.2 at the time of writing, which requires macOS Sequoia 15.2). However, Xojo also works with Xcode 13 or later, such as on macOS Ventura.
The following certificates are present in your Mac’s Keychain:
- Developer ID Application
- Apple Distribution
- 3rd Party Mac Developer Installer
An explicit App ID (Identifier) has been created for your app at developer.apple.com.
A Provisioning Profile has been created at developer.apple.com to ensure the uploaded build is available for testing via TestFlight.
No pending agreements are waiting for your approval at both developer.apple.com and appstoreconnect.apple.com.

Handling Certificates

The best way to ensure you have the correct certificates installed in your Mac’s Keychain is to manage them directly from Xcode. Open Xcode, go to Preferences > Accounts, and make sure you are signed in with your developer.apple.com credentials.

Next, click the “Manage Certificates…” button. A new window will appear, displaying the installed certificates—including expired ones or those missing a private key. From here, you can also download any missing certificates.

Once the required certificates are installed on your Mac, I recommend opening the Keychain app to remove any revoked, expired, or incomplete certificates (those missing a private key) to keep your Keychain clean and organized.

Handling App ID

The App ID, Identifier, or ‘Bundle Identifier’ is something you should be familiar with whenever you create a new macOS or iOS app in the Xojo IDE.

You also need to create the same App ID at developer.apple.com. Log in to the Apple Developer portal using your Apple Developer credentials, then click “Identifiers” under the “Certificates, IDs & Profiles” section.

Note: Keep in mind that you must create a new App ID and follow these steps for each macOS or iOS app you want to distribute through the Mac or iOS App Store.

On the page displayed after the previous step, click the “+” button next to the “Identifiers” header to register a new Identifier.
On the next page, ensure that “App IDs” is selected, then click “Continue”.
On the following page, select “App”, then click “Continue” again.
Now, you’ll reach the most important step—entering the explicit Bundle ID. Make sure it exactly matches the “Application Identifier” used when creating the project in the Xojo IDE.
Also, verify that the App ID Prefix matches the Team ID of the certificates installed in your Mac’s Keychain via Xcode.
Select any Capabilities and/or App Services your app requires. (For this example, none are selected.)
Click “Continue” to proceed to the summary page, where you can review all the entered details and selected Capabilities/App Services.
If everything looks correct, click “Register” to finalize the process.

Once registered, the new Identifier will appear in the list under the “Identifiers” section.

Handling Provisioning Profiles

TestFlight is an Apple service that allows developers to gather feedback from users and teammates while an app is still in development, before it becomes publicly available on the Mac or iOS App Store. When a new app build (version) is published from the Xojo IDE, it will also become available through TestFlight.

However, for this to work, the app must have a “Provisioning Profile” embedded. This profile needs to be created on the “developer.apple.com” website, as we did in the previous “App ID” section.

There are two main types of provisioning profiles: “Development” and “Distribution.” The key difference is:

“Development” profiles specify which devices an app can be installed on. They are primarily used for internal testing on user devices or, in the case of iOS apps, for running tests on a physical device using the “Run On Device” option in the Xojo IDE.
“Distribution” profiles are used for submitting apps to the App Store or making them available for TestFlight testing.

In this example, we will focus on creating a “Distribution Provisioning Profile” to ensure that apps published from the Xojo IDE are eligible for TestFlight testing.

Log in to “developer.apple.com” and navigate to the “Certificates, IDs & Profiles” section.
Select “Profiles” and click the “+” button next to the “Profiles” header.
On the next page, under the “Distribution” section, select “Mac App Store Connect” if you are creating a profile for a macOS app. For iOS apps, choose “App Store Connect” instead. Click “Continue.”
Select the “App ID” you previously created. Notice that the App ID is prefixed with the “Team ID” from when the App ID was created (e.g., “BW7PU32485”).
Under “Profile Type,” make sure the “Mac” option is selected instead of “Mac Catalyst.” Click “Continue.”
On the next page, select the same “Distribution” certificate that will be used when building the Xojo app (i.e., the “Apple Distribution” certificate installed on your Mac). Click “Continue.”
Give the Provisioning Profile a meaningful name so you can easily distinguish it later from other profiles. Click “Generate.”
After a few seconds, the Provisioning Profile summary page will appear with a “Download” button. Click it to download the profile.

NOTE: Provisioning Profiles for iOS
For iOS apps, you need to create both “Development” and “Distribution” provisioning profiles.

When creating the “Development” provisioning profile, be sure to include all registered devices you want to use for installing and testing the app directly from Xojo (using the “Run On Device” option in the IDE).

Once these provisioning profiles are downloaded to your Mac, double-click on them to ensure Xcode installs them in the correct location (as of this writing: “Library > Developer > Xcode > User Data > Provisioning Profiles”).

Adding the Distribution Provision Profile to your Xojo Project

Move the downloaded macOS Distribution Provisioning Profile to a more convenient location related to your Xojo project, and rename it to “embedded.provisionprofile”.

Next, open your Xojo project and add a new “Copy Files” step:

Right-click (or use the contextual menu) and choose “Add to ‘Build Settings’ > Build Step > Copy Files”.
Select the “macOS” item under “Build Settings.”

Next, click the “Add File” button in the “Copy Files” toolbar and select your “embedded.provisionprofile” file.

In the associated “Inspector” panel, use the following values:

Name: Distribution Profile
Applies To: Release
Architecture: Any
Destination: Contents Folder

NOTE: For Xojo iOS projects, provisioning profiles are applied automatically when building or publishing the app. This happens based on the profiles installed by Xcode when you double-click them after downloading from developer.apple.com.

App Store Connect: Creating the Record for the App

You need to create an App Record for every macOS or iOS app that will be distributed through the Mac or iOS App Store. To upload an app from the Xojo IDE, it is not necessary to complete every required field in the various sections right away—you can do that at your own pace. However, you must at least have an App Record created for the app.

To do this, log in to “appstoreconnect.apple.com” using your developer credentials. Once logged in, select the “Apps” icon. On the next page, click the “+” button and choose “New App” to create a new App Record. The previous action will open a dialog where you need to enter the essential app information required to create the record.

Platforms: Select “macOS.”
Name: Enter the same name used in your Xojo project for the app (Build Settings > macOS > Mac App Name). Apple can be strict about this during the app review process if the names differ, as this will also be the name displayed in the App Store listing.
Bundle ID: Select the App ID you created for the app by following the steps in the “Handling App ID” section.
SKU: Enter any arbitrary SKU value that makes sense to you for uniquely tracking this app.
User Access: If you are a solo developer, the choice doesn’t make much difference. However, if you are part of a team, selecting “Limited Access” allows more control over which team members can access the app.

Once you are confident with the information provided, click the “Create” button to generate the new app record.

If you receive an error stating that another app has already been registered with the same name, you will need to choose a different name for your app.

NOTE: Values such as the App Name and Bundle ID can be changed later, if needed, from the “General > App Information” section on the App Record page.

Once the App Record has been created, there will be a lot of required information to fill in before the app can go through the App Store Review Process and be publicly listed in the Mac/iOS App Store upon approval. However, as mentioned earlier, you can add this information at your own pace. The most important thing right now is that, once the record is created, you have everything set up to start uploading your app builds (versions) from the Xojo IDE.

Publishing Mac Apps From Xojo

General Information

Open your Xojo project in the IDE and go to Build Settings > macOS. Then, make sure the correct values are set in the associated Inspector Panel for the following fields:

Mac App Name: This should match the name entered for the App Record on appstoreconnect.apple.com.
Bundle Identifier: This should match the App ID created for the app.
Category: Select the category that best fits your app from the available options.

App Store Connect Setup

To allow the IDE to upload the app to App Store Connect, you need an app-specific password. You can add it by clicking the App Store Connect > Setup button. If you have already created this app-specific password in a previous version of Xojo (under Build Settings > Sign > Notarization > Setup), you don’t need to do it again. Also, keep in mind that this setup only needs to be done once for all your Desktop (macOS) and iOS projects.

Signing and Sandboxing

Select Build Settings > macOS > Sign in the project browser in order to access the associated Inspector Panel:

Developer ID: Type (or paste) the full string from the Apple Distribution certificate installed on your Mac. In this example, it is: “Apple Distribution: Francisco Javier Rodriguez Menendez (BW7PU32485)”. This certificate should match the one selected when the Distribution Provisioning Profile was created, and the Team ID (the value in parentheses) should match the one used when the App ID (Identifier) was created for the app at developer.apple.com.
Sandboxing: Apps uploaded to App Store Connect require Sandboxing to be enabled. Turn on this option and click the associated “Edit” button to enable the necessary sandboxed features for your app. In our example, we only enabled the ability to read/write the selected user files.

Shared Settings

Select Build Settings > Shared in the project browser to access the associated Inspector Panel:

If you are going to publish the final (release) version of your app after it has been thoroughly tested, you will likely want to set the Stage Code value to “Final.” Additionally, make sure to enter the short version string in the Version field and the copyright information for the app in the Copyright field.

NOTE: Did you forget something? Every time you click the Publish button (or select the equivalent “Build and Publish to App Store Connect” menu item from the Project menu), the IDE will run a “checklist.” If something needs to be set in the IDE before uploading the app to App Store Connect, any errors will be shown in the IDE’s Error Panel, pointing out “what” needs to be fixed and “where” to make the changes.

App Icon

Nothing new here, apart from building your macOS app for regular or “web-based” distribution. Your app needs an icon in the required sizes. However, when it comes to publishing to the Mac/iOS App Store, this requirement is even more strict. Xojo will catch this before starting the app building process to save you time spent on compilation and uploading. So, make sure you add all the required icon sizes by selecting the App item in the project browser, then clicking the Appearance > Icon option in the associated Inspector Panel.

That action will open the Icon Editor, where you can drag and drop the different icon files for each size or paste them directly from your preferred image editor.

Publishing!

Click the Publish button. Once the “checklist” passes without any errors, a confirmation dialog will appear. Click the “OK” button to begin the process and upload your app’s new build to App Store Connect.

If everything goes smoothly, you will see a “Success” dialog at the end of the process. However, if there is an error during any of the steps, an error message dialog will provide more details about the issue, and the process will be interrupted, returning you to the IDE.

In either case—whether your new app build was successfully uploaded to App Store Connect or not—you can find the generated Log file in the same folder as the built app. If there are errors, you can open the Log file to review the information about the issue(s), which will help you resolve them before trying again. For example:

2025-01-23 12:54:35.030 *** Error: [ContentDelivery.Uploader.6000028E01C0] The provided entity includes an attribute with a value that has already been used (-19232) The bundle version must be higher than the previously uploaded version: ‘1.0.6’. (ID: d422b9bf-049f-4263-af43-8357c2fe5f00)

In this case, the Log file entry indicates that we tried to publish a build with the same version number as an already uploaded build on App Store Connect. If this new build includes changes or new features, the way to fix this issue is simply by increasing the version number (and the short version string) before publishing it.

Testing with TestFlight

When you create a new app record in App Store Connect and access it, one of the tabs at the top of the page is named “TestFlight.” Click on it, and you will see all the uploaded builds of your app that are eligible for testing.

As you can see, there is a warning icon next to the app build we just uploaded (A). This is because Apple requires additional information from you regarding the app’s compliance with Encryption Export Regulations. To provide this information, click the associated “Manage” link to access the dialog where you can make your choice about it.

TIP: Use the new Property List Editor in Xojo’s IDE and add the following Key/Value pair to avoid manually going through the Encryption Export Regulations compliance process:

Key: ITSAppUsesNonExemptEncryption

Value: False

Once the requirement has been completed, the build status will change to “Ready to Submit.” As you can see, it also indicates that this build will be available to your testers for the next 90 days before expiring. This should be enough time before you send new test builds to them, anyway.

For each of your apps, you can create as many tester groups as needed. By default, there is only one entry: “Internal Testing.” You can create additional groups and add any members of your Apple Development Team to the groups you create. Click on the “+” icon to create your first group.

Give the new group a name and uncheck the “Enable automatic distribution” checkbox. Then, click the “Create” button.
Once the new internal testing group is created, you will be able to assign any uploaded (and not expired) builds of your app to it. You can also add members to the group (remember, these should be members of your Apple Developer Team!).

However, having internal testing groups might not be very helpful if you are a solo developer or part of a small team. The good news is that once you create the first, mandatory internal group, a new option will be added to the TestFlight sidebar.

External Testing

In this case, you will be able to invite up to 10,000 members to test your app. The main difference compared to internal groups is that once you select a build to be tested in any of the external groups, it must go through the Beta App Review process. This means the build won’t be immediately available to your testers until the review is complete. However, this process is only required for the first build—subsequent builds will be available immediately, just like in internal groups.

When inviting members to an external group, you have several options: you can create and share a public link, manually add testers, or even import them from a .csv file.

In any case, your testers will be able to download, install, and begin testing your app, as well as provide feedback!

In Summary

The new Publish feature simplifies the process of submitting your macOS and iOS apps to App Store Connect, making them available on the Mac App Store and iOS App Store directly from the IDE, without needing any external apps (such as Transporter).

Provisioning Profiles for macOS Apps

Javier Menendez — Thu, 30 Jan 2025 15:22:00 +0000

Continuing our series on distributing Mac apps, this post will take you through properly setting up a provisioning profile, which is required for your apps to get tested by others in TestFlight. To review or catch up on earlier steps in this process, see my posts on Sandboxing, Hardened Runtime and Notarization arrives to the Xojo IDE, macOS Apps: From Sandboxing to Notarization, The Basics and Uploading macOS Builds to App Store Connect. But if you have those steps done, let’s set up the provisioning profile you need.

Development or Distribution

There are two types of provisioning profiles: Development and Distribution. Development provisioning profiles are for builds sent to the AppStore Connect service that are not meant to be available on the Mac App Store. Development profiles allow apps to be tested by the eligible users associated with that app in TestFlight. For Development provisioning profiles, set the Stage Code value (under Build Settings > Shared) to “Development”, “Alpha” or “Beta”.

On the other hand, Distribution provisioning profiles for macOS are required for builds meant to be publicly available on the Mac App Store once approved by the App Store Reviewing Process, they are also available for TestFlight. For Distribution provisioning profiles, make sure the Stage Code value is set to “Final” under Build Settings > Shared.

Creating Provisioning Profiles

Regardless of which type of provisioning profile you are creating, you’ll need to do it from the Apple Developer website (using your paid developer membership).

In this example we will create a Distribution provisioning profile.

Login into the Apple Developer Website.
Select the Profiles option found under the “Certificates, IDs & Profiles” section.
Click on the “+” icon found next to the “Profiles” header.
Next, select the “Mac AppStore Connect” option under the Distribution section, and click on the “Continue” button.

Select the “Mac” option under the Profile Type section, and select the App ID value from those available in the associated Popup menu. Make sure that the chosen one (without the value between parentheses) matches the one entered under Build Settings > macOS > Bundle Identifier. Then, click on the “Continue” button.

For example the selected one in the screenshot (that, is BW7PU32485.com.aprendexojo.vcardtoqr), matches the one used as the Bundle Identifier for the app in the Xojo IDE (com.aprendexojo.vcardtoqr).

Next, select the “Distribution” Certificate to be included in the generated provisioning profile. The one selected must be the same one entered in the Developer ID field when building the App from the Xojo IDE (Build Settings > macOS > Sign). For example, I’m going to use the value (without the quotes) “Apple Distribution: Francisco Javier Rodriguez Menendez (BW7PU32485)” as the Developer ID value in Xojo, so I’m selecting that same Distribution certificate here. Next, click the “Continue” button.

Name the provisioning profile using a significative name, so you can easily distinguish it later among the many available ones. Next, click the “Generate” button so the provisioning profile is generated and downloaded to your local Mac disk (probably in the Downloads folder).
The downloaded provisioning profile will have the name you entered in the previous step. Select it and use the Finder options to rename it as “embedded.provisionprofile”.

Adding the Provisioning Profile to the Project

macOS provisioning profiles need to be added to the Contents folder on the app bundle, and that is easy to do from the Xojo IDE!

Open your project in the Xojo IDE and add a new Copy Files build step under Build Settings > MacOS.
Add the “embedded.provisionprofile” file to the just added CopyFile build step.
Select the “Contents Folder” option from the Destination popup menu in the associated Inspector Panel for the Copy Files build step.
Select the “Release” option from the “Applies To” popup menu in the associated Inspector Panel for the Copy Files build step, so only this file is copied to the Contents folder when the app is built as a standalone app.

Adding New Entries to the Entitlements File

In order for the provisioning profile to be recognized by TestFlight when the app package is sent to AppStore Connect, we need to add a couple more entries to the Entitlements file (see “Uploading macOS Builds to App Store Connect” for more details on the Entitlements file).

Full Application Identifier. Use the “com.apple.application-identifier” as the Key for the entry. The value should be the Application Bundle Identifier (in our example com.aprendexojo.vcardtoqr) prefixed with the Team ID value of the Certificate we used both for signing our app and the provisioning profile itself. In this example it is BW7PU32485, making the string value for this key BW7PU32485.com.aprendexojo.vcardtoqr
Team ID. Use “com.apple.developer.team-identifier” as the Key for the entry, while the value (following with our example) is just the Team ID from the certificate: BW7PU32485

All in all, the final Entitlements file will look like this:





	com.apple.security.app-sandbox
	
	com.apple.security.files.user-selected.read-write
	
	com.apple.application-identifier
	BW7PU32485.com.aprendexojo.vcardtoqr
	com.apple.developer.team-identifier
	BW7PU32485

That is: Sandboxing enabled, plus the ability for the app to read/write the selected user files, plus the two new entries required so the provisioning profile is recognized by TestFlight when the package is submitted to the AppStore Connect.

Save the changes to the modified Entitlements file (in our example named as “myEntitlements.entitlements”).

Resign, Re-Package, and Uploading

If you followed the two previous blog posts in this series, you may have already guessed the next step! Yep, because we modified our “myEntitlements.entitlements” file, we need to re-sign the app bundle, package it and submit it to AppStore Connect.

So for re-signing, type the following in a new Terminal window:

codesign --force --timestamp --entitlements path-to-your-myEntitlements.entitlements-file  -s "Apple Distribution: whatever-name-you-use (BZXXXXXXX)" path-to-the-bundle-of-the-compiled-app.app

In order to create a package from the bundle, issue this command from the Terminal:

productbuild --sign "3rd Party Mac Developer Installer: whatever-name-you-use (BZXXXXXXX)"  --component path-to-the-bundle-of-the-compiled-app.app  /Applications path-to-the-generated-package-file.pkg

And in order to upload the package to the AppStore Connect, type the following command in a Terminal window:

xcrun altool  --upload-package path-to-the-package-file.pkg -u your-apple-developer-login-id-goes-here -p "your-app-specific-password-goes-here" --type osx -apple-id "6111111111" --bundle-id "com.yourcomany.yourIdentifier" --bundle-short-version-string "current-short-value" --bundle-version "current-version-value"

If everything went OK, open your Internet Browser and go to http://appstoreconnect.apple.com, select your app record from the Apps section and click on the TestFlight tab. You should be able to see the just submitted build ready for testing!

In Summary

As you see, adding provisioning profiles to macOS apps sent to the AppStore Connect website to be tested by in TestFlight, requires a bit of previous preparation for the provisioning profile generation itself, copying the file to the project using a Copy Files build step and, then, adding a couple more entries to the Entitlements file.

Once everything this is done, your testers will be able to use the TestFlight app to download and test your builds and report feedback, crash reports and other information about it!

More in this series on distributing Mac apps:

Uploading macOS Builds to App Store Connect

Javier Menendez — Tue, 14 Jan 2025 20:53:32 +0000

Since Xojo 2024r4 the IDE includes the ability to automatically compile macOS apps with Sandboxing, Hardened Runtime and Notarization. Continue reading to learn that extra step in order to submit the created bundle directly to the App Store Connect website!

There is a Xojo-made tool out there that can simplify the process, and if that’s your route, check out AppWrapper from Ohanaware. But if you are the kind of developer that enjoys “how things work under the hood”, then follow these steps to do it manually from the command line (or convert these instructions into Xojo Scripts that can be executed as part of the build process itself from the Xojo project).

There are some requirements for all of this to work, but you took care of them already if you already followed our previous post about how to apply Sandboxing, Hardened Runtime and Notarize manually to your Xojo macOS builds. Perhaps, the most important one is that this requires a paid Apple Developer Program membership (around US $99/yr). Additionally, Xcode needs to be installed on your Mac in order to use its included altool and productbuild command line tools. Create an app-specific password in order to execute the notarytool command line tool, which is also required when using the altool command line. You likely created one already for the notarytool command line tool which you can use as the password required by the altool command line tool.

If distributing your macOS apps from your website, these need to be signed using the “Apple Development” Certificate, but if you are compiling a macOS app for distribution through the Mac App Store, you need to sign it using the “Apple Distribution” certificate. So make sure to fill-in the macOS > Signing > Developer ID field properly.

Also important, in order to upload the app to App Store Connect, you need to create a package file from the app bundle, and that package file (.pkg) needs to be signed using the “3rd Party Mac Developer Installer”. Make sure you have this certificate installed in your Mac Keychain.

First things … First

Before you can upload you .pkg file to the App Store Connect website, there are some things you need to take care of that are required by Apple for apps to be distributed through the Mac App Store.

The first thing is to register an App ID (or Identifier) in the Apple Developer Portal. When doing it, make sure you are creating an explicit Identifier instead of a wildcard one. Also very important, make sure that the identifier (in the reversed DNS form) is the same one you are using in the field macOS > Build > Bundle Identifier of your Xojo project. If they don’t match, then you can expect errors throughout the process.
The second thing is to create a new record for the App itself in the App Store Connect website. This is the place where you need to provide all the information requested by Apple for two main things: 1. what will be available as the app information when the users reach your app in the Mac App Store (for example product description, price, images, etc.), and, 2. what is for internal and compliance use. All in all, make sure you create a new macOS app record and go through all the available sections to fill in the requested information.

Once these two steps are completed, we can focus on the command line itself to create the .pkg file and upload it manually (optionally, it is possible to use the Transporter app to select the .pkg file and upload it).

Sing, sing, sing … the re-signing song!

When building the macOS app from the Xojo IDE, it will be correctly signed based on the settings selected in the Build Settings > Sign section. But because of the way Apple requires some entries to be formatted (specifically those for the CFBundleShortVersionString and CFBundleVersion keys), and the fact that it also requires the LSApplicationCategoryType key to be present in the Plist file with the associated value (the app category value among those you can find here), we need to manually edit the generated Info.Plist file for the compiled app.

Yeah, sure we can create an additional text file named Info.Plist file with the appropriate/expected keys and values and drop such file in the IDE navigator for our project so this information gets added/modified, as for example this one:




	CFBundleShortVersionString
	1.0.0
	CFBundleVersion
	1.0.0
	LSApplicationCategoryType
	public.app-category.business

The bad news is that the value for the CFBundleVersion key will not be replaced with the one from our Info.Plist file.

What’s the downside of manually editing the Info.Plist file for the already compiled app? Well, as soon you make a change and save it, the app bundle signature will be invalidated. But no fear! We know how to do it already, right? If not, I suggest you to take a look to the blog post about Sandboxing, Hardened Runtime and Notarization for macOS apps that I mentioned earlier.

Go ahead, select your compiled app in the Finder, click on its icon and select the option “Show package Contents” from the contextual menu. This action will show the “inner files” of the bundle that composes your app. Inside the Contents folder you will see the Info.Plist file. Click on it and select the option from the contextual menu allowing you to edit it with the text editor of your preference (mine is to use BBEdit from BareBones Software).

Locate the CFBundleVersion key entry and change its string value so it doesn’t have more than three numbers separated by the dot character (as shown in the previous Plist example file).
Locate the CFBundleShortVersionString and change its string to make sure it has three version numbers separated by the dot character.

Of course for both of the previous keys, make sure these match your expected version numbers for the app! In the example I used 1.0.0 as it’s typical for the initial release of an app.

Next, add the expected LSApplicationCategoryType key with the value that better fits your app among those available at the Apple Documentation website. In the previous Plist file example I’m using the one for the Business category:

	LSApplicationCategoryType
	public.app-category.business

Save the changes to our modified Info.Plist file. Now it is time to sign it again!

What about the Entitlements?

Heh… wait! Because we need to re-sign our app bundle again, we also need to attach the expected entitlements to it! That means at least one very-important-and-required entitlement: enabling Sandboxing, which needs to be done to any app sent for distribution through the Mac App Store.

While Xojo 2024r4+ is able to do it automatically when building the app, now we also need to do it manually. That means creating our own .entitlements file that will be used when re-signing the app. For example, for a very typical (and bare-bones) app that only needs to read and write files it would look like this:




	com.apple.security.app-sandbox
	
	com.apple.security.files.user-selected.read-write

Save it as “myEntitlements.entitlements” to your Mac drive. Of course, if you app requires more entitlements, go ahead and add them to the previous “template” .entitlements file.

We now have our modified .Plist file and the required .Entitlements file… so we have everything we need to re-sign the app bundle again!

Open a Terminal window and type the following command:

codesign --force --timestamp --entitlements path-to-your-myEntitlements.entitlements-file  -s "Apple Distribution: whatever-name-you-use (BZXXXXXXX)" path-to-the-bundle-of-the-compiled-app.app

Look how we are using the reference to the entitlements file, and the “Apple Distribution” certificate instead of the “Apple Development” certificate.

Packaging Acme

So far so good. We have our app bundle signed again, so we are ready now to create a .pkg file from it! All you need to do is to type the following command from a Terminal window:

productbuild --sign "3rd Party Mac Developer Installer: whatever-name-you-use (BZXXXXXXX)"  --component path-to-the-bundle-of-the-compiled-app.app  /Applications path-to-the-generated-package-file.pkg

As you can see, we are using the “3rd Party Mac Developer Installer” certificate in order to create the package file.

Uploading it!

With the package file already created, we now have all we need to upload it to the App Store Connect website. At this point you can follow two paths. The first one is to use the Transporter App that you can download from the Mac App Store itself. In that case:

Open the Transporter app.
Click on the “+” icon. That action will bring a dialog where you can select the previously created .pkg file.
Once it is added, Transporter will make some early checks on the package contents. If everything goes OK, you should see something like this:

The interesting thing about using Transporter is that you can select the “Verify” option from the associated contextual menu (the one with the three dots icon). That action will start some more deeply checking on the package (and its contents) so you can get some early information about things that need to be fixed prior uploading it to the App Store Connect Website. For example, this error generated when the bundle version is duplicated:

The second option involves using the aforementioned altool command line to automatically upload the package to the App Store Connect website. If you choose this path, all you need to do is to execute the following command from a Terminal window:

xcrun altool  --upload-package path-to-the-package-file.pkg -u your-apple-developer-login-id-goes-here -p "your-app-specific-password-goes-here" --type osx -apple-id "6111111111" --bundle-id "com.yourcomany.yourIdentifier" --bundle-short-version-string "1.0.0" --bundle-version "1.0.0"

Some considerations about the provided options/values for this command:

-u: This is the login name you use when accessing the Apple Developer website
-p: This is the app-specific password you created from scratch following the steps provided in the aforementioned blog post.
-apple-id: This is the numeric value you can find under General > App Information at the appstoreconnect.apple.com website for the record created for this app:

This information can also be retrieved using:

xcrun altool --list-apps -u your-apple-developer-login-id-goes-here -p "your-app-specific-password-goes-here" --output-format json

–bundle-id: Make sure to provide the same value as the one used when creating the Identifier for the App and, thus, the same one used under Build Settings > macOS > Build > Build Identifier field in your Xojo project.
–bundle-short-version-string: Make sure it’s the same value used for the CFBundleShortVersionString key in the .Plist file.
–bundle-version: Make sure to provide the same value as the one used for the CFBundleVersion key in the .Plist file.

Once the command is executed, your package file will be uploaded to the App Store Connect website and, once completed, eligible as a new Build to be added to your app record so you can send it to review as part of the Apple reviewing process.

In Summary

There are several details to take care of, but Xojo has simplified the process of covering the “last mile” of sending you compiled app for review at the App Store Connect website.

More in this series on distributing Mac apps:

macOS Apps: From Sandboxing to Notarization, The Basics

Javier Menendez — Thu, 22 Aug 2024 15:45:28 +0000

You are likely already familiar with terms like Sandboxing, hardened runtime and Notarization. After all, these are required if you plan to distribute your macOS apps through the Mac App Store. But, starting with macOS Sequoia 15 (expected in the fall of 2024), Apple has tightened the runtime security protections even more. For example, it was common to Control + click on any downloaded macOS app from Internet that has not been signed and simply choose the Open option from the contextual menu to open it. That won’t be an option under Sequoia (although it still possible to run the unsigned app).

In fact, Apple recommends to Notarize the software even if you are going to distribute it from your own website, outside of the Mac App Store. But, don’t be scared! Currently there are good third parties options available that ease the path, like App Wrapper from Ohanaware, or some OpenSource options as for example Xojo2DMG; and through this article you will see how to enable Sandboxing, runtime hardening and even Notarizing on a simple example app. Of course, this will touch only the basics and it is up to you to read the related Apple Documentation to add the entries, both the Entitlements and additional keys/values in the app Info.plist file, required by the purposes of your particular app, for example file access, camera or mic access, network access, etc.

A Bit of Common Ground

At this point, your head may be spinning if you are unfamiliar with these app security terms; so, what do Sandbox, hardened runtime and Notarizing mean when they are applied to macOS apps?

Sandboxing

When a macOS app is sandboxed, that means that macOS will create an exclusive container for everything related to the app the first time it is launched. This is what happens when installing an iOS app, too! Such a container will have its own structure to access things like documents, pictures, downloads, etc. Think about it as the own private execution space for the app:

Of course, there are entitlements waiting for you so your sandboxed app can access the files created by other apps (including the Desktop, Downloads, Movies, Music and Picture folders), among other things.

Hardened Runtime

When enabled for your macOS app, hardened runtime adds an extra layer of protection to the running code itself. For example, it prevents certain classes of exploits, like code injection, dynamically linked library (DLL) hijacking, and process memory space tampering. This kind of protection is also enhanced by the System Integrity Protection (SIP).

Notarization

In brief, this is a third layer of confidence for the potential users of your macOS app. When the app is notarized, that ensures to the user that the Developer ID-signed software you distribute has been checked by Apple for malicious components. This is not related with the Apple Review process of your app when it is submitted to the Mac App Store, it’s related to the macOS Gatekeeper technology. So, when a Notarized app is downloaded from Internet, for example, Gatekeeper will use the notarization ticket attached to your app/DMG file to provide more meaningful information about the origin of the app, including if it is safe for the user to open it.

Preparation

In order to follow this article, you will need:

Xojo. Download it for macOS if you have not done yet.
macOS 11.3 or later.
Xcode 13 or later. Run it at least one time and make sure that all its required components and SDKs are installed.
Apple Developer ID. This needs to be a paid Apple Developer membership. Also, make sure you have your Developer certificates installed in the Mac.
A working Internet connection.

With all of this in place, open Xojo to create a macOS Desktop project and do some basic layout in the by default window. It is not required to add any functionality to keep the focus in the task at hand. Then, use Build Settings > macOS > Mac App Name to give an appropriate name to the built application (for this example I named it “SandboxedApp”).

Lastly, save the project (for example into the Documents folder) and click the Build button to build the app! It is not required at this point to assign the Developer ID in the Build Settings > macOS > Sign section, because we are going to sign it (again) in the next steps.

Creating the Entitlements File

The entitlements file is pretty similar to the Info.plist file you probably already know that is in charge of storing the required keys and values for the app to properly work. Both of these are in XML format, and the only difference is that while the Info.plist file is created for you by Xojo, the Entitlements file needs to be, currently, manually created for you.

So, open your text editor of choice (there a lot of there out there, both free and paid ones; personally I tend to use BBEdit from BareBones Software). Add the following lines to the text document and save it with the name “Entitlements.plist” (if you keep it next to the saved built macOS app, the better). This is the file where you will probably want to add more entitlement entries as your app requires them:





  com.apple.security.app-sandbox

Sandbox Your App

With the compiled app and the entitlements file in place, open the Terminal app and type the following command and press the return key:

> codesign --force --deep --timestamp --entitlements  -s "Developer ID Application: "

Once executed, run the “SandboxedApp”, open the Activity Monitor app and make sure that the Sandbox option is enabled under the View > Columns options. Then, use the search box of the main window to filter the displayed processes so it only displays your app. Take a look to the value under the Sandbox column and you will see that the app is now Sandboxed, and the Container for it has been created under the Library/Containers path. Quit the app when you are done.

Hardened Runtime

With our app already sandboxed, let’s look how to add the hardened option to it. Once again, type the following command in the Terminal prompt:

> codesign --force --deep --options runtime --timestamp --entitlements  -s "Developer ID Application: "

As you can see, it doesn’t vary much from the previous command. All it adds is the “–options runtime” text in charge of enabling the runtime hardening. Also, as you might guess, using this command will enable the Sandboxing of the app and also the runtime hardening, at all once.

Do you want to check if it worked? Well, type the following command at the Terminal prompt:

> codesign --display --verbose

It will produce an output similar to this one:

Executable=
Identifier=com.xojo.sandboxedapp
Format=app bundle with Mach-O universal (x86_64 arm64)
CodeDirectory v=20500 size=43297 flags=0x10000(runtime) hashes=1342+7 location=embedded
Signature size=9100
Timestamp=13 Aug 2024 at 12:51:28 PM
Info.plist entries=15
TeamIdentifier=************
Runtime Version=11.1.0
Sealed Resources version=2 rules=13 files=4
Internal requirements count=1 size=184

It is the “flags=0x1000(runtime)” which shows that, in fact, the app runtime is hardened. Congrats!

Notarizing the App

This is the final step, but is going to require an extra step from your side. Because the notarytool command line tool, used for notarizing the app, is going to require the ID and password from your Apple ID account, plus the fact that it uses 2FA authentication, it is very convenient to create an app specific password for it.

Creating an App-Specific Password

In order to create the password used by the notarytool process, follow this steps:

Sign in to appleid.apple.com
In the Sign-in and Security section, select the App-Specific Passwords option:

The previous action will bring a new dialog displaying all the app-specific passwords already created. Click the “+” button to add a new one:

Type a meaningful name for as the “Title” or description for your new password in the presented dialog (notarytool could be a good one):

Once you click the Create button it is possible that you will be asked to authenticate again using your Apple ID. Once done, a new dialog will present the generated password to you. Copy it and write it down (or paste it) into a safe place, because we are going to need it in the next step.

Adding the notarytool specific password to the Keychain

Because this app-specific password is going to be used by the notarytool command line tool, it would be very convenient to have it stored in the macOS Keychain. To do so, type the following command at the Terminal prompt, and press the Return key:

> xcrun notarytool store-credentials "notarytool-password" --apple-id "" --team-id  --password

Once executed, you will be able to see the password added to the Keychain app under the name of “notarytool-password”:

Creating a Zip file for your app

The notarization process is handled by the Apple notary service running in the Internet, what means that notarytool needs to send (upload) the bundle of your app in an appropriate format. There are two options: as a DMG file (that needs to be signed before submitting), or as a zipped file, what is even faster and easier (Trivia: Did you know how easy it is to create Zip files in Xojo code?)

So, in order to upload our app for notarization, we need to create a Zip file first. Once again, it is time to type a new command at the Terminal prompt:

> /usr/bin/ditto -c -k --keepParent

Uploading the app for Notarization

With our Zip file in place, we now have all the pieces to send it to the notarization process. The time spent by that process may (and will) vary depending of several factors.

In order to send the file, type the following command at the Terminal prompt:

> xcrun notarytool submit  --keychain-profile "notarytool-password" --wait

After pressing the Return key, the process will start and the Terminal will output information about the progress; something similar to this:

Conducting pre-submission checks for  and initiating connection to the Apple notary service...
Submission ID received
  id: 
Upload progress: 100.00% (8.65 MB of 8.65 MB)   
Successfully uploaded file
  id: 
  path: 
Waiting for processing to complete.
Current status: Accepted........
Processing complete
  id: 
  status: Accepted

Have you seen the last line? The “status: Accepted” means that everything worked OK, and the notarization process has been successful, but it’s better if we check! Type the following command at the Terminal prompt. This one will ask the notarytool command to download the log file in JSON format to be saved at the desired path. It is a good habit to do it, because such a log file will include some eventual error and explanation about possible errors during the notarization process, including those related to the app itself:

> xcrun notarytool log  --keychain-profile "notarytool-password"

Staple the Ticket!

Assuming that everything worked OK, it is time to staple the notarization ticket to the app itself. It is not required, but is convenient to avoid online checks when the user runs the app, or Gatekeeper inspects it.

Yeah, that means using a new command from Terminal on the already signed, sandboxed and runtime hardened app bundle (not the Zip file you created for submitting using notarytool):

> xcrun stapler staple ""

After that, you can check that everything went OK using the following command:

> spctl -a -vvv -t install

And you should get something similar to this as the output:

source=Notarized Developer ID
origin=

App Distribution

That’s fine, but you will probably want to distribute your app from the Internet using a DMG container. In that case, follow these steps:

Create a DMG container (file).
Copy your already notarized app bundle into it.
Notarize the DMG file.
Staple the ticket to the DMG file.

That way the DMG container will be Notarized along with the app bundle inside it.

In Summary

As we did see, all the process of sandboxing, runtime hardening and Notarization involves a bunch of commands from the terminal, including the creation of the Zip file. But the good news is that all the process could be automated using Xojo itself! (take a look to the Shell class and the Zip method from the FolderItem class if you are not familiar with them).

As I said before, this article only on touches the basics and doesn’t dig into Provisioning Profile creation (associated with Capabilities required by the app), the Entitlements your app may need to properly work, among other topics; so you may find these Apple Developer Documentation of interest:

– Provisioning profiles.
– macOS Entitlements.
– macOS Sandbox.
– macOS Hardened Runtime.
– macOS Notarization.

Happy Xojo Coding!

More in this series on distributing Mac apps:

Software Distribution Simplified with GuancheMOS

Javier Menendez — Tue, 26 Jun 2018 10:00:09 +0000

In an ideal world there is a person responsible for every step in software development, from coding, UI design, distribution, documentation, marketing and support. All of this can seem really overwhelming for independent developers and small businesses. But if you break it down and take it one piece at a time, it’s manageable by even the smallest team of one. Right now, let’s look at software distribution.

For software, distribution usually means generating and validating unique serial numbers for each of your products and users. Serial numbers (or license keys) help you manage your users, unlock a free trial or demo version for full use and, of course, minimize illegal use of your apps.

Let’s admit it, there is no silver bullet. Even the greatest companies (you know who you are) throw lots of money at implementing and improving serious protection schemes that are often quickly bypassed. It comes down to: How much time, money and resources are you willing to spend implementing a protection or licensing scheme?

The bad guys will always find a way to break your software protection if they are interested in doing that. Does that mean giving up on protecting your software? Not at all! When I was faced with the problem myself, in order to protect my own products, I went to the drawing board to build a way to generate unique serial numbers —or licensing information— for all the Xojo supported platforms.

The result of this process was the GuancheMOS plug-in. GuancheMOS is a fully multiplatform plug-in for desktop, web and console apps (not for iOS due to the fact that iOS only can link against static libraries), on 32-bit and 64-bit architectures.

The simplicity of GuancheMOS means that you can use it as is, or as the starting point to build your own private and unique serial number automations. Integrate it as part of the purchase process in your website, wrap it as the core piece of other unique information collection. It’s already used by dozens of developers around the world in ways I hadn’t ever thought of while designing it! The best part, is that implementing GuancheMOS in your product takes about 5 minutes.

You can download and try GuancheMOS for free today.

Javier Rodriguez has been the Xojo Spanish Evangelist since 2008, he’s also a Developer, Consultant and Trainer who has be using Xojo since 1998. He manages AprendeXojo.com and is the developer behind the GuancheMOS plug-in for Xojo Developers, Markdown Parser for Xojo, HTMLColorizer for Xojo and the Snippery app, among others