Implementing a custom SSO Protocol

This guide explains how to extend the B2bSso addon in the B2B Platform by implementing a custom external Single Sign-On (SSO) protocol (e.g., OAuth).

All relative file paths in this guide refer to custom/plugins/b2bsellerscore/addons/B2bSso/.

Extension Point & Architecture

To add a custom protocol, extend the abstract base class AbstractSsoProtocol, which serves as the Service Provider Interface (SPI). For reference, review the default Auth0 implementation in Components/Protocol/Auth0.php.

Base Class Methods

function login(
    Request $request, 
    SalesChannelContext $context, 
    B2bSsoProvider $provider
): string

Starts the authentication flow. Read credentials from $provider->getConfig() and return the IdP authorization URL where the user should be redirected.

function callback(
    Request $request, 
    SalesChannelContext $context, 
    B2bSsoProvider $provider
): string

Handles the redirect back from the IdP. Exchange the authorization code, resolve the user, log them in, persist the subject ID, and return the target URL. The $provider is re-loaded from the providerId route parameter, providing the same configuration as in login().

Required Flow in callback()

Your callback() implementation must execute the following step-by-step logic:

1. Call getByToken($sub) using the IdP subject ID.

2. Fall back to getByEmail($email) if no token is linked yet.

3. Call updateEmail() if the email address has drifted.

4. Authenticate the user via loginEmployee() or loginCustomer() (refer to Auth0.php for branching logic).

5. Call saveToken($sub) to store the relation.

6. Return $this->generateResponseUrl($request);.

Step-by-Step Implementation

To register a custom protocol (e.g., oauth), create the following 5 files in your custom plugin (no database migrations required):

1. PHP Protocol Class

Create a class extending AbstractSsoProtocol within your plugin's namespace.

2. Service Definition

Register your service in services.xml using the b2bsellers_sso.protocol tag and pass the required positional arguments:

<service id="MyPlugin\Components\Protocol\MyOauthProtocol">
    <argument type="service" id="router"/>
    <argument type="service" id="B2bSso\Components\Services\B2bSsoLoginService"/>
    <argument type="service" id="B2bSellersCore\Components\Customer\Service\B2bAccountService"/>
    <tag name="b2bsellers_sso.protocol" key="oauth"/>
</service>

The key specified in your service tag (key="oauth") must exactly match the type column value of the provider entity. Otherwise, a protocolNotFound() exception is thrown.

3. Administration Vue Component

Create the Administration component b2b-sso-protocol-oauth. It accepts the props providerId and config, and emits changes via $emit('change', config). You can copy the reference component from Resources/app/administration/src/components/b2b-sso-protocol-auth0/.

4. Administration Override

Override b2b-sso-provider-detail-modal to include your new key in the protocols computed property:

JavaScript

Component.override('b2b-sso-provider-detail-modal', {
    computed: {
        protocols() {
            const protocols = this.$super('protocols');
            // Add your protocol key to the selection list
            return [...protocols, 'oauth'];
        }
    }
});

5. Snippets

Add admin translation snippets under b2bSso.ssoProtocol.oauth.*, mirroring the structure of the auth0 block.

Key Considerations

• No Automatic User Creation: B2bSso does not create customer accounts. The user or employee must already exist in Shopware. If no match is found, the system redirects to the login page with b2bSso.noConnectedUser.

• State / PKCE Handling: No built-in state or PKCE helpers are provided. You must handle CSRF protection and token verification manually within your protocol class.

• Schema Flexibility: Providers are not scoped to individual sales channels, and provider configuration is stored as a free-form JSON column, requiring no database schema changes.