Panoramica: perché il monitoraggio della scadenza dei certificati è essenziale
I certificati Apple Pass Type ID (pass.com.yourbrand.*) hanno un periodo di validità rigoroso di 397 giorni (~13 mesi) imposto dalla Certification Authority di Apple. Se un certificato scade senza essere rinnovato:
-
I nuovi download non riescono: Passinstance non può generare firme PKCS#7 detached valide per i nuovi download
.pkpassassociati a quel certificato. -
Gli aggiornamenti push APNs si interrompono: Il gateway HTTP/2 APNs di Apple (
api.push.apple.com) rifiuta immediatamente le connessioni TLS autenticate con un certificato scaduto, bloccando gli aggiornamenti live di saldo e campi sugli iPhone già installati.
Importante: Rinnovi sempre sotto l'esatto stesso Pass Type ID (
pass.com.yourbrand.*) e Apple Developer Team ID invece di creare un nuovo Pass Type ID da zero. Poiché iOS lega i pass installati alla coppia(passTypeIdentifier, teamIdentifier), rinnovare il certificato sullo stesso Pass Type ID permette a tutti i pass esistenti sugli iPhone e Apple Watch dei clienti di continuare a ricevere aggiornamenti push APNs con zero reinstallazioni richieste al cliente.
Procedura di rinnovo certificati a zero downtime
-
1
Monitoraggio delle finestre di scadenza (
Certificate Renewal Monitor): Passinstance esegue ogni giorno alle 02:00 un controllo programmato sui certificati attivi convalidToentro 30 giorni, inviando un'e-mail a proprietari e amministratori del workspace e mostrando gli avvisi in Impostazioni -> Wallet -> Certificati Apple. -
2
Generazione di un CSR di rinnovo: Apra il certificato in scadenza in Passinstance e scarichi un nuovo CSR (
POST /api/v1/certificates/generate-csr). -
3
Emissione di un nuovo certificato sotto il Pass Type ID esistente: In Apple Developer Portal -> Identifiers -> Pass Type IDs, selezioni il Pass Type ID esistente, clicchi su Create Certificate, carichi il CSR e scarichi il nuovo
pass.cer. (Apple consente certificati attivi sovrapposti sullo stesso Pass Type ID, così da poter completare la rotazione in sicurezza prima di revocare il certificato precedente.) -
4
Upsert del file
pass.cerrinnovato in Passinstance: Carichi il file.cerfirmato tramitePOST /api/v1/certificates/upsert(multipart/form-data, specificandopassTypeId,type: "TYPE_PASS" | "TYPE_NFC"ed eventualepkeyId). Passinstance verifica la catena Apple WWDR G4/G6 e sostituisce il certificato di firma attivo. -
5
Verifica firma e push APNs: Emetta un pass di test (
POST /api/v1/passes) e invii una notifica push (POST /api/v1/push-notifications/passes/:id) per confermare che sia la firma del bundle PKCS#7 sia la consegna HTTP/2 APNs vadano a buon fine.
Endpoint API per rinnovo e ciclo di vita dei certificati (Certificate Management API)
| Metodo | Percorso endpoint | Permesso richiesto | Descrizione |
|---|---|---|---|
| GET | /api/v1/certificates | certificates:read | Elenca i certificati del workspace e i relativi metadati (validFrom, validTo, passTypeIdentifier, teamIdentifier, type). |
| POST | /api/v1/certificates/generate-csr | certificates:manage | Genera una coppia di chiavi RSA (CertificatePkey) e restituisce un CSR PEM per la firma in Apple Developer. |
| POST | /api/v1/certificates/upsert | certificates:manage | Crea o sostituisce/rinnova atomicamente un certificato esistente a partire da un .cer firmato caricato (multipart/form-data). |
| GET | /api/v1/certificates/:id | certificates:read | Ispeziona metadati X.509, date di validità e associazione del Pass Type ID. |
| DELETE | /api/v1/certificates/:id | certificates:manage | Rimuove un record certificato superato o non utilizzato. |
Esempio: eseguire l'upsert di un certificato .cer rinnovato
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"
Risposta (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"
}
Rotazione automatica dei certificati intermedi Apple WWDR G4 e G6
Passinstance gestisce automaticamente i certificati intermedi Worldwide Developer Relations (WWDR) di Apple (G4 e G6) all'interno dell'archivio certificati PKCS#7 lato server (Apple Wallet Packager). Non è mai necessario caricare manualmente AppleWWDRCAG4.cer o AppleWWDRCAG6.cer: Passinstance legge l'Authority Key Identifier (AKI) del file pass.cer caricato e include il certificato intermedio WWDR corrispondente nella signature di ogni .pkpass.
Consulti Certificati Apple Wallet e Apple Wallet per i passaggi iniziali di configurazione.
