DfSocialConnect SW: complete gids

DfSocialConnect voegt aan Shopware 6 sociale login met Google, Apple en Facebook toe, met een volledig analytisch dashboard in de administration. De plugin is bewust gebouwd zonder externe JWT-bibliotheek: de ES256-handtekening van het client_secret van Apple wordt native in PHP gegenereerd via openssl. Eén codebase dekt Shopware 6.6 en 6.7, zonder verplichte eigen build van de storefront of de administration. Deze gids behandelt de installatie, de configuratie per verkoopkanaal van elke provider, de weergave van de knoppen, het dashboard, het automatisch koppelen van accounts, de beveiliging en de probleemoplossing.

Vereisten

• Shopware 6.6.x of 6.7.x (6.5 wordt niet ondersteund, de plugin gebruikt AccountService::loginById dat in 6.6 is geïntroduceerd).
• PHP 8.2 of nieuwer, met de extensie openssl (gebruikt voor de ES256-handtekening en de HMAC van de state-cookie).
• Een geldige HTTPS-URL voor uw shop: alle OAuth-providers weigeren redirect-URI’s via HTTP in productie.

Installatie

1. Download DfSocialConnect-v1.0.1.zip vanuit uw DataFirefly-account.
2. Installeer de ZIP via Administration → Extensies → Mijn extensies → Extensie uploaden, of kopieer de uitgepakte map DfSocialConnect naar custom/plugins/.
3. Activeer de plugin en ververs de caches:

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

4. Bij de installatie maakt de plugin twee tabellen aan: df_social_account (sociale identiteiten gekoppeld aan de klanten) en df_social_log (gebeurtenissenlogboek voor het dashboard). Bij het verwijderen zonder de gegevens te behouden, worden deze twee tabellen gewist.

Algemene configuratie

Open Extensies → Mijn extensies → DataFirefly Social Connect → ⋯ → Configureren. Alle opties zijn per verkoopkanaal in te stellen via de native kiezer bovenaan de pagina: selecteer een kanaal om er specifieke waarden aan toe te kennen, of laat “Alle verkoopkanalen” staan voor gemeenschappelijke waarden.

De kaart Algemeen bevat:

• Stijl van de knoppen: “vol gekleurd” (standaard, in de officiële merkkleuren), “omlijnd” (sobere variant voor minimalistische thema’s) of “alleen pictogram” (zeer compact, ideaal op mobiel).
• Automatisch koppelen via geverifieerd e-mailadres: als de provider het e-mailadres bevestigt en er al een klant met dat adres bestaat, wordt de sociale identiteit aan dat account gekoppeld in plaats van een dubbel account aan te maken. Standaard ingeschakeld.
• Double opt-in overslaan: omdat de e-mailadressen van Google, Apple en Facebook al geverifieerd zijn, wordt de double opt-in standaard overgeslagen.
• Nieuwsbrief bij registratie: voegt een nieuwsbrief-opt-in toe aan accounts die via een sociale login zijn aangemaakt.
• Pogingen per uur (per IP): drempel voor de rate limiting van het authenticatieproces. Standaard 30, verhoog die als u veel bezoekers achter dezelfde NAT hebt.

Google Connect

1. Ga naar console.cloud.google.com → API’s en services → Inloggegevens.
2. Maak een OAuth 2.0-client-ID aan van het type Webapplicatie.
3. Voeg bij Geautoriseerde redirect-URI’s het volgende toe:

   https://uw-domein/df-social-connect/callback/google

   Voeg bij meerdere kanalen één regel per domein van een verkoopkanaal toe.

4. Kopieer Client ID en Client Secret naar de kaart Google Connect in de configuratie van de plugin en zet de schakelaar Google Connect activeren aan.

Het proces verloopt via OpenID Connect met PKCE S256, de gevraagde scope is openid email profile, en de nonce van de id_token wordt bij elke terugkeer aan serverzijde gevalideerd.

Apple Connect

Apple is veeleisender om in te stellen, maar biedt de beste gebruikerservaring op iOS en macOS.

