Échec de notarisation notarytool : checklist 2026

Ce guide s’adresse aux développeurs indépendants qui distribuent une application macOS depuis leur site, dans un DMG, un PKG ou une archive ZIP, plutôt que par le Mac App Store.

Il vise également les mainteneurs d’une automatisation de signature et de publication, ainsi que les petites équipes qui veulent déplacer cette chaîne vers un Mac distant sans perdre l’accès au trousseau, aux certificats et aux journaux de diagnostic.

Ne confondez pas les résultats suivants :

• l’envoi n’a pas terminé ;
• la soumission est encore en cours de traitement ;
• le service a refusé le contenu avec un statut Invalid ;
• le service a accepté la soumission, mais le ticket n’a pas été attaché ;
• le ticket est présent, mais Gatekeeper rejette encore l’artefact local.

Apple présente la notarisation comme une analyse automatisée d’un logiciel signé avec Developer ID. Ce n’est pas une revue éditoriale comparable à une validation de fiche produit. Gatekeeper intervient ensuite, au moment où l’utilisateur ouvre ou installe le logiciel. La signature, la notarisation et la vérification Gatekeeper doivent donc être testées séparément. La documentation Apple sur la distribution macOS décrit cette séparation.

Commencez par conserver l’identifiant retourné par la soumission :

xcrun notarytool submit "/chemin/vers/ARCHIVE.zip" \
  --keychain-profile "PROFIL_TROUSSEAU" \
  --wait \
  --output-format json > "/chemin/vers/notarytool-result.json"

Les valeurs ARCHIVE.zip et PROFIL_TROUSSEAU sont volontairement des espaces réservés. Ne remplacez pas ces exemples par les identifiants d’un autre projet dans un script partagé.

Si vous n’avez pas utilisé --wait, consultez l’état à partir du Submission ID :

xcrun notarytool info "SUBMISSION_ID" \
  --keychain-profile "PROFIL_TROUSSEAU"

Puis téléchargez systématiquement le journal :

xcrun notarytool log "SUBMISSION_ID" \
  --keychain-profile "PROFIL_TROUSSEAU" \
  "/chemin/vers/notary-log.json"

Apple recommande de lire ce journal pour identifier les erreurs et avertissements. notarytool permet aussi de consulter l’historique des soumissions, ce qui est utile pour vérifier une authentification ou comparer deux artefacts sans exposer leur contenu dans la sortie de votre pipeline. Le guide Apple consacré au workflow notarytool détaille les commandes submit, info, log et history.

Les trois états à ne pas mélanger

In Progress signifie que l’analyse n’est pas terminée. Il ne faut pas modifier puis renvoyer immédiatement le paquet, car vous risqueriez de perdre le lien entre le résultat et l’artefact testé.

Invalid signifie que le service a terminé l’analyse et a trouvé un problème. Le journal est alors la source prioritaire. Corrigez le premier problème bloquant signalé, reconstruisez ou resignez l’artefact, puis relancez une soumission.

Accepted signifie que la soumission a été acceptée. Il reste à vérifier l’attachement du ticket avec stapler et le comportement de l’artefact dans les règles locales de Gatekeeper.

Apple indique que la plupart des traitements se terminent en moins de 5 minutes et que 98 % des logiciels sont traités en moins de 15 minutes, tout en précisant que certaines soumissions peuvent prendre davantage de temps. Ces valeurs ne constituent pas un engagement de délai pour votre pipeline. Apple recommande également de limiter les notarisation à 75 par jour. Le workflow officiel de notarisation Apple précise ces limites et ces précautions.

Le premier contrôle porte sur le type de certificat, pas seulement sur la présence d’une signature.

Pour une distribution hors Mac App Store, Apple distingue notamment :

• Developer ID Application pour signer l’application, les frameworks, les plug-ins, les services XPC et les exécutables ;
• Developer ID Installer pour signer un paquet d’installation PKG ;
• un horodatage sécurisé inclus dans la signature de distribution.

Un PKG peut donc contenir une application correctement signée tout en échouant parce que le paquet lui-même n’est pas signé avec la bonne identité. À l’inverse, un DMG ne remplace pas la signature de l’application qu’il contient. La page Apple sur les certificats Developer ID précise le rôle de ces deux identités.

Inspectez l’identité effectivement utilisée :

security find-identity -v -p codesigning

Puis vérifiez l’application exportée :

codesign -dv --verbose=4 "/chemin/vers/APP.app"

