From b316d0baf8df8f0a555eebb1d9bcbc88369b038d Mon Sep 17 00:00:00 2001 From: Thomas Peterson Date: Wed, 3 Jun 2026 22:33:22 +0200 Subject: [PATCH] Docs: Wallet-Setup-Anleitung (Apple & Google) per OpenSSL MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- deploy/README.md | 2 + docs/WALLET-SETUP.md | 112 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 114 insertions(+) create mode 100644 docs/WALLET-SETUP.md diff --git a/deploy/README.md b/deploy/README.md index b682e2a..e6353f4 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -94,6 +94,8 @@ per CI oder Service-Discovery.) ## Wallet-Pässe (Apple / Google) — optional +> **Ausführliche Schritt-für-Schritt-Anleitung: [`docs/WALLET-SETUP.md`](../docs/WALLET-SETUP.md).** + Auf der öffentlichen Profilseite erscheint ein QR „Zur Wallet hinzufügen" (Landing `/w/{code}`), sobald die Zugangsdaten gesetzt sind. Ohne Konfiguration ist das Feature ausgeblendet. diff --git a/docs/WALLET-SETUP.md b/docs/WALLET-SETUP.md new file mode 100644 index 0000000..a357223 --- /dev/null +++ b/docs/WALLET-SETUP.md @@ -0,0 +1,112 @@ +# 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.