Thomas Peterson
b316d0baf8
Schritt-für-Schritt zum Erzeugen der Zugangsdaten (Pass Type ID + Cert/Key/WWDR als PEM via CSR; Google Issuer + Service-Account + Freigabe) und Eintragen der Env-Variablen. Verlinkt aus deploy/README. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
113 lines
5.0 KiB
Markdown
113 lines
5.0 KiB
Markdown
# Wallet-Pässe einrichten (Apple & Google)
|
||
|
||
Schritt-für-Schritt, um die „Zur Wallet hinzufügen"-Funktion scharf zu schalten.
|
||
Ohne diese Zugangsdaten bleibt das Feature ausgeblendet. Ein Mac ist **nicht** nötig –
|
||
alles geht per OpenSSL.
|
||
|
||
Die fertigen Dateien und Werte trägst du am Ende als **Environment-Variablen** ein:
|
||
- **Lokal (Docker):** Dateien nach `backend/var/wallet/` legen (ist gitignored), Werte in `backend/.env.local`. Pfade sind Container-Pfade `/app/var/wallet/...`.
|
||
- **Produktiv:** Dateien außerhalb des Webroots auf den Server, Werte in der Server-Env / `.env.prod.local`.
|
||
|
||
---
|
||
|
||
## A) Apple Wallet (PassKit)
|
||
|
||
Voraussetzung: kostenpflichtiger **Apple Developer**-Account.
|
||
|
||
### 1. Pass Type ID anlegen
|
||
1. https://developer.apple.com/account → **Certificates, Identifiers & Profiles** → **Identifiers** → **+**.
|
||
2. Typ **Pass Type IDs** wählen → Beschreibung + Identifier vergeben, z. B. `pass.de.vcard4reseller.card`.
|
||
3. Dieser Identifier ist später `APPLE_WALLET_PASS_TYPE_ID`.
|
||
|
||
### 2. Privatschlüssel + CSR erzeugen (per OpenSSL)
|
||
```bash
|
||
mkdir -p backend/var/wallet && cd backend/var/wallet
|
||
openssl genrsa -out key.pem 2048
|
||
openssl req -new -key key.pem -out request.csr \
|
||
-subj "/emailAddress=DEINE@MAIL.de/CN=vcard4reseller Pass/O=vcard4reseller/C=DE"
|
||
```
|
||
`key.pem` ist dein **unverschlüsselter** Privatschlüssel (→ `APPLE_WALLET_KEY_PASSWORD` bleibt leer).
|
||
|
||
### 3. Zertifikat erstellen & als PEM speichern
|
||
1. Im Apple-Portal beim Pass Type ID → **Create Certificate** → die eben erzeugte `request.csr` hochladen.
|
||
2. Das resultierende `pass.cer` (DER) herunterladen → nach `backend/var/wallet/` legen → umwandeln:
|
||
```bash
|
||
openssl x509 -inform DER -in pass.cer -out cert.pem
|
||
```
|
||
→ `cert.pem` = `APPLE_WALLET_CERT_PATH`.
|
||
|
||
### 4. Apple-WWDR-Zwischenzertifikat
|
||
1. https://www.apple.com/certificateauthority/ → **Worldwide Developer Relations** Intermediate Certificate (aktuell **G4**) herunterladen (`AppleWWDRCAG4.cer`).
|
||
2. Umwandeln:
|
||
```bash
|
||
openssl x509 -inform DER -in AppleWWDRCAG4.cer -out wwdr.pem
|
||
```
|
||
→ `wwdr.pem` = `APPLE_WALLET_WWDR_PATH`.
|
||
|
||
### 5. Team ID
|
||
https://developer.apple.com/account → **Membership** → **Team ID** (10 Zeichen) = `APPLE_WALLET_TEAM_ID`.
|
||
|
||
### Ergebnis (Env)
|
||
```dotenv
|
||
APPLE_WALLET_PASS_TYPE_ID=pass.de.vcard4reseller.card
|
||
APPLE_WALLET_TEAM_ID=ABCDE12345
|
||
APPLE_WALLET_ORG_NAME=vcard4reseller
|
||
APPLE_WALLET_CERT_PATH=/app/var/wallet/cert.pem
|
||
APPLE_WALLET_KEY_PATH=/app/var/wallet/key.pem
|
||
APPLE_WALLET_KEY_PASSWORD=
|
||
APPLE_WALLET_WWDR_PATH=/app/var/wallet/wwdr.pem
|
||
```
|
||
|
||
> Falls du das Zertifikat als `.p12` aus dem Keychain exportierst statt per CSR:
|
||
> `openssl pkcs12 -legacy -in Cert.p12 -clcerts -nokeys -out cert.pem` und
|
||
> `openssl pkcs12 -legacy -in Cert.p12 -nocerts -nodes -out key.pem`.
|
||
|
||
---
|
||
|
||
## B) Google Wallet
|
||
|
||
Voraussetzung: Google-Konto + Google Cloud (kostenlos).
|
||
|
||
### 1. Wallet API aktivieren
|
||
https://console.cloud.google.com → Projekt wählen/anlegen → **APIs & Dienste** → **Google Wallet API** suchen → **Aktivieren**.
|
||
|
||
### 2. Issuer-Account anlegen
|
||
1. https://pay.google.com/business/console → **Google Wallet API** → Issuer-Profil anlegen.
|
||
2. Die **Issuer ID** (Zahl) = `GOOGLE_WALLET_ISSUER_ID`.
|
||
|
||
### 3. Service-Account + JSON-Key
|
||
1. Cloud Console → **IAM & Verwaltung** → **Dienstkonten** → **Dienstkonto erstellen**.
|
||
2. Anlegen, dann **Schlüssel** → **Neuen Schlüssel** → **JSON** → herunterladen.
|
||
3. JSON nach `backend/var/wallet/google-sa.json` legen → `GOOGLE_WALLET_SERVICE_ACCOUNT`.
|
||
|
||
### 4. Service-Account dem Issuer freigeben
|
||
Im **Google Pay & Wallet Console** → Issuer → **Users / Nutzer** → die **E-Mail des Dienstkontos**
|
||
(`...iam.gserviceaccount.com`) mit Rolle **Developer** hinzufügen. Sonst → 403 beim Speichern.
|
||
|
||
### Ergebnis (Env)
|
||
```dotenv
|
||
GOOGLE_WALLET_ISSUER_ID=3388000000000000000
|
||
GOOGLE_WALLET_SERVICE_ACCOUNT=/app/var/wallet/google-sa.json
|
||
GOOGLE_WALLET_CLASS_SUFFIX=vcard_generic
|
||
```
|
||
|
||
> **Demo-Modus:** Solange der Issuer noch nicht von Google freigegeben ist, können nur
|
||
> **Test-Nutzer** (im Pay & Wallet Console unter dem Issuer hinzugefügt) Pässe speichern.
|
||
> Für die Veröffentlichung muss der Issuer den Google-Freigabeprozess durchlaufen.
|
||
> Logos erscheinen nur, wenn das Firmen-Branding eine **öffentliche https-Logo-URL** hat.
|
||
|
||
---
|
||
|
||
## Aktivieren & testen
|
||
|
||
1. Werte in `backend/.env.local` (lokal) bzw. Server-Env eintragen.
|
||
2. Cache leeren: `docker compose exec php php bin/console cache:clear`.
|
||
3. Ein Mitarbeiter mit `shortCode` → öffentliche Profilseite zeigt jetzt den QR **„Zur Wallet hinzufügen"**.
|
||
Direktlinks: `/w/{shortCode}` (Landing), `/w/{shortCode}/apple.pkpass`, `/w/{shortCode}/google`.
|
||
4. Auf dem Smartphone scannen/öffnen → „Zu Apple/Google Wallet".
|
||
|
||
**Hinweis:** Self-signed Test-Zertifikate erzeugen technisch valide Pässe, werden aber von
|
||
Apple/Google **nicht akzeptiert** – für echte Pässe sind die obigen echten Zugangsdaten nötig.
|
||
Der automatische Over-the-air-Sync (Apple APNs / Google Objekt-Patch bei Datenänderung) ist
|
||
noch nicht umgesetzt; bisher wird der Pass beim Hinzufügen erzeugt.
|