# 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…

- Seite: <https://www.datafirefly.com/de/documentation/dfsocialconnect-sw-4/>
- Sprache: de
- Aktualisiert am: 2026-06-17
- Weitere Sprachen: [fr](https://www.datafirefly.com/documentation/dfsocialconnect-sw/index.md), [en](https://www.datafirefly.com/en/documentation/dfsocialconnect-sw-2/index.md), [es](https://www.datafirefly.com/es/documentation/dfsocialconnect-sw-3/index.md), [it](https://www.datafirefly.com/it/documentation/dfsocialconnect-sw-5/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfsocialconnect-sw/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfsocialconnect-sw/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfsocialconnect-sw/index.md)
- Index: <https://www.datafirefly.com/de/documentation/llms.txt>

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.

Apple Sign In erfordert eine sorgfältige Konfiguration im Apple-Developer-Portal (Services ID, Team ID, Key ID, .p8-Schlüssel) und eine gültige HTTPS-Domain. Ohne diese sind nur Google und Facebook einsatzbereit. Das Plugin funktioniert problemlos auch mit nur einem aktivierten Anbieter.

## 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.

Auf Shopware 6.7 lädt die neue Meteor-Administration Plugin-Module automatisch ohne Admin-Build. Auf 6.6, falls das Menü „Social Connect" unter Kunden nach der Installation nicht erscheint, führen Sie `bin/console administration:build` aus und leeren Sie den Browser-Cache.

## 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: Aktivieren Sie den Toggle **„Mit Apple anmelden" aktivieren**.
   - **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.

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

**Die Apple-form_post-Callback-Falle.** Wenn Sie den Scope `name email` anfordern, schickt Apple den Callback als Cross-Site-POST, wodurch der SameSite-Lax-Session-Cookie nicht zurückgesendet wird. Die meisten Integrationen scheitern hier. DfSocialConnect setzt parallel einen HMAC-signierten State-Cookie im SameSite-None-Modus und validiert gegen diesen, wenn der Session-Cookie nicht verfügbar ist. Keine Konfiguration auf Ihrer Seite erforderlich, aber es setzt voraus, dass Ihr Shop strikt über HTTPS ausgeliefert wird (SameSite=None-Cookies benötigen `Secure`).

## 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.