# DfSocialConnect SW — Complete guide

> DfSocialConnect adds Google, Apple and Facebook social login to Shopware 6, with a complete analytics dashboard built into the admin. The plugin is deliberately built without any external JWT library:…

- Page: <https://www.datafirefly.com/en/documentation/dfsocialconnect-sw-2/>
- Language: en
- Last updated: 2026-06-17
- Other languages: [fr](https://www.datafirefly.com/documentation/dfsocialconnect-sw/index.md), [es](https://www.datafirefly.com/es/documentation/dfsocialconnect-sw-3/index.md), [de](https://www.datafirefly.com/de/documentation/dfsocialconnect-sw-4/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/en/documentation/llms.txt>

DfSocialConnect adds Google, Apple and Facebook social login to Shopware 6, with a complete analytics dashboard built into the admin. The plugin is deliberately built without any external JWT library: the ES256 client_secret signature for Apple is generated natively in PHP via openssl. A single codebase covers Shopware 6.6 and 6.7, with no forced storefront or administration build. This guide walks through installation, per-sales-channel configuration of each provider, button rendering, the dashboard, automatic account linking, security and troubleshooting.

Apple Sign In requires a non-trivial setup on the Apple Developer portal (Services ID, Team ID, Key ID, .p8 key) and a valid HTTPS domain. Without those, only Google and Facebook will be operational. The plugin works perfectly well with a single provider enabled.

## Prerequisites

- Shopware **6.6.x** or **6.7.x** (6.5 is not supported; the plugin relies on `AccountService::loginById`, introduced in 6.6).
- PHP 8.2 or newer, with the `openssl` extension (used for ES256 signing and the HMAC state cookie).
- A valid HTTPS URL for your shop: every OAuth provider rejects HTTP redirect URIs in production.

## Installation

1. Download `DfSocialConnect-v1.0.1.zip` from your DataFirefly account.
2. Install the ZIP via **Administration → Extensions → My extensions → Upload extension**, or copy the unpacked `DfSocialConnect` folder into `custom/plugins/`.
3. Activate the plugin and refresh caches: ``` bin/console plugin:refresh bin/console plugin:install --activate DfSocialConnect bin/console cache:clear ```
4. On install, the plugin creates two tables: `df_social_account` (social identities linked to customers) and `df_social_log` (event log feeding the dashboard). On uninstall without keeping user data, both tables are dropped.

On Shopware 6.7, the new Meteor administration loads plugin modules automatically with no admin build. On 6.6, if the "Social Connect" menu under Customers does not appear after installation, run `bin/console administration:build` and clear the browser cache.

## General configuration

Open **Extensions → My extensions → DataFirefly Social Connect → ⋯ → Configure**. Every option is scopable to a sales channel via the native selector at the top of the page: pick a channel to set channel-specific values, or leave "All sales channels" to share them.

The **General** card includes:

- **Button style**: "default" (full brand colours), "outline" (subtle variant for minimal themes), or "icon only" (very compact, ideal on mobile).
- **Auto-link by verified e-mail**: if the provider flags the e-mail as verified and a customer already exists with that address, the social identity is attached to that account instead of creating a duplicate. On by default.
- **Skip double opt-in**: since e-mails from Google, Apple or Facebook are already verified, double opt-in is bypassed by default.
- **Newsletter opt-in on registration**: adds a newsletter opt-in flag on accounts created via social login.
- **Attempts per hour (per IP)**: rate-limiting threshold for the auth flow. Defaults to 30; raise it if many visitors share a single NAT.

## Google Connect

1. Go to **console.cloud.google.com → APIs & Services → Credentials**.
2. Create an **OAuth 2.0 Client ID**, type **Web application**.
3. Under **Authorised redirect URIs**, add: ``` https://your-domain/df-social-connect/callback/google ``` For a multi-channel setup, add one line per sales-channel domain.
4. Paste **Client ID** and **Client Secret** into the **Google Connect** card in the plugin configuration, and turn on the **Enable Google Connect** toggle.

The flow uses OpenID Connect with PKCE S256, the scope requested is `openid email profile`, and the `id_token` nonce is validated server-side on every return.

## Apple Connect

Apple is the most demanding to set up, but it delivers the best UX on iOS and macOS.

1. Go to **developer.apple.com → Certificates, Identifiers and Profiles**.
2. Create an **App ID** with the _Sign In with Apple_ capability.
3. Create a **Services ID** (e.g. `com.your-brand.web`) linked to that App ID. In its configuration:
   - **Domains**: your domain (without `https://`).
   - **Return URLs**: `https://your-domain/df-social-connect/callback/apple`.
4. Create a **Key** with the _Sign In with Apple_ service enabled, download the `AuthKey_XXXXX.p8` file and note its **Key ID**.
5. Grab your **Team ID** from the top-right corner of the portal.
6. In the **Apple Connect** card of the plugin, fill in: Turn on the **Enable Sign in with Apple** toggle.
   - **Services ID** (e.g. `com.your-brand.web`),
   - **Team ID**,
   - **Key ID**,
   - **Private key**: paste the full contents of the `.p8`, including the BEGIN/END lines.

The ES256-signed client_secret JWT is generated on the fly for every request from your .p8 key, no caching: no rotation to manage.

**The Apple form_post callback pitfall.** When you request the `name email` scope, Apple posts the callback as a cross-site POST, which prevents the SameSite Lax session cookie from being sent back. Most integrations break here. DfSocialConnect also sets a parallel HMAC-signed state cookie in SameSite None and validates against it when the session cookie is unavailable. No configuration on your side, but it assumes your shop is served over strict HTTPS (SameSite=None cookies require `Secure`).

## Facebook Connect

1. Go to **developers.facebook.com → My Apps** and create a **Consumer** app.
2. Add the **Facebook Login → Settings** product.
3. Under **Valid OAuth Redirect URIs**, add: ``` https://your-domain/df-social-connect/callback/facebook ```
4. Grab **App ID** and **App Secret** from **Settings → Basic**, and paste them into the **Facebook Connect** card. Turn on the toggle.

The plugin calls Graph API v21.0 with mandatory `appsecret_proof` (HMAC-SHA256 signature of the token with your App Secret), which is Facebook's recommended hardening for any production app.

## Storefront button rendering

Once at least one provider is enabled and configured, the buttons appear automatically:

- on the **/account/login** page, right below the login form, preceded by an "or continue with" divider;
- on the **/account/register** page, in the same position;
- in the customer's **profile page** (`/account/profile`), a **Social logins** block lists the linked identities with a _Disconnect_ button per identity, and shows the remaining providers as Link buttons.

No theme override is needed. The plugin's Twig templates extend the `page_account_login_login`, `page_account_register_content` and `page_account_profile_personal` blocks. If your custom theme already overrides these blocks and forgets to call `{{ parent() }}`, add it back to re-include the buttons.

### Custom styling

Buttons are styled via `Resources/app/storefront/src/scss/base.scss`. Three baseline variants are shipped (`--default`, `--outline`, `--icon`); for further customisation, override the `.df-social-connect__btn--google`, `--apple` and `--facebook` classes in your theme.

## Analytics dashboard

The administration exposes a dedicated module under **Customers → Social Connect**. Four cards filterable by period (7, 30 or 90 days) and by sales channel:

- **Overview**: logins, registrations, links, global success rate, errors.
- **By provider**: progress bars in each brand's official colour.
- **Daily trend**: multi-series ApexCharts curve (one line per provider).
- **Recent activity**: the 25 latest events with customer, provider, event type and message.

The module is protected by a dedicated viewer ACL: `df_social_connect.viewer`. To grant dashboard access to a user role, open its profile under **Settings → System → Users and permissions** and tick the matching permission under the _Customers_ category.

## Auto-linking and deduplication

On every social login, the plugin runs three resolution layers:

1. **Direct lookup** by (provider, `provider_user_id`) pair in `df_social_account`. Found: immediate login on the linked customer.
2. **Link by verified e-mail**: if the provider flagged the e-mail as verified and a customer exists with that address on the sales channel, the social identity is attached to that account. Preserves order history and customer group.
3. **Account creation**: as a last resort only, a new customer is created via `AccountService::loginById` with a never-reused random password, a neutral salutation and a minimal address tied to the sales channel's default country.

Auto-link by e-mail is disablable per sales channel in the general configuration if you prefer to force explicit account creation on every social registration.

## Security

- **HMAC-signed OAuth state**: CSRF protection on every flow.
- **PKCE S256** on Google: the `code_verifier` never leaves the server.
- **OIDC nonce** validated server-side on Google's `id_token`.
- **Facebook appsecret_proof**: the user access token cannot be replayed from another client.
- **Hashed IP**: event IP addresses are hashed before being written to `df_social_log`.
- **Rate limiting** per IP, threshold configurable per hour.
- **Open-redirect sanitisation**: user-provided return URLs are checked against the sales channel's domain before any redirect.

## Uninstallation

From **My extensions**, deactivate and uninstall the plugin. If _Keep user data_ is off, the two tables `df_social_account` and `df_social_log` are dropped. Customer accounts remain intact — only social links and the event log are erased.

## FAQ and troubleshooting

**No button shows up on the login page.** Check that (a) at least one provider has its toggle _on_ AND its credentials filled in; (b) you are on the configured sales channel; (c) the theme has been rebuilt: `bin/console assets:install && bin/console theme:compile && bin/console cache:clear`.

**Apple returns invalid_client.** The client_secret JWT failed validation. Check Services ID, Team ID, Key ID and that the .p8 contents include the BEGIN and END lines. A drifted server clock also triggers this because the JWT `iat` ends up in the future.

**Apple returns a state error on return.** Confirm your shop is served over strict HTTPS (no HTTP → HTTPS redirect on the callback) and that no front proxy strips or rewrites the `SameSite=None` attribute on outgoing Set-Cookie headers.

**Facebook returns Invalid appsecret_proof provided.** The App Secret entered does not match the App ID. Regenerate it from **Settings → Basic** on your Facebook App and paste it back.

**The dashboard is empty although there have been logins.** Check the sales channel filter at the top of the dashboard: it scopes every statistic. Pick "All sales channels" to view the global aggregate.

**A user has two accounts: one created via the form, one via Google.** Auto-link by e-mail was off, or the original account's e-mail was not strictly identical to the one returned by Google. To merge, delete the most recent account and ask the user to log in again via Google: auto-link will attach the identity to the retained account.

**Compatible with Shopware 6.5?** No. `AccountService::loginById` was introduced in 6.6; it is central to the plugin and cannot be back-ported cleanly.