DfSocialConnect SW — Guida completa

DfSocialConnect aggiunge a Shopware 6 il login social con Google, Apple e Facebook, con una dashboard analitica completa integrata nell’admin. Il plugin è deliberatamente costruito senza alcuna libreria JWT esterna: la firma ES256 del client_secret di Apple è generata nativamente in PHP tramite openssl. Una sola codebase copre Shopware 6.6 e 6.7, senza build storefront o administration imposto. Questa guida copre installazione, configurazione per sales channel di ogni provider, visualizzazione dei pulsanti, dashboard, collegamento automatico degli account, sicurezza e risoluzione dei problemi.

Prerequisiti

• Shopware 6.6.x o 6.7.x (la 6.5 non è supportata; il plugin usa AccountService::loginById, introdotto in 6.6).
• PHP 8.2 o successivo, con l’estensione openssl (usata per la firma ES256 e l’HMAC del cookie di state).
• Una URL HTTPS valida per il negozio: tutti i provider OAuth rifiutano URI di redirect in HTTP in produzione.

Installazione

1. Scarichi DfSocialConnect-v1.0.1.zip dal suo account DataFirefly.
2. Installi lo ZIP tramite Amministrazione → Estensioni → Le mie estensioni → Carica estensione, oppure copi la cartella decompressa DfSocialConnect in custom/plugins/.
3. Attivi il plugin e svuoti le cache:

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

4. All’installazione, il plugin crea due tabelle: df_social_account (identità social collegate ai clienti) e df_social_log (registro eventi che alimenta la dashboard). Alla disinstallazione senza conservare i dati, entrambe le tabelle vengono eliminate.

Configurazione generale

Apra Estensioni → Le mie estensioni → DataFirefly Social Connect → ⋯ → Configura. Tutte le opzioni sono limitabili al sales channel tramite il selettore nativo in alto: scelga un canale per assegnargli valori specifici, oppure lasci «Tutti i sales channel» per valori comuni.

La scheda Generale contiene:

• Stile dei pulsanti: «colore pieno» (predefinito, tonalità ufficiali), «contorno» (variante sobria per temi minimalisti) o «solo icona» (molto compatto, ideale su mobile).
• Collegare automaticamente per email verificata: se il provider certifica l’email e un cliente esiste già con quell’indirizzo, l’identità social viene collegata a quell’account anziché creare un duplicato. Attivo per impostazione predefinita.
• Ignorare il double opt-in: poiché le email di Google, Apple o Facebook sono già verificate, il double opt-in viene saltato per impostazione predefinita.
• Newsletter alla registrazione: aggiunge un flag di opt-in newsletter agli account creati tramite login social.
• Tentativi all’ora (per IP): soglia di rate limiting del flow di autenticazione. Predefinito 30; aumentarlo se molti visitatori condividono un singolo NAT.

Google Connect

1. Vada su console.cloud.google.com → API e servizi → Credenziali.
2. Crei un ID client OAuth 2.0, tipo Applicazione Web.
3. In URI di reindirizzamento autorizzati, aggiunga:

   https://suo-dominio/df-social-connect/callback/google

   Per un multi-canale, aggiunga una riga per dominio di sales channel.

4. Incolli Client ID e Client Secret nella scheda Google Connect della configurazione del plugin e attivi il toggle Attiva Google Connect.

Il flow è OpenID Connect con PKCE S256, lo scope richiesto è openid email profile, e il nonce dell’id_token viene validato lato server a ogni ritorno.

Apple Connect

Apple è la configurazione più impegnativa, ma offre la migliore esperienza utente su iOS e macOS.

