Getting Started

Minimal Setup

Installation Add the bundle via Composer:

composer require digitalstate/platform-sso-bundle

Enable the bundle in config/bundles.php:

return [
    // ...
    DigitalState\Bundle\PlatformSSOBundle\DigitalStatePlatformSSOBundle::class => ['all' => true],
];

Configuration Publish the default configuration:

php bin/console digitalstate:platform-sso:install

Edit config/packages/digitalstate_platform_sso.yaml to define your SSO providers (e.g., Google, Facebook, LinkedIn). Example:

digitalstate_platform_sso:
    providers:
        google:
            enabled: true
            client_id: 'your_client_id'
            client_secret: 'your_client_secret'
            redirect_uri: 'https://your-app.com/connect/google/check'

First Use Case Add a login button for a provider (e.g., Google) in your template:
```
<a href="{{ path('oro_sso_connect', {'provider': 'google'}) }}" class="btn btn-google">
    Login with Google
</a>
```
The bundle handles authentication flow, token exchange, and user creation/association.

Where to Look First

Configuration: config/packages/digitalstate_platform_sso.yaml (provider settings, routes).
Commands: php bin/console list digitalstate (e.g., digitalstate:platform-sso:install).
Templates: Override Twig templates in templates/DigitalStatePlatformSSOBundle/ if needed.
Events: Listen to oro_sso.connect.success or oro_sso.connect.failure for custom logic.

Implementation Patterns

Core Workflow

Provider Registration Define providers in digitalstate_platform_sso.yaml with required credentials (client ID, secret, redirect URI). Example for LinkedIn:

linkedin:
    enabled: true
    client_id: 'linkedin_client_id'
    client_secret: 'linkedin_secret'
    scope: ['r_liteprofile', 'r_emailaddress']
    redirect_uri: 'https://your-app.com/connect/linkedin/check'

Authentication Flow
- User clicks a provider-specific link (e.g., /connect/google).
- Bundle redirects to the provider’s OAuth endpoint.
- After authorization, the provider redirects back to your redirect_uri with a code.
- Bundle exchanges the code for an access token and user data.
User Handling
- New Users: Triggers oro_sso.user.create event. Override the event listener to create a custom user.
- Existing Users: Links the SSO account to an existing user via oro_sso.user.link event.
- User Data Mapping: Use digitalstate_platform_sso.user.provider_mapping to map provider fields (e.g., email, first_name) to your user entity.

Custom Providers Extend the bundle by creating a custom provider class:

namespace App\SSO\Provider;

use DigitalState\Bundle\PlatformSSOBundle\Provider\AbstractProvider;

class CustomProvider extends AbstractProvider
{
    protected function getAuthUrl(): string
    {
        return 'https://custom-provider.com/oauth/authorize';
    }

    protected function getTokenUrl(): string
    {
        return 'https://custom-provider.com/oauth/token';
    }

    protected function getUserDataUrl(): string
    {
        return 'https://custom-provider.com/api/user';
    }
}

services:
    app.sso.provider.custom:
        class: App\SSO\Provider\CustomProvider
        tags:
            - { name: digitalstate_platform_sso.provider, provider: 'custom' }

Integration Tips

OroPlatform Integration The bundle extends OroSSOBundle, so it works seamlessly with OroCRM’s user management. Use Oro’s user entity (Oro\Bundle\UserBundle\Entity\User) for consistency.

Symfony Security Integrate with Symfony’s security system by configuring a firewall:

# config/packages/security.yaml
firewalls:
    main:
        form_login:
            provider: fos_userbundle
        oauth:
            resource_owners:
                google: '/connect/google/check'
                facebook: '/connect/facebook/check'
            login_path: /login
            use_forward: false
            failure_path: /login

Frontend Integration Use Twig to render provider buttons dynamically:

{% for provider in digitalstate_platform_sso_providers %}
    <a href="{{ path('oro_sso_connect', {'provider': provider.name}) }}">
        Login with {{ provider.title|default(provider.name) }}
    </a>
{% endfor %}

Testing Mock provider responses in tests using HTTP clients (e.g., Guzzle) or factory classes for user data.

Gotchas and Tips

Pitfalls

Redirect URI Mismatch
- Issue: OAuth providers reject requests if the redirect_uri in your config doesn’t match the one registered with the provider.
- Fix: Ensure redirect_uri in digitalstate_platform_sso.yaml matches the URI registered with the provider (e.g., https://your-app.com/connect/google/check).
State Parameter
- Issue: Some providers require a state parameter for CSRF protection. The bundle generates one automatically, but ensure your provider supports it.
- Fix: If using a custom provider, include the state in your auth URL:
```
$authUrl = $this->getAuthUrl() . '?state=' . $this->getState();
```
Scope Restrictions
- Issue: Providers like LinkedIn may block requests if scopes aren’t pre-approved in their developer console.
- Fix: Test scopes in the provider’s developer dashboard before deploying.
User Data Mapping
- Issue: Provider user data may not align with your user entity fields (e.g., given_name vs. first_name).
- Fix: Override the mapProviderDataToUser method in a custom provider or use the digitalstate_platform_sso.user.provider_mapping config:
```
user:
    provider_mapping:
        google:
            email: email
            first_name: given_name
            last_name: family_name
```
Caching Tokens
- Issue: Storing tokens in the session may cause issues with multi-tab sessions.
- Fix: Use a persistent storage (e.g., database) for tokens. Extend the bundle’s TokenStorage service.

Debugging Tips

Enable Debugging Set debug: true in digitalstate_platform_sso.yaml to log OAuth flows:
```
digitalstate_platform_sso:
    debug: true
```

Check Events Listen to oro_sso.connect.* events to debug failures:

// src/EventListener/SSOListener.php
namespace App\EventListener;

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Oro\Bundle\SSOBundle\Event\ConnectEvent;

class SSOListener implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            'oro_sso.connect.failure' => 'onConnectFailure',
        ];
    }

    public function onConnectFailure(ConnectEvent $event)
    {
        \Log::error('SSO Failure', [
            'provider' => $event->getProviderName(),
            'error' => $event->getError(),
        ]);
    }
}

Provider-Specific Logs For Google/Facebook, enable their respective debug modes:
- Google: Add ?approval_prompt=force to auth URLs for testing.
- Facebook: Use the Graph API Explorer to test endpoints.

Extension Points

Custom Provider Logic Override the AbstractProvider class to handle provider-specific quirks (e.g., token refresh logic).

User Creation/Linking Subscribe to oro_sso.user.create or oro_sso.user.link events to customize user data or roles:

# config/services.yaml
services:
    App\EventListener\CustomSSOUserListener:
        tags:
            - { name: kernel.event_subscriber }

Post-Auth Redirects Extend the bundle’s ConnectHandler to redirect users after SSO:

namespace App\SSO;

use DigitalState\Bundle\PlatformSSOBundle\Handler\ConnectHandlerInterface;

class CustomConnectHandler implements ConnectHandlerInterface
{
    public function handleSuccess(string $providerName, array $userData): void
    {
        // Custom logic (e.g., redirect to dashboard)
        return new RedirectResponse('/dashboard');
    }
}

Platform Sso Bundle Laravel Package