> For the complete documentation index, see [llms.txt](https://docs.b2b-sellers.com/b2b-platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.b2b-sellers.com/b2b-platform/developer-guide/how-to/implementing-a-custom-sso-protocol.md).

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

{% hint style="info" %}
All relative file paths in this guide refer to `custom/plugins/b2bsellerscore/addons/B2bSso/`.
{% endhint %}

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

<pre class="language-php" data-overflow="wrap"><code class="lang-php"><strong>function login(
</strong><strong>    Request $request, 
</strong><strong>    SalesChannelContext $context, 
</strong><strong>    B2bSsoProvider $provider
</strong><strong>): string
</strong></code></pre>

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

<pre class="language-php" data-overflow="wrap"><code class="lang-php"><strong>function callback(
</strong><strong>    Request $request, 
</strong><strong>    SalesChannelContext $context, 
</strong><strong>    B2bSsoProvider $provider
</strong><strong>): string
</strong></code></pre>

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:

```xml
<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>
```

{% hint style="warning" %}
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.
{% endhint %}

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.b2b-sellers.com/b2b-platform/developer-guide/how-to/implementing-a-custom-sso-protocol.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.