Contrôlez en particulier :

• le type d’identité affiché ;
• l’équipe associée ;
• la présence d’un horodatage ;
• l’identifiant de bundle ;
• la présence éventuelle d’un profil de provisioning adapté.

Pour une vérification stricte de l’application et de son contenu imbriqué :

codesign --verify --verbose=4 --deep --strict \
  "/chemin/vers/APP.app"

Pour un PKG :

pkgutil --check-signature "/chemin/vers/INSTALLATEUR.pkg"

Apple indique que codesign est l’outil approprié pour diagnostiquer les signatures d’une application, tandis que pkgutil --check-signature permet d’examiner la signature d’un installateur. Un message concernant une signature invalide, une modification après signature ou une identité Developer ID absente doit être traité avant toute nouvelle tentative de notarisation. La documentation Apple sur les problèmes courants de notarisation fournit ces contrôles.

Les indices typiques dans le journal

• Identité incorrecte : le journal indique que le binaire n’est pas signé avec un certificat Developer ID valide.
• Clé privée absente : la signature ne peut pas être reproduite après migration vers un autre Mac, même si le certificat public est visible dans le trousseau.
• Contenu modifié après signature : le journal ou codesign --verify signale une signature invalide.
• Horodatage manquant : la chaîne de signature peut être rejetée ou devenir fragile lors de la vérification.
• Composant oublié : l’application principale semble correcte, mais un framework, un helper ou un outil en ligne de commande porte encore une signature de développement.

Un certificat visible dans l’interface du trousseau ne prouve donc pas que la chaîne complète est exploitable. Vérifiez aussi la présence et l’accès à la clé privée, notamment après une restauration de machine, une rotation de certificat ou une installation sur un Mac distant.

Activer le Hardened Runtime est nécessaire pour la notarisation, mais ce réglage ne rend pas automatiquement toutes les fonctionnalités compatibles.

Le problème apparaît souvent dans l’un de ces trois cas :

1. l’entitlement est mal écrit ou mal encodé ;
2. l’entitlement est présent alors que l’application n’en a pas besoin ;
3. le bundle a été modifié après la signature, ce qui invalide le lien entre l’entitlement et le code signé.

Examinez les entitlements réellement intégrés dans le binaire :

codesign -d --entitlements :- \
  "/chemin/vers/APP.app"

Comparez cette sortie avec les capacités réellement utilisées par l’application. Ne vous contentez pas du fichier .entitlements du projet : l’exportation, la signature et certains réglages de distribution peuvent produire un résultat différent.

Le cas le plus fréquent dans une chaîne personnalisée est la présence de com.apple.security.get-task-allow avec une valeur autorisant le débogage. Apple indique que cette entitlement ne doit pas être conservée avec une valeur vraie dans un logiciel destiné à la notarisation. La documentation Apple sur la préparation à la notarisation donne également des exemples liés au code JIT, à la mémoire exécutable non signée et à la validation des bibliothèques.

Ne supprimez toutefois pas en bloc toutes les entitlements pour « faire passer » l’analyse. Une application audio qui charge des extensions, un outil vidéo qui utilise un moteur de traitement natif ou un logiciel de design qui intègre des modules externes peut avoir besoin d’autorisations particulières. La bonne méthode consiste à :

• partir d’une liste minimale ;
• ajouter uniquement la capacité correspondant à une fonction réellement utilisée ;
• signer à nouveau après toute modification ;
• vérifier la sortie finale avec codesign -d --entitlements :- ;
• relire le journal après soumission.

Attention : une entitlement valide dans le projet ne signifie pas que le comportement est autorisé dans tous les contextes. Le service analyse le binaire distribué et ses composants, pas votre intention de configuration.

Une application macOS moderne peut contenir plusieurs objets signables :

• frameworks ;
• plug-ins audio ou vidéo ;
• services XPC ;
• helpers ;
• exécutables auxiliaires ;
• bibliothèques tierces ;
• moteurs ou outils appelés depuis le bundle.

La signature de l’application extérieure ne suffit pas si un de ces objets a été copié, patché ou resigné après coup. Inspectez l’arborescence avant de créer l’archive finale. Les fichiers exécutables doivent être signés ; les ressources non exécutables ne doivent pas être placées dans un emplacement qui impose inutilement une signature.

Pour un contrôle rapide :

codesign --verify --verbose=4 --deep --strict \
  "/chemin/vers/APP.app"