1. Ga naar developer.apple.com → Certificates, Identifiers and Profiles.
2. Maak een App ID aan met de capability Sign In with Apple.
3. Maak een Services ID aan (bijvoorbeeld com.uw-merk.web) die aan de App ID is gekoppeld. In de configuratie ervan:
   • Domains: uw domein (zonder https://).
   • Return URLs: https://uw-domein/df-social-connect/callback/apple.
4. Maak een Key aan met de service Sign In with Apple, download het bestand AuthKey_XXXXX.p8 en noteer het bijbehorende Key ID.
5. Haal uw Team ID op, rechtsboven in het portaal.
6. Vul in de kaart Apple Connect van de plugin het volgende in:
   • Services ID (bijvoorbeeld com.uw-merk.web),
   • Team ID,
   • Key ID,
   • Private sleutel: plak de volledige inhoud van het .p8-bestand, inclusief de BEGIN- en END-regels.

   Zet de schakelaar Sign in with Apple activeren aan.

De met ES256 ondertekende client_secret JWT wordt bij elke aanvraag ter plekke uit de .p8-sleutel gegenereerd, zonder cache: er is geen rotatie te beheren.

Facebook Connect

1. Ga naar developers.facebook.com → Mijn apps en maak een App aan van het type Consumer.
2. Voeg het product Facebook Login → Settings toe.
3. Voeg bij Valid OAuth Redirect URIs het volgende toe:

   https://uw-domein/df-social-connect/callback/facebook

4. Haal App ID en App Secret op onder Settings → Basic en plak ze in de kaart Facebook Connect van de plugin. Zet de schakelaar aan.

De module roept de Graph API v21.0 aan met verplichte appsecret_proof (HMAC-SHA256-handtekening van het token met uw App Secret), wat Facebook aanbeveelt voor elke applicatie in productie.

Weergave van de knoppen in de storefront

Zodra ten minste één provider is geactiveerd en geconfigureerd, verschijnen de knoppen automatisch:

• op de pagina /account/login, direct onder het inlogformulier, voorafgegaan door de scheiding “of ga verder met”;
• op de pagina /account/register, op dezelfde plek;
• op de profielpagina van de klant (/account/profile) toont een blok Sociale koppelingen de al gekoppelde identiteiten met per identiteit een knop Ontkoppelen, en biedt het daarnaast de nog beschikbare providers aan.

Er is geen aanpassing van het thema nodig. De Twig-templates van de plugin breiden de Shopware-blokken page_account_login_login, page_account_register_content en page_account_profile_personal uit. Als uw aangepaste thema deze blokken al overschrijft en vergeet {{ parent() }} aan te roepen, voeg dat dan toe om de knoppen terug te krijgen.

De stijl aanpassen

De knoppen worden gestyled via Resources/app/storefront/src/scss/base.scss. Er worden standaard drie varianten geleverd (--default, --outline, --icon); voor verdere aanpassingen overschrijft u de klassen .df-social-connect__btn--google, --apple en --facebook in uw thema.

Analytisch dashboard

De administration biedt een eigen module onder Klanten → Social Connect. Vier kaarten, filterbaar op periode (7, 30 of 90 dagen) en op verkoopkanaal:

• Overzicht: aanmeldingen, registraties, gekoppelde accounts, algemeen slagingspercentage, fouten.
• Per provider: voortgangsbalken in de officiële kleuren van elk merk.
• Dagelijkse trend: ApexCharts-grafiek met meerdere reeksen (één lijn per provider).
• Recente activiteit: de 25 laatste gebeurtenissen met klant, provider, gebeurtenistype en melding.

De module is beveiligd met een eigen viewer-ACL: df_social_connect.viewer. Om een gebruikersrol toegang tot het dashboard te geven, opent u het profiel onder Instellingen → Systeem → Gebruikers en rechten en vinkt u de bijbehorende toestemming in de categorie Klanten aan.

Automatisch koppelen en voorkomen van dubbele accounts

Bij elke sociale aanmelding probeert de plugin drie opeenvolgende resoluties:

1. Directe lookup op het paar (provider, provider_user_id) in df_social_account. Gevonden: onmiddellijke login op de gekoppelde klant.
2. Koppeling via geverifieerd e-mailadres: als de provider het e-mailadres als geverifieerd heeft gemarkeerd en er in het verkoopkanaal een klant met dat adres bestaat, wordt de sociale identiteit aan dat account gekoppeld. Dat behoudt de bestelgeschiedenis en de klantgroep.
3. Aanmaken van een account: alleen als laatste redmiddel wordt er een nieuwe klant aangemaakt via AccountService::loginById, met een willekeurig wachtwoord dat nooit wordt hergebruikt, een neutrale aanhef en een minimaal adres gekoppeld aan het standaardland van het verkoopkanaal.

Het automatisch koppelen via e-mail schakelt u per verkoopkanaal uit in de algemene configuratie, als u bij elke sociale registratie liever een expliciete aanmaak afdwingt.

Beveiliging

• Met HMAC ondertekende OAuth-state: CSRF-bescherming op alle flows.
• PKCE S256 bij Google: de code_verifier verlaat de server nooit.
• OIDC-nonce aan serverzijde gevalideerd op de id_token van Google.
• appsecret_proof bij Facebook: het gebruikerstoken kan niet vanaf een andere client worden hergebruikt.
• Gehasht IP: de IP-adressen van de gebeurtenissen worden gehasht voordat ze in df_social_log worden opgeslagen.
• Rate limiting per IP, met een instelbare drempel per uur.
• Sanitisatie tegen open redirects: door de gebruiker aangeleverde retour-URL’s worden vóór elke doorverwijzing gecontroleerd tegen het domein van het verkoopkanaal.

Verwijderen

Deactiveer en verwijder de plugin via Mijn extensies. Als de optie Gebruikersgegevens behouden uitstaat, worden de twee tabellen df_social_account en df_social_log verwijderd. De klantaccounts blijven intact, alleen de sociale koppelingen en het gebeurtenissenlogboek worden gewist.

FAQ en probleemoplossing

Er verschijnt geen enkele knop op de inlogpagina. Controleer of (a) ten minste één provider zijn schakelaar aan heeft staan EN zijn inloggegevens in de configuratie zijn ingevuld; (b) u zich op het geconfigureerde verkoopkanaal bevindt; (c) het thema opnieuw is gecompileerd: bin/console assets:install && bin/console theme:compile && bin/console cache:clear.

Apple geeft invalid_client terug. De client_secret JWT is aan de kant van Apple afgekeurd. Controleer Services ID, Team ID, Key ID en of de inhoud van de .p8-sleutel de BEGIN- en END-regels bevat. Een afwijkende servertijd veroorzaakt deze fout eveneens, omdat de JWT dan een iat in de toekomst heeft.

Apple geeft bij de terugkeer een state-fout. Controleer of uw shop strikt via HTTPS wordt geserveerd (geen HTTP-naar-HTTPS-redirect op de callback) en of uw third-party cookies niet worden geblokkeerd door een frontproxy die SameSite=None zou herschrijven.

Facebook geeft Invalid appsecret_proof provided terug. De ingevoerde App Secret komt niet overeen met de App ID. Genereer die opnieuw via Settings → Basic van uw Facebook-app en plak hem opnieuw.

Het dashboard is leeg terwijl er wel aanmeldingen zijn geweest. Controleer het verkoopkanaalfilter bovenaan het dashboard: het beperkt alle statistieken. Kies “Alle verkoopkanalen” om het globale totaal te zien.

Een gebruiker heeft twee accounts: één via het formulier aangemaakt, één via Google. Het automatisch koppelen via e-mail stond uit, of het e-mailadres van het oorspronkelijke account was niet exact gelijk aan het adres dat Google teruggaf. Om samen te voegen verwijdert u het meest recente account en vraagt u de gebruiker opnieuw via Google in te loggen: de automatische koppeling verbindt hem dan met het behouden account.

Compatibel met Shopware 6.5? Nee. AccountService::loginById is in 6.6 geïntroduceerd; dat mechanisme staat centraal in de plugin en kan niet netjes worden teruggeport.