DfSocialConnect SW — Vollständiger Leitfaden

DfSocialConnect ergänzt Shopware 6 um Social Login mit Google, Apple und Facebook, mit einem vollständigen Analyse-Dashboard im Admin. Das Plugin verzichtet bewusst auf jede externe JWT-Bibliothek: die ES256-Signatur des client_secret für Apple wird nativ in PHP über openssl erzeugt. Eine einzige Codebasis deckt Shopware 6.6 und 6.7 ab, ohne erzwungenen Storefront- oder Admin-Build. Dieser Leitfaden behandelt Installation, sales-channel-spezifische Konfiguration jedes Anbieters, Button-Darstellung, Dashboard, automatische Konto-Verknüpfung, Sicherheit und Fehlerbehebung.

Voraussetzungen

• Shopware 6.6.x oder 6.7.x (6.5 wird nicht unterstützt; das Plugin nutzt AccountService::loginById, eingeführt in 6.6).
• PHP 8.2 oder neuer mit der openssl-Erweiterung (für ES256-Signierung und den HMAC-State-Cookie).
• Eine gültige HTTPS-URL für Ihren Shop: alle OAuth-Anbieter lehnen HTTP-Redirect-URIs in Produktion ab.

Installation

1. Laden Sie DfSocialConnect-v1.0.1.zip aus Ihrem DataFirefly-Konto.
2. Installieren Sie das ZIP über Administration → Erweiterungen → Meine Erweiterungen → Erweiterung hochladen, oder kopieren Sie den entpackten Ordner DfSocialConnect nach custom/plugins/.
3. Aktivieren Sie das Plugin und leeren Sie die Caches:

   bin/console plugin:refresh
   bin/console plugin:install --activate DfSocialConnect
   bin/console cache:clear

4. Bei der Installation legt das Plugin zwei Tabellen an: df_social_account (mit Kunden verknüpfte Social-Identitäten) und df_social_log (Event-Log für das Dashboard). Bei der Deinstallation ohne Datenerhalt werden beide Tabellen entfernt.

Allgemeine Konfiguration

Öffnen Sie Erweiterungen → Meine Erweiterungen → DataFirefly Social Connect → ⋯ → Konfigurieren. Alle Optionen lassen sich über den nativen Selektor oben auf der Seite auf einen Sales Channel scopen: wählen Sie einen Channel für kanalspezifische Werte, oder lassen Sie „Alle Sales Channels“ für gemeinsame Werte stehen.

Die Karte Allgemein enthält:

• Button-Stil: „Standard“ (vollfarbig, offizielle Markenfarben), „Umriss“ (zurückhaltend für minimalistische Themes) oder „Nur Icon“ (sehr kompakt, ideal mobil).
• Automatisch per verifizierter E-Mail verknüpfen: wenn der Anbieter die E-Mail als verifiziert kennzeichnet und ein Kunde mit dieser Adresse existiert, wird die Social-Identität diesem Konto zugeordnet statt ein Duplikat anzulegen. Standardmäßig aktiv.
• Double-Opt-In überspringen: da E-Mails von Google, Apple oder Facebook bereits verifiziert sind, wird Double-Opt-In standardmäßig übergangen.
• Newsletter-Anmeldung bei der Registrierung: setzt ein Newsletter-Opt-In-Flag auf Konten, die per Social Login angelegt werden.
• Versuche pro Stunde (pro IP): Rate-Limit-Schwelle für den Auth-Flow. Standardwert 30; erhöhen, falls viele Besucher hinter einem NAT sitzen.

Google Connect

1. Gehen Sie auf console.cloud.google.com → APIs & Dienste → Anmeldedaten.
2. Erstellen Sie eine OAuth-2.0-Client-ID, Typ Webanwendung.
3. Fügen Sie unter Autorisierte Weiterleitungs-URIs hinzu:

   https://ihre-domain/df-social-connect/callback/google

   Für Multi-Channel-Setups: eine Zeile pro Sales-Channel-Domain.

4. Tragen Sie Client ID und Client Secret in die Karte Google Connect der Plugin-Konfiguration ein und aktivieren Sie den Toggle Google Connect aktivieren.

Der Flow ist OpenID Connect mit PKCE S256, der angeforderte Scope openid email profile, und der Nonce im id_token wird serverseitig bei jeder Rückkehr validiert.

Apple Connect

