Überblick: Warum die Überwachung von Ablaufdaten entscheidend ist
Apple Pass Type ID-Zertifikate (pass.com.yourbrand.*) besitzen eine von Apples Zertifizierungsstelle fest vorgegebene Gültigkeitsdauer von 397 Tagen (~13 Monate). Läuft ein Zertifikat ohne Erneuerung ab:
-
Schlagen neue Downloads fehl: Passinstance kann für neue
.pkpass-Downloads unter diesem Zertifikat keine gültigen PKCS#7-Signaturen mehr erzeugen. -
Stoppen APNs-Push-Updates: Apples HTTP/2-APNs-Gateway (
api.push.apple.com) lehnt TLS-Verbindungen mit abgelaufenem Zertifikat sofort ab — Live-Kontostands- und Feldaktualisierungen auf installierten iPhones werden dadurch unterbrochen.
Wichtig: Erneuern Sie stets unter exakt derselben Pass Type ID (
pass.com.yourbrand.*) und Apple Developer Team ID, statt eine komplett neue Pass Type ID anzulegen. Da iOS installierte Pässe an das Tupel(passTypeIdentifier, teamIdentifier)bindet, sorgt eine Erneuerung auf derselben Pass Type ID dafür, dass alle vorhandenen Pässe auf Kunden-iPhones und Apple Watches ohne jegliche Neuinstallation durch Endkundinnen und Endkunden weiterhin APNs-Push-Updates empfangen.
Ablauf für unterbrechungsfreie Zertifikatserneuerung
-
1
Ablauffristen überwachen (
Certificate Renewal Monitor): Passinstance führt täglich um 02:00 Uhr eine geplante Prüfung aller aktiven Zertifikate mitvalidToinnerhalb der nächsten 30 Tage durch, benachrichtigt Workspace-Owner/-Admins per E-Mail und blendet Hinweise unter Einstellungen -> Wallet -> Apple-Zertifikate ein. -
2
Erneuerungs-CSR erzeugen: Öffnen Sie das ablaufende Zertifikat in Passinstance und laden Sie eine neue CSR herunter (
POST /api/v1/certificates/generate-csr). -
3
Neues Zertifikat unter bestehender Pass Type ID ausstellen: Wählen Sie im Apple Developer Portal -> Identifiers -> Pass Type IDs Ihre bestehende Pass Type ID aus, klicken Sie auf Create Certificate, laden Sie die CSR hoch und laden Sie die neue
pass.cerherunter. (Apple erlaubt mehrere zeitlich überlappende aktive Zertifikate je Pass Type ID, sodass Sie gefahrlos rotieren können, bevor das alte Zertifikat widerrufen wird.) -
4
Erneuerte
pass.cerper Upsert in Passinstance laden: Laden Sie die signierte.cer-Datei überPOST /api/v1/certificates/upserthoch (multipart/form-datamit Angabe vonpassTypeId,type: "TYPE_PASS" | "TYPE_NFC"und optionalpkeyId). Passinstance prüft die Apple WWDR G4/G6-Kette und tauscht das aktive Signaturzertifikat aus. -
5
Signatur & APNs-Push verifizieren: Geben Sie einen Testpass aus (
POST /api/v1/passes) und senden Sie eine Push-Benachrichtigung (POST /api/v1/push-notifications/passes/:id), um sowohl PKCS#7-Signierung als auch APNs-HTTP/2-Auslieferung zu bestätigen.
API-Endpunkte für Zertifikatserneuerung & Lebenszyklus (Certificate Management API)
| Methode | Endpunkt-Pfad | Erforderliche Berechtigung | Beschreibung |
|---|---|---|---|
| GET | /api/v1/certificates | certificates:read | Listet Workspace-Zertifikate samt Prüf-Metadaten (validFrom, validTo, passTypeIdentifier, teamIdentifier, type) auf. |
| POST | /api/v1/certificates/generate-csr | certificates:manage | Erzeugt ein RSA-Schlüsselpaar (CertificatePkey) und gibt eine PEM-CSR zur Signierung in Apple Developer zurück. |
| POST | /api/v1/certificates/upsert | certificates:manage | Erstellt oder ersetzt/erneuert ein bestehendes Zertifikat atomar anhand einer hochgeladenen .cer-Datei (multipart/form-data). |
| GET | /api/v1/certificates/:id | certificates:read | Zeigt X.509-Zertifikatsmetadaten, Gültigkeitsdaten und Pass-Type-ID-Verknüpfung an. |
| DELETE | /api/v1/certificates/:id | certificates:manage | Entfernt einen abgelösten oder ungenutzten Zertifikatsdatensatz. |
Beispiel: Erneuertes .cer-Zertifikat per Upsert einspielen
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"
Antwort (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"
}
Apple WWDR G4 & G6 Zwischenzertifikats-Rollover
Passinstance verwaltet Apples Worldwide Developer Relations (WWDR) Zwischenzertifikate (G4 und G6) vollautomatisch im serverseitigen PKCS#7-Zertifikatsspeicher (Apple Wallet Packager). Sie müssen niemals manuell AppleWWDRCAG4.cer oder AppleWWDRCAG6.cer hochladen — Passinstance prüft den Authority Key Identifier (AKI) Ihrer hochgeladenen pass.cer und bettet automatisch das passende WWDR-Zwischenzertifikat in jede .pkpass-signature ein.
Für die Ersteinrichtung siehe Apple Wallet-Zertifikate und Apple Wallet.