spctl --assess --type execute --verbose=4 \
  "/chemin/vers/APP.app"

spctl ne remplace pas le journal de notarisation. Il répond à une question différente : comment la politique de sécurité locale évalue-t-elle cet objet ? Le résultat peut varier selon le type d’objet, le ticket présent et le contexte d’exécution.

ZIP, DMG et PKG

Apple accepte notamment les archives ZIP, les images disque au format UDIF et les paquets d’installation signés. Le choix du conteneur modifie cependant le point de contrôle. La documentation Apple sur la mise en paquet d’un logiciel Mac explique les différences entre ces formats.

Un ZIP doit surtout être vérifié comme archive contenant une application signée. Un DMG ajoute l’intégrité de l’image et son contenu. Un PKG exige une attention particulière à la signature de l’installateur et à la signature de l’application installée.

Si vous utilisez un installateur personnalisé, Apple précise qu’il peut être nécessaire de notariser séparément le contenu installé, puis l’installateur qui l’embarque. Cette règle est importante pour les applications créatives qui installent des extensions, des composants audio ou des outils auxiliaires en dehors du bundle principal. Le workflow Apple pour la notarisation décrit cette distinction.

Les réponses ci-dessous complètent la procédure sans remplacer le journal de la soumission.

Notarytool retourne Invalid

Utilisez le Submission ID avec notarytool log. Cherchez d’abord le premier objet réellement signalé, puis vérifiez son type : application, framework, plug-in, outil auxiliaire ou paquet. Corrigez une seule famille de problèmes à la fois. Si vous resignez plusieurs niveaux sans conserver une copie de l’artefact précédent, vous risquez de rendre la comparaison impossible.

Application signée, mais notarisation refusée

Inspectez le certificat, l’horodatage, les entitlements et les composants imbriqués. Une application peut passer codesign --verify tout en contenant une entitlement interdite, un outil auxiliaire signé avec une identité de développement ou un fichier modifié après la dernière signature. La commande de vérification est une preuve locale, pas une garantie d’acceptation par le service.

Notarisation acceptée, mais stapler échoue

Commencez par valider le fichier exact qui a été soumis. Ne staplez pas une copie recompressée, renommée par un script ou reconstruite après l’acceptation. Vérifiez que le volume est accessible en écriture et que le Mac peut contacter les services nécessaires. Utilisez ensuite :

xcrun stapler staple "/chemin/vers/ARTEFACT.dmg"
xcrun stapler validate "/chemin/vers/ARTEFACT.dmg"

Identifiants sur un Mac distant

Créez un profil de trousseau avec un nom générique qui ne contient pas de secret :

xcrun notarytool store-credentials "PROFIL_TROUSSEAU" \
  --apple-id "APPLE_ID_PLACEHOLDER" \
  --team-id "TEAM_ID_PLACEHOLDER"

Le mot de passe doit être saisi de manière interactive ou injecté par un mécanisme sécurisé. Ne l’écrivez pas dans le dépôt, les arguments persistants du système ou les logs de CI. Testez ensuite le profil :

xcrun notarytool history \
  --keychain-profile "PROFIL_TROUSSEAU"

Apple indique que notarytool peut enregistrer les informations dans le trousseau et que l’option --keychain permet de cibler un trousseau fichier dans certains workflows. La configuration doit être testée avec le même compte système que celui qui exécutera la publication. La note technique Apple sur la migration vers notarytool précise les options d’authentification et de stockage des identifiants.

Une erreur d’authentification n’est pas un refus du logiciel. Une erreur réseau n’est pas une erreur d’entitlement. Un échec de stapler n’est pas une preuve que la notarisation a été rejetée.

Classez le problème selon le moment où il apparaît :

• Avant l’envoi : profil de trousseau, Team ID, clé privée, version d’outillage ou chemin de fichier.
• Pendant l’envoi : accès réseau, taille, archive corrompue ou point de terminaison inaccessible.
• Après l’envoi : traitement en cours, statut Invalid ou journal indisponible.
• Après Accepted : artefact non inscriptible, mauvais fichier, cache local ou accès aux services nécessaires à stapler.
• Au lancement local : signature, ticket, quarantaine ou évaluation Gatekeeper.

Apple indique que notarytool utilise par défaut un mécanisme d’accélération pour le transfert et que stapler doit pouvoir joindre les services Apple nécessaires au téléchargement des tickets. Sur un réseau d’entreprise ou une machine distante verrouillée, une liste blanche incomplète peut donc bloquer l’attachement du ticket sans remettre en cause le résultat de l’analyse.