1. Vada su developer.apple.com → Certificates, Identifiers and Profiles.
2. Crei un App ID con la capability Sign In with Apple.
3. Crei un Services ID (ad esempio com.suo-brand.web) collegato all’App ID. Nella sua configurazione:
   • Domains: il suo dominio (senza https://).
   • Return URLs: https://suo-dominio/df-social-connect/callback/apple.
4. Crei una Key con il servizio Sign In with Apple attivato, scarichi il file AuthKey_XXXXX.p8 e annoti il suo Key ID.
5. Recuperi il Team ID in alto a destra del portale.
6. Nella scheda Apple Connect del plugin, compili:
   • Services ID (es. com.suo-brand.web),
   • Team ID,
   • Key ID,
   • Chiave privata: incolli il contenuto completo del .p8, righe BEGIN/END comprese.

   Attivi il toggle Attiva Sign in with Apple.

Il JWT client_secret firmato in ES256 è generato al volo a ogni richiesta dalla sua chiave .p8, senza cache: nessuna rotazione da gestire.

Facebook Connect

1. Vada su developers.facebook.com → Le mie app e crei un’App di tipo Consumer.
2. Aggiunga il prodotto Facebook Login → Settings.
3. In Valid OAuth Redirect URIs, aggiunga:

   https://suo-dominio/df-social-connect/callback/facebook

4. Recuperi App ID e App Secret in Settings → Basic e li incolli nella scheda Facebook Connect. Attivi il toggle.

Il modulo chiama la Graph API v21.0 con appsecret_proof obbligatorio (firma HMAC-SHA256 del token con il suo App Secret), che Facebook raccomanda per ogni app in produzione.

Visualizzazione dei pulsanti nello storefront

Una volta attivato e configurato almeno un provider, i pulsanti appaiono automaticamente:

• nella pagina /account/login, subito sotto il modulo di login, preceduti dal separatore «o continuare con»;
• nella pagina /account/register, nella stessa posizione;
• nella pagina profilo del cliente (/account/profile), un blocco Accessi social elenca le identità già collegate con un pulsante Disconnetti per identità e mostra i provider rimanenti come pulsanti per collegarsi.

Non è necessario sovrascrivere il tema. I template Twig del plugin estendono i blocchi page_account_login_login, page_account_register_content e page_account_profile_personal di Shopware. Se il suo tema personalizzato sovrascrive già questi blocchi e dimentica di chiamare {{ parent() }}, lo aggiunga per reincludere i pulsanti.

Personalizzare lo stile

I pulsanti sono stilati tramite Resources/app/storefront/src/scss/base.scss. Sono fornite tre varianti di base (--default, --outline, --icon); per personalizzazioni più spinte, sovrascriva le classi .df-social-connect__btn--google, --apple e --facebook nel suo tema.

Dashboard analitica

L’amministrazione espone un modulo dedicato sotto Clienti → Social Connect. Quattro schede filtrabili per periodo (7, 30 o 90 giorni) e per sales channel:

• Panoramica: login, registrazioni, collegamenti, tasso globale di successo, errori.
• Per provider: barre di progresso nei colori ufficiali di ogni marchio.
• Andamento giornaliero: curva multi-serie ApexCharts (una linea per provider).
• Attività recente: gli ultimi 25 eventi con cliente, provider, tipo di evento e messaggio.

Il modulo è protetto da un’ACL viewer dedicata: df_social_connect.viewer. Per dare accesso alla dashboard a un ruolo utente, apra il suo profilo in Impostazioni → Sistema → Utenti e permessi e attivi il permesso corrispondente nella categoria Clienti.

Collegamento automatico ed evitazione duplicati

A ogni login social, il plugin tenta tre risoluzioni successive:

1. Lookup diretto per coppia (provider, provider_user_id) in df_social_account. Trovato: login immediato sul cliente collegato.
2. Collegamento per email verificata: se il provider ha marcato l’email come verificata e un cliente esiste con quell’indirizzo nel sales channel, l’identità social viene collegata a quell’account. Preserva lo storico ordini e il gruppo cliente.
3. Creazione account: solo come ultima risorsa, viene creato un nuovo cliente tramite AccountService::loginById con una password casuale mai riutilizzata, un saluto neutro e un indirizzo minimo legato al paese predefinito del sales channel.

Il collegamento automatico per email è disattivabile per sales channel nella configurazione generale, se preferisce forzare la creazione esplicita a ogni registrazione social.

Sicurezza

• State OAuth firmato HMAC: protezione CSRF su ogni flow.
• PKCE S256 su Google: il code_verifier non lascia mai il server.
• Nonce OIDC validato lato server sull’id_token di Google.
• appsecret_proof Facebook: il token utente non può essere riutilizzato da un altro client.
• IP hashato: gli indirizzi IP degli eventi vengono hashati prima di essere scritti in df_social_log.
• Rate limiting per IP, soglia configurabile per ora.
• Sanificazione anti open-redirect: gli URL di ritorno forniti dall’utente sono verificati contro il dominio del sales channel prima di ogni reindirizzamento.

Disinstallazione

Da Le mie estensioni, disattivi e disinstalli il plugin. Se l’opzione Mantieni i dati utente è disattivata, le due tabelle df_social_account e df_social_log vengono eliminate. Gli account cliente restano intatti — vengono cancellati solo i collegamenti social e il registro eventi.

FAQ e risoluzione dei problemi

Nessun pulsante appare nella pagina di login. Verifichi che (a) almeno un provider abbia il toggle attivato E le sue credenziali compilate; (b) si trovi sul sales channel configurato; (c) il tema sia stato ricompilato: bin/console assets:install && bin/console theme:compile && bin/console cache:clear.

Apple restituisce invalid_client. La validazione del client_secret JWT è fallita. Verifichi Services ID, Team ID, Key ID e che il contenuto del .p8 includa le righe BEGIN e END. Anche un orologio del server disallineato provoca questo errore perché l’iat del JWT finisce nel futuro.

Apple restituisce un errore di state al ritorno. Confermi che il negozio sia servito in HTTPS stretto (nessun redirect HTTP → HTTPS sul callback) e che nessun proxy frontale rimuova o riscriva l’attributo SameSite=None nelle intestazioni Set-Cookie in uscita.

Facebook restituisce Invalid appsecret_proof provided. L’App Secret inserito non corrisponde all’App ID. Lo rigeneri da Settings → Basic della sua App Facebook e lo incolli di nuovo.

La dashboard è vuota anche se ci sono stati dei login. Controlli il filtro sales channel in alto nella dashboard: limita ogni statistica. Scelga «Tutti i sales channel» per vedere l’aggregato globale.

Un utente ha due account: uno creato tramite il form, l’altro tramite Google. Il collegamento automatico per email era disattivato, o l’email dell’account originale non era strettamente identica a quella restituita da Google. Per unirli, elimini l’account più recente e chieda all’utente di riconnettersi tramite Google: il collegamento automatico legherà l’identità all’account conservato.

Compatibile con Shopware 6.5? No. AccountService::loginById è stato introdotto in 6.6; questo meccanismo è centrale per il plugin e non può essere portato indietro in modo pulito.