Comprendre les certificats et profils de provisionnement iOS

La signature iOS code repose sur deux éléments. Un certificat prouve qui a compilé l'app, et un profil de provisionnement indique de quelle app il s'agit, quels appareils peuvent l'exécuter et quelles capacités elle peut utiliser. Xcode refuse de compiler pour un appareil, et App Store Connect refuse les uploads, à moins que le certificat, sa clé privée et un profil correspondant ne concordent parfaitement.

Ce guide explique chaque élément, la combinaison nécessaire pour les builds de développement, ad hoc, TestFlight, App Store et enterprise, comment les créer avec ou sans Mac, et comment corriger les erreurs que vous rencontrerez.

Pourquoi Apple exige la signature de code

Apple n'autorise les iPhones à exécuter que code qu'Apple peut rattacher à un développeur connu. La signature offre trois garanties à Apple :

1. Identité: le binaire a été signé par un membre d'une équipe Apple Developer spécifique.
2. Intégrité: personne n'a modifié le binaire après la signature. Modifier un seul octet brise la signature.
3. Autorisation: l'app est autorisée sur cet appareil, avec ces entitlements (push, iCloud, Sign in with Apple, App Groups, etc.).

Les certificats fournissent les deux premiers. Les profils de provisionnement fournissent le troisième.

Les éléments de base

La confusion la plus courante : un .cer fichier est inutile seul. La signature nécessite la clé privée qui a créé le CSR. Si vous perdez cette clé, il faut créer un nouveau certificat.

Types de certificats

Développement Apple

Utilisé pour lancer des builds sur vos propres appareils depuis Xcode pendant le développement. Les certificats de développement appartiennent à un développeur individuel, et Apple les nomme d'après le nom de l'ordinateur. Chaque développeur de l'équipe peut avoir le sien.

Distribution Apple

Servent à signer les builds pour la distribution Ad Hoc, TestFlight et l'App Store. Les certificats de distribution appartiennent à l'équipe, et seuls les rôles Account Holder ou Admin peuvent les créer. Apple limite le nombre de certificats par équipe : partagez-en un via un stockage sécurisé plutôt que de laisser chaque développeur créer le sien.

Vous pourriez encore voir Développement iOS et Distribution iOS dans d'anciens comptes. Il s'agit des types antérieurs à Xcode 11. Apple Development et Apple Distribution les remplacent et fonctionnent sur iOS, iPadOS, macOS, tvOS, watchOS et visionOS.

Autres types de certificats à connaître

• Developer ID Application / Installer: pour les apps Mac distribuées hors du Mac App Store. Non utilisé pour iOS.
• SSL pour Apple Push Notification service: des anciens certificats push. Privilégiez un Clé d'authentification APNs (.p8), qui n'expire pas chaque année et fonctionne pour toutes les apps de l'équipe. Voir notre guide sur les certificats APNs.
• Identité marchand Apple Pay, ID de type de pass, ID de push web: services spécifiques.

Types de profils de provisionnement

Un profil est lié à un App ID. Si votre app possède des extensions (un widget, une extension de service de notification, une extension de partage), chaque cible possède son propre bundle ID et nécessite son propre profil.

Comment les éléments s'assemblent

Quand Xcode ou un service de build signe votre app Capacitor, il vérifie :

1. Le bundle ID de votre cible (par exemple com.example.app) correspond à l'App ID du profil.
2. Le certificat utilisé pour signer est l'un des certificats listés dans le profil.
3. La clé privée de ce certificat est disponible dans le keychain.
4. Pour les builds de développement et ad hoc, l’UDID de l’appareil figure dans le profil.
5. Le fichier d’entitlements (push, domaines associés, App Groups) est un sous-ensemble de ce que l’App ID et le profil autorisent.

Si un contrôl’échoue, vous obtenez une erreur de signature, pas un crash à l’exécution, ce qui est bien : vous le découvrez avant de livrer.

Quelle combinaison choisir ?

TestFlight utilise la même signature que l'App Store. Il n'y a pas de profil TestFlight distinct. Vous envoyez un build et décidez dans App Store Connect s'il est destiné aux testeurs, à la review, ou aux deux.

Créer des certificats et des profils

Option 1 : laisser Xcode gérer la signature

C'est la solution la plus simple pour le développement local. Ouvrez ios/App/App.xcworkspace (ou le .xcodeproj lorsque votre projet Capacitor 8 utilise Swift Package Manager), sélectionnez la cible App, ouvrez Signature et capacités, cochez Gérer automatiquement la signature et choisissez votre équipe. Xcode crée le certificat de développement, enregistre l'appareil connecté et génère les profils pour vous.

La signature automatique devient pénible en CI, car la machine de build doit avoir accès au compte de l'équipe et crée ses propres certificats. La plupart des équipes passent à la signature manuelle, ou à un service de build avec une signature basée sur une clé API pour les builds de release.

Option 2 : créez-les manuellement sur un Mac

1. Ouvrez Trousseau d’accès > Assistant de certification > Demander un certificat à une autorité de certification. Saisissez votre e-mail, choisissez Enregistré sur le disque. Cela crée la clé privée dans votre trousseau et un .certSigningRequest fichier.
2. Dans le portail Apple Developer, allez dans Certificats, Identifiants & Profils > Certificats > +, choisissez Distribution Apple (ou Apple Development) et envoyez le CSR.
3. Téléchargez le .cer et double-cliquez dessus. Keychain Access l'associe à la clé privée.
4. Pour l'export vers une CI : dans Keychain Access, sous Mes certificats, faites un clic droit sur le certificat, choisissez Exporter, save as .p12 avec un mot de passe robuste.

Option 3 : les créer sans Mac

Vous pouvez faire toute la procédure avec OpenSSL sur Linux ou Windows :

# 1. Private key and CSR
openssl genrsa -out ios_distribution.key 2048
openssl req -new -key ios_distribution.key -out ios_distribution.csr \
  -subj "/emailAddress=you@example.com/CN=Example Inc/C=US"

# 2. Upload ios_distribution.csr in the Apple Developer portal,
#    download the certificate as distribution.cer

# 3. Convert the .cer (DER) to PEM
openssl x509 -in distribution.cer -inform DER -out distribution.pem -outform PEM

# 4. Build the .p12 (signing identity)
openssl pkcs12 -export -inkey ios_distribution.key -in distribution.pem \
  -out ios_distribution.p12 -legacy

Le -legacy le flag est important avec OpenSSL 3 : sans lui, l' .p12 utilise des algorithmes de chiffrement que les outils du trousseau macOS rejettent avec une erreur « mot de passe invalide », même si le mot de passe est correct.

Si vous préférez ne pas installer OpenSSL, l' Générateur de certificats iOS crée le CSR et la clé privée pour vous. Ils proviennent d'un endpoint Capgo stateless qui ne les stocke pas, et seul son .cer vers .p12 Le convertisseur s’exécute entièrement dans votre navigateur. Si votre politique exige que la clé soit générée sur votre machine, utilisez les commandes OpenSSL ci-dessus.

Création du profil

1. Identifiants > +: enregistrez un App ID avec votre bundle ID exact et activez les capacités que vous utilisez (Push Notifications, Sign in with Apple, Associated Domains…).
2. Appareils > +: pour les profils de développement et ad hoc, enregistrez l’UDID de chaque testeur. Les testeurs peuvent l’obtenir directement sur le téléphone avec le Recherche d'UDID iOS, sans Mac ni câble.
3. Profils > +: choisissez le type de profil, l’App ID, le(s) certificat(s) et les appareils. Donnez-lui un nom explicite, par exemple com.example.app AppStore 2026.
4. Téléchargez le .mobileprovision fichier.

Si vous ajoutez un appareil ou une capacité ultérieurement, vous devrez régénérer et retélécharger le profil. Les profils existants ne se mettent pas à jour automatiquement.

Inspecter un profil

Un .mobileprovision est un fichier plist signé. Sur macOS, vous pouvez le lire :

security cms -D -i App_Store.mobileprovision > profile.plist
/usr/libexec/PlistBuddy -c "Print :Name" profile.plist
/usr/libexec/PlistBuddy -c "Print :ExpirationDate" profile.plist
/usr/libexec/PlistBuddy -c "Print :Entitlements" profile.plist
/usr/libexec/PlistBuddy -c "Print :ProvisionedDevices" profile.plist

Sur Linux, openssl smime -inform der -verify -noverify -in App_Store.mobileprovision affiche le plist.

Pour vérifier ce qu'un build .ipa a été signé avec :

unzip -q App.ipa -d ipa
codesign -dvv ipa/Payload/App.app
codesign -d --entitlements :- ipa/Payload/App.app

Expiration et renouvellement