Apple ist am aufwändigsten zu konfigurieren, liefert dafür aber die beste UX auf iOS und macOS.

1. Gehen Sie auf developer.apple.com → Certificates, Identifiers and Profiles.
2. Erstellen Sie eine App ID mit der Capability Sign In with Apple.
3. Erstellen Sie eine Services ID (z. B. com.ihre-marke.web) verknüpft mit der App ID. In ihrer Konfiguration:
   • Domains: Ihre Domain (ohne https://).
   • Return URLs: https://ihre-domain/df-social-connect/callback/apple.
4. Erstellen Sie einen Key mit aktiviertem Service Sign In with Apple, laden Sie die Datei AuthKey_XXXXX.p8 herunter und notieren Sie die Key ID.
5. Notieren Sie Ihre Team ID in der oberen rechten Ecke des Portals.
6. Tragen Sie in die Karte Apple Connect des Plugins ein:
   • Services ID (z. B. com.ihre-marke.web),
   • Team ID,
   • Key ID,
   • Privater Schlüssel: kompletten Inhalt der .p8 einfügen, BEGIN/END-Zeilen inklusive.

   Aktivieren Sie den Toggle „Mit Apple anmelden“ aktivieren.

Das ES256-signierte client_secret-JWT wird für jeden Request frisch aus Ihrer .p8 erzeugt, ohne Cache: keine Rotation zu verwalten.

Facebook Connect

1. Gehen Sie auf developers.facebook.com → Meine Apps und erstellen Sie eine App vom Typ Consumer.
2. Fügen Sie das Produkt Facebook Login → Settings hinzu.
3. Fügen Sie unter Valid OAuth Redirect URIs hinzu:

   https://ihre-domain/df-social-connect/callback/facebook

4. Holen Sie App ID und App Secret aus Settings → Basic und fügen Sie sie in die Karte Facebook Connect ein. Aktivieren Sie den Toggle.

Das Plugin ruft die Graph API v21.0 mit verpflichtendem appsecret_proof auf (HMAC-SHA256-Signatur des Tokens mit Ihrem App Secret), das Facebook für jede Produktiv-App empfiehlt.

Button-Darstellung im Storefront

Sobald mindestens ein Anbieter aktiviert und konfiguriert ist, erscheinen die Buttons automatisch:

• auf der Seite /account/login, direkt unter dem Login-Formular, mit dem Trenner „oder fortfahren mit“;
• auf der Seite /account/register, an gleicher Stelle;
• auf der Profilseite des Kunden (/account/profile): ein Block Social Logins listet die bereits verknüpften Identitäten mit einem Trennen-Button pro Identität und zeigt die übrigen Anbieter als Verknüpfen-Buttons.

Keine Theme-Überschreibung notwendig. Die Twig-Templates des Plugins erweitern die Blöcke page_account_login_login, page_account_register_content und page_account_profile_personal. Wenn Ihr Custom-Theme diese Blöcke bereits überschreibt und den Aufruf {{ parent() }} vergisst, ergänzen Sie ihn, damit die Buttons wieder eingebunden werden.

Eigenes Styling

Die Buttons werden in Resources/app/storefront/src/scss/base.scss gestylt. Drei Grundvarianten werden ausgeliefert (--default, --outline, --icon); für weitergehende Anpassungen überschreiben Sie in Ihrem Theme die Klassen .df-social-connect__btn--google, --apple und --facebook.

Analyse-Dashboard

Die Administration stellt unter Kunden → Social Connect ein eigenes Modul bereit. Vier Karten, filterbar nach Zeitraum (7, 30 oder 90 Tage) und Sales Channel:

• Übersicht: Logins, Registrierungen, Verknüpfungen, globale Erfolgsquote, Fehler.
• Nach Anbieter: Fortschrittsbalken in den offiziellen Markenfarben.
• Tagestrend: ApexCharts-Mehrseriengrafik (eine Linie pro Anbieter).
• Letzte Aktivität: die 25 jüngsten Ereignisse mit Kunde, Anbieter, Ereignistyp und Meldung.

Das Modul wird über eine dedizierte Viewer-ACL geschützt: df_social_connect.viewer. Um einer Benutzerrolle Dashboard-Zugriff zu gewähren, öffnen Sie ihr Profil unter Einstellungen → System → Benutzer und Berechtigungen und setzen das entsprechende Recht in der Kategorie Kunden.

Automatische Verknüpfung und Duplikatvermeidung

Bei jedem Social Login durchläuft das Plugin drei Auflösungsebenen:

1. Direkter Lookup nach dem Paar (Anbieter, provider_user_id) in df_social_account. Gefunden: sofortiger Login beim verknüpften Kunden.
2. Verknüpfung per verifizierter E-Mail: wenn der Anbieter die E-Mail als verifiziert markierte und im Sales Channel ein Kunde mit dieser Adresse existiert, wird die Social-Identität diesem Konto zugeordnet. Bestellhistorie und Kundengruppe bleiben erhalten.
3. Kontoanlage: nur als letztes Mittel wird über AccountService::loginById ein neuer Kunde angelegt, mit nie wiederverwendetem Zufallspasswort, neutraler Anrede und minimaler Adresse, die an das Standardland des Sales Channels gebunden ist.

Die automatische Verknüpfung per E-Mail lässt sich pro Sales Channel in der allgemeinen Konfiguration deaktivieren, falls Sie bei jeder Social-Registrierung eine explizite Kontoanlage erzwingen wollen.

Sicherheit

• HMAC-signierter OAuth-State: CSRF-Schutz in jedem Flow.
• PKCE S256 bei Google: der code_verifier verlässt nie den Server.
• OIDC-Nonce serverseitig validiert auf Googles id_token.
• Facebook appsecret_proof: das User-Token kann nicht von einem anderen Client wiederverwendet werden.
• Gehashte IP: IP-Adressen der Events werden vor dem Schreiben in df_social_log gehasht.
• Rate Limiting pro IP, Schwelle pro Stunde konfigurierbar.
• Open-Redirect-Säuberung: vom Nutzer übergebene Rückkehr-URLs werden vor jeder Weiterleitung gegen die Domain des Sales Channels geprüft.

Deinstallation

Unter Meine Erweiterungen Plugin deaktivieren und deinstallieren. Wenn Benutzerdaten behalten ausgeschaltet ist, werden die beiden Tabellen df_social_account und df_social_log gelöscht. Kundenkonten bleiben unberührt — nur die Social-Verknüpfungen und das Event-Log werden entfernt.

FAQ und Fehlerbehebung

Auf der Login-Seite erscheint kein Button. Prüfen Sie, dass (a) mindestens ein Anbieter seinen Toggle aktiviert UND seine Zugangsdaten eingetragen hat; (b) Sie sich auf dem konfigurierten Sales Channel befinden; (c) das Theme neu gebaut wurde: bin/console assets:install && bin/console theme:compile && bin/console cache:clear.

Apple liefert invalid_client. Die Validierung des client_secret-JWT ist fehlgeschlagen. Prüfen Sie Services ID, Team ID, Key ID und ob der .p8-Inhalt die BEGIN- und END-Zeilen enthält. Auch eine driftende Server-Uhr löst diesen Fehler aus, weil der JWT-iat in der Zukunft landet.

Apple liefert einen State-Fehler bei der Rückkehr. Stellen Sie sicher, dass Ihr Shop strikt über HTTPS bedient wird (keine HTTP-zu-HTTPS-Weiterleitung auf dem Callback) und dass kein vorgeschalteter Proxy das Attribut SameSite=None in ausgehenden Set-Cookie-Headern entfernt oder umschreibt.

Facebook liefert Invalid appsecret_proof provided. Das eingetragene App Secret passt nicht zur App ID. Generieren Sie es unter Settings → Basic Ihrer Facebook-App neu und fügen Sie es erneut ein.

Das Dashboard ist leer, obwohl Logins stattfanden. Prüfen Sie den Sales-Channel-Filter oben im Dashboard: er scopt jede Statistik. Wählen Sie „Alle Sales Channels“, um den globalen Aggregat zu sehen.

Ein Nutzer hat zwei Konten: eines per Formular, eines per Google angelegt. Die automatische Verknüpfung per E-Mail war ausgeschaltet, oder die E-Mail des ursprünglichen Kontos war nicht exakt identisch mit jener von Google. Zum Zusammenführen löschen Sie das jüngere Konto und bitten Sie den Nutzer, sich erneut über Google anzumelden: die automatische Verknüpfung hängt die Identität an das verbleibende Konto.

Kompatibel mit Shopware 6.5? Nein. AccountService::loginById wurde in 6.6 eingeführt; es ist zentral für das Plugin und lässt sich nicht sauber rückportieren.