Une machine distante est adaptée à la publication répétée uniquement si vous pouvez reproduire les mêmes conditions à chaque version. L’objectif n’est pas de disposer d’un Mac « puissant » en général, mais d’un environnement capable de conserver :

• la version choisie de Xcode Command Line Tools ;
• les identités Developer ID et leurs clés privées ;
• le trousseau utilisé par notarytool ;
• les scripts de signature et d’exportation ;
• les variables secrètes hors des logs ;
• les journaux JSON associés à chaque Submission ID ;
• les fichiers finaux avant et après stapler.

Suivez cette séquence :

1. Exportez une archive de test avec le même script que celui de la publication.
2. Vérifiez l’identité de signature et la présence de la clé privée.
3. Contrôlez l’application et les composants imbriqués avec codesign.
4. Inspectez les entitlements effectivement intégrés.
5. Créez le ZIP, le DMG ou le PKG final sans le modifier après signature.
6. Testez le profil de trousseau avec notarytool history.
7. Soumettez l’artefact et sauvegardez le résultat JSON.
8. Téléchargez le journal avec le Submission ID.
9. Si le statut est Accepted, attachez le ticket avec stapler.
10. Validez l’artefact final avec stapler validate et spctl.

Pour une procédure plus large, vous pouvez consulter le guide de configuration sécurisée du trousseau Developer ID, puis documenter la machine dans une configuration de Mac distant pour publication. Si la chaîne doit rester disponible pendant vos cycles de sortie, comparez aussi les options de location de Mac pour un environnement de développement.

Utilisez ces branches avant de modifier votre infrastructure :

• Si le journal signale une signature ou une entitlement, corrigez le projet et le script de signature avant de changer de Mac.
• Si le profil de trousseau fonctionne mais que le réseau bloque l’envoi ou stapler, corrigez les règles réseau ou choisissez un environnement disposant d’un accès sortant documenté.
• Si la clé privée manque après chaque nouvelle installation, migrez le certificat, la clé et le trousseau dans une procédure contrôlée plutôt que de recréer manuellement la machine.
• Si le statut reste en traitement, conservez le Submission ID et évitez les renvois automatiques agressifs ; le délai n’est pas une preuve de rejet.
• Si le même artefact passe sur un Mac mais échoue sur un autre, comparez les versions d’outillage, le trousseau, les scripts et les droits du compte système avant de conclure à un problème de code.
• Si vous distribuez plusieurs formats, validez chacun avec son outil : codesign pour l’application, pkgutil pour le PKG, stapler et spctl pour l’artefact final.

Un flux local ponctuel peut fonctionner avec un trousseau configuré à la main, un script lancé depuis votre session et une validation manuelle. Ce modèle devient fragile dès que plusieurs versions doivent être publiées, qu’un collaborateur reprend la maintenance ou qu’un échec doit être reproduit plusieurs jours plus tard.

Si votre solution actuelle repose sur un Mac personnel, elle présente souvent quatre limites concrètes : machine éteinte au moment du lancement, trousseau inaccessible à une tâche automatisée, dépendance à une configuration locale non documentée et absence de journaux centralisés. Une machine virtuelle générique ou un serveur Linux ajoute une autre contrainte : elle ne remplace pas l’environnement macOS nécessaire à Xcode, codesign, stapler et aux tests Gatekeeper.

Après une première correction, vous devez donc décider si votre Mac actuel peut conserver durablement les certificats, le trousseau, les outils et les scripts. Si ce n’est pas le cas, louer un Mac auprès de CALMVPS peut offrir un environnement macOS persistant pour exécuter vos archives, conserver une configuration contrôlée et répéter la chaîne notarytool sans dépendre de la disponibilité de votre poste personnel. Cette option est surtout pertinente pour les versions fréquentes, les applications audio ou vidéo lourdes et les équipes qui veulent séparer le poste de création du serveur de publication.

Pour une publication occasionnelle, votre propre Mac reste généralement plus simple. Pour une charge continue nécessitant des interfaces physiques, des périphériques de test ou un contrôle matériel local, une location distante ne convient pas toujours. En revanche, si votre priorité est de disposer d’un Mac connecté, documenté et réutilisable pour signer, notariser, stapler et conserver les journaux, vous pouvez examiner les solutions de Mac distant proposées par CALMVPS et appliquer cette checklist avant toute mise en production.