• Certificats sont valables un an à partir de leur création.
• Profils de provisionnement expirent après un an, ou plus tôt si le certificat qu'ils incluent expire ou est révoqué.
• Les apps de l'App Store continuent de fonctionner après l'expiration du certificat de distribution. Apple signe à nouveau les téléchargements de l'App Store. Vous avez seulement besoin d'un nouveau certificat pour envoyer de nouveaux builds.
• Les builds Ad Hoc et de développement ne se lancent plus une fois leur profil expiré. Les testeurs constatent un crash de l'app au lancement.
• Builds TestFlight expirent 90 jours après l'upload, indépendamment du certificat.
• Les apps Enterprise cessent de fonctionner sur chaque appareil lorsque le certificat Enterprise expire ou est révoqué. Renouvelez-l’avant l'expiration.
• Slots d'appareils sont réinitialisés une fois par année d'adhésion. Supprimer un appareil ne libère pas son slot avant le début de l'année d'adhésion suivante.

Ajoutez la date d’expiration du certificat dans un calendrier partagé. Notre guide de gestion des certificats aborde plus en détail la surveillance et la rotation.

Erreurs courantes et solutions

« No signing certificate ‘iOS Distribution’ found » ou « Signing certificate is invalid »: la clé privée n’est pas dans ce keychain. Importez la .p12, ou créez un nouveau certificat si personne n’a la clé.

« Provisioning profile doesn’t include signing certificate »: le profil a été créé avec un certificat différent. Modifiez le profil dans le portail, cochez le certificat actuel, régénérez-le puis téléchargez-le.

« Le profil de provisionnement n’inclut pas l’appareil actuellement sélectionné »: enregistrez l’UDID, puis régénérez le profil. Inutile pour TestFlight ou l’App Store.

« Le profil de provisionnement ne prend pas en charge la capacité Notifications push »: activez la capacité sur l’App ID, puis régénérez le profil. Les profils sont des instantanés.

« Aucun profil de provisionnement valide pour cet exécutable n’a été trouvé » à l’installation : l’appareil n’est pas dans le profil ad hoc, ou le profil a expiré.

L’app s’installe puis se ferme immédiatement: sur iOS 16 et versions ultérieures, les builds de développement et ad hoc nécessitent le mode développeur sur l’appareil. Voir Comment activer le mode développeur sur iOS.

Échec de la signature des extensions: chaque cible d’extension nécessite son propre App ID et son propre profil. Vérifiez chaque cible dans Signing & Capabilities, pas seulement App.

« Invalid password » lors de l’importation d’un .p12 créé sur Linux: recompilez-l’avec openssl pkcs12 -export ... -legacy.

Upload rejeté pour la version SDK: depuis avril 2026, App Store Connect exige des builds réalisés avec Xcode 26 et le SDK iOS 26 SDK. Mettez à jour Xcode ou votre image CI. Capacitor 8 exige déjà Xcode 26.

Bonnes pratiques pour les équipes

• Un certificat Apple Distribution par équipe, stocké dans .p12 un gestionnaire de mots de passe ou un coffre-fort de secrets, avec le mot de passe stocké séparément.
• Never email .p12 les fichiers, et ne les committez jamais dans git.
• Utilisez les clés API d’App Store Connect (.p8) pour les uploads au lieu des mots de passe Apple ID.
• Nommez les profils avec le bundle ID, le type et l'année.
• Révoquez les certificats des personnes qui quittent l'équipe.
• Tenez une liste écrite de tous les bundle ID, extensions et capacités utilisés par l'app.

Signature cloud pour les apps Capacitor

Vous n'avez pas besoin d'un Mac sur le bureau de chaque développeur pour déployer des builds iOS. Build Capgo compile Capacitor apps sur les machines macOS de Capgo en utilisant un .p12 et le profil que vous fournissez. Les identifiants ne servent qu'au build et ne sont pas stockés sur les serveurs de Capgo. Enregistrez-les une fois depuis CLI :

bunx @capgo/cli@latest build credentials save --appId com.example.app --platform ios
bunx @capgo/cli@latest build request com.example.app --platform ios --path .

Le Documentation Capgo Build iOS détaillent les options d'identifiants, dont les clés API App Store Connect pour l'upload TestFlight et ad_hoc le mode pour les builds de test.

Une fois votre premier build dans TestFlight, vous pouvez déployer des changements JS et d'assets aux utilisateurs avec les live updates Capgo sans avoir à re-signer un nouveau binaire à chaque correctif. Les changements natifs code et les nouvelles capacités nécessitent toujours un build signé via le store.

Prochaines étapes

• Besoin de comptes au préalable ? Comment créer des comptes développeur Apple et Google Play.
• Prêt à envoyer vos builds aux testeurs ? Comment distribuer vos apps iOS et Android aux testeurs.
• En cours de soumission ? Lisez notre guide de publication d'app iOS.