Aperçu : pourquoi surveiller l'expiration des certificats
Les certificats Apple Pass Type ID (pass.com.yourbrand.*) ont une durée de validité stricte de 397 jours (~13 mois) imposée par l'autorité de certification d'Apple. Si un certificat expire sans avoir été renouvelé à temps :
-
Échec des nouveaux téléchargements : Passinstance ne peut plus produire de signature PKCS#7 détachée valide pour les nouvelles archives
.pkpassrattachées à ce certificat. -
Arrêt des mises à jour push APNs : La passerelle HTTP/2 APNs d'Apple (
api.push.apple.com) rejette immédiatement les connexions TLS authentifiées par un certificat expiré, bloquant les actualisations de solde et de champs sur les iPhones déjà équipés.
Important : Renouvelez toujours votre certificat sous exactement le même Pass Type ID (
pass.com.yourbrand.*) et le même Apple Developer Team ID plutôt que d'en créer un nouveau. Comme iOS lie les passes installés au couple(passTypeIdentifier, teamIdentifier), le renouvellement sur le même Pass Type ID permet à toutes les cartes déjà enregistrées sur iPhone et Apple Watch de continuer à recevoir les mises à jour push APNs sans aucune réinstallation côté client.
Procédure de renouvellement sans interruption de service
-
1
Surveiller les échéances (
Certificate Renewal Monitor) : Passinstance exécute chaque jour à 02:00 une analyse des certificats actifs dontvalidToarrive à échéance sous 30 jours, envoie un e-mail aux propriétaires/administrateurs de l'espace de travail et affiche des alertes dans Paramètres -> Wallet -> Certificats Apple. -
2
Générer une CSR de renouvellement : Ouvrez le certificat proche de l'expiration dans Passinstance et téléchargez une nouvelle CSR (
POST /api/v1/certificates/generate-csr). -
3
Émettre le nouveau certificat sous le Pass Type ID existant : Dans Apple Developer Portal -> Identifiers -> Pass Type IDs, ouvrez votre Pass Type ID existant, cliquez sur Create Certificate, importez la CSR puis téléchargez le nouveau fichier
pass.cer. (Apple autorise la coexistence temporaire de deux certificats actifs par Pass Type ID afin d'effectuer la bascule avant de révoquer l'ancien.) -
4
Remplacer via
pass.cerdans Passinstance : Importez le.cersigné viaPOST /api/v1/certificates/upsert(multipart/form-dataen précisantpassTypeId,type: "TYPE_PASS" | "TYPE_NFC"etpkeyIdoptionnel). Passinstance vérifie la chaîne Apple WWDR G4/G6 et bascule le certificat de signature actif. -
5
Vérifier la signature & le push APNs : Émettez un passe de test (
POST /api/v1/passes) et envoyez une notification push (POST /api/v1/push-notifications/passes/:id) afin de confirmer que la signature PKCS#7 et la livraison HTTP/2 APNs fonctionnent toutes les deux.
Points d'entrée API de renouvellement & cycle de vie (Certificate Management API)
| Méthode | Chemin du point d'entrée | Permission requise | Description |
|---|---|---|---|
| GET | /api/v1/certificates | certificates:read | Liste les certificats de l'espace avec métadonnées (validFrom, validTo, passTypeIdentifier, teamIdentifier, type). |
| POST | /api/v1/certificates/generate-csr | certificates:manage | Génère une paire de clés RSA (CertificatePkey) et retourne une CSR PEM à faire signer sur Apple Developer. |
| POST | /api/v1/certificates/upsert | certificates:manage | Crée ou remplace/renouvelle de manière atomique un certificat existant à partir d'un fichier .cer signé (multipart/form-data). |
| GET | /api/v1/certificates/:id | certificates:read | Inspecte les métadonnées X.509, les dates de validité et le rattachement Pass Type ID d'un certificat. |
| DELETE | /api/v1/certificates/:id | certificates:manage | Supprime un ancien enregistrement de certificat remplacé ou inutilisé. |
Exemple : remplacer un certificat par sa version renouvelée .cer
curl -X POST https://api.passinstance.com/api/v1/certificates/upsert \
-H "X-API-Key: <API_KEY>" \
-F "file=@./pass-renewed.cer" \
-F "passTypeId=pass.com.phenixroasters.loyalty" \
-F "type=TYPE_PASS"
Réponse (201 Created / 200 OK) :
{
"id": "cert_8841a9b0-2c3d-4e5f-8a9b-0c1d2e3f4a5b",
"passTypeIdentifier": "pass.com.phenixroasters.loyalty",
"teamIdentifier": "9A8B7C6D5E",
"type": "TYPE_PASS",
"validTo": "2027-12-31T23:59:59.000Z"
}
Gestion automatique des certificats intermédiaires Apple WWDR G4 & G6
Passinstance embarque et maintient automatiquement les certificats intermédiaires Worldwide Developer Relations (WWDR) d'Apple (G4 et G6) dans son magasin serveur PKCS#7 (Apple Wallet Packager). Vous n'avez jamais besoin d'importer manuellement AppleWWDRCAG4.cer ou AppleWWDRCAG6.cer : Passinstance inspecte l'Authority Key Identifier (AKI) de votre pass.cer et inclut le certificat intermédiaire WWDR correspondant dans la signature de chaque archive .pkpass.
Consultez Certificats Apple Wallet et Apple Wallet pour les étapes d'installation initiale.
