Platform Sso Linkedin Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add the package via Composer:

   composer require digitalstate/platform-sso-linkedin-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       DigitalState\PlatformSsoLinkedinBundle\DigitalStatePlatformSsoLinkedinBundle::class => ['all' => true],
   ];
   

2. Configure LinkedIn SSO Navigate to System -> Configuration -> Integrations -> LinkedIn Settings in the OroPlatform admin panel.

   • Client ID & Secret: Register an application in LinkedIn Developer Portal and add the credentials.
   • Callback URL: Set to https://your-app.com/linkedin/connect (adjust domain).
   • Scope: Define required permissions (e.g., r_liteprofile, email_address).

3. First Use Case: Enable LinkedIn Login

   • Create a SSO Provider in OroPlatform:
     • Go to System -> Users & Roles -> SSO Providers.
     • Add a new provider with type linkedin.
     • Assign it to user groups or roles.
   • Test the flow by visiting the login page and selecting "Login with LinkedIn."

Implementation Patterns

Workflow: User Authentication Flow

1. Initiate Login The bundle injects a "Login with LinkedIn" button on the login page (if configured).

   • Triggered via ds_sso_linkedin.connect route.

2. OAuth Handshake

   • Redirects to LinkedIn’s OAuth endpoint.
   • After user approval, LinkedIn redirects back to the configured callback URL with an authorization_code.

3. Token Exchange & User Data Fetch

   • The bundle exchanges the authorization_code for an access token (via LinkedIn\OAuth2\Client).
   • Fetches user profile data (e.g., id, email, firstName, lastName) using the access token.

4. User Mapping

   • Uses the DsSSOBundle's user provider to map LinkedIn data to your platform’s user model.
   • Default mapping:

     # config/packages/ds_sso_linkedin.yaml
     ds_sso_linkedin:
         user_provider:
             property_mappings:
                 email: email
                 first_name: firstName
                 last_name: lastName
     

   • Extend via custom providers (see Extension Points).

5. Post-Auth Redirect

   • Redirects to the configured post-login route (default: /).

Integration Tips

1. Custom User Fields Extend the user provider to map additional LinkedIn fields (e.g., profilePicture):

   // src/Provider/CustomLinkedInUserProvider.php
   namespace App\Provider;
   
   use DigitalState\PlatformSsoLinkedinBundle\Provider\LinkedInUserProvider;
   use Oro\Platform\Security\Authentication\UserProviderInterface;
   
   class CustomLinkedInUserProvider extends LinkedInUserProvider
   {
       public function loadUserByLinkedInData(array $data)
       {
           $user = parent::loadUserByLinkedInData($data);
           $user->setCustomField($data['pictureUrls']['narrow48']); // Example
           return $user;
       }
   }
   

   Register in config/packages/ds_sso_linkedin.yaml:

   ds_sso_linkedin:
       user_provider: App\Provider\CustomLinkedInUserProvider
   

2. Role Assignment Assign roles dynamically based on LinkedIn data (e.g., premium users):

   ds_sso_linkedin:
       role_assigner:
           enabled: true
           roles:
               - 'ROLE_PREMIUM' # Assign if LinkedIn profile has a specific field
   

3. Error Handling

   • Log OAuth errors via monolog:

     $this->logger->error('LinkedIn OAuth failed', ['error' => $e->getMessage()]);
     

   • Customize error messages in templates (templates/ds_sso_linkedin/login.html.twig).

4. Testing

   • Use LinkedIn’s OAuth Sandbox for testing.
   • Mock the OAuth client in PHPUnit:

     $this->mock(OAuth2\Client::class)
          ->shouldReceive('getAccessToken')
          ->andReturn(new OAuth2\AccessToken(['access_token' => 'mock_token']));
     

Gotchas and Tips

Pitfalls

1. Callback URL Mismatch

   • LinkedIn’s OAuth requires exact URL matching (including http/https).
   • Fix: Verify the callback URL in both:
     • OroPlatform admin (LinkedIn Settings).
     • LinkedIn Developer Portal (Auth tab).

2. Token Expiry

   • LinkedIn access tokens expire after 60 days.
   • Solution: Implement token refresh logic in a custom provider or use the bundle’s built-in refresh handler:

     ds_sso_linkedin:
         token_refresh:
             enabled: true
     

3. Scope Restrictions

   • LinkedIn’s r_emailaddress scope requires premium approval.
   • Workaround: Use r_liteprofile and prompt users to manually add their email.

4. User Data Changes

   • LinkedIn users can modify their profile (e.g., email).
   • Mitigation: Sync user data on every login by clearing cached user providers.

Debugging

1. Enable Debug Mode Add to config/packages/dev/ds_sso_linkedin.yaml:

   ds_sso_linkedin:
       debug: true
   

   • Logs OAuth requests/responses to var/log/dev.log.

2. Common Errors

   Error	Cause	Solution
   invalid_client	Wrong Client ID/Secret	Recheck LinkedIn Developer Portal
   redirect_uri_mismatch	Callback URL mismatch	Update in both OroPlatform and LinkedIn
   insufficient_scope	Missing required scopes	Add scopes in LinkedIn Settings
   user_not_found	No matching user in your DB	Implement custom user provider

3. Database Issues

   • Ensure the sso_provider and sso_user tables exist (run migrations if needed):

     php bin/console doctrine:migrations:execute
     

Extension Points

1. Custom User Provider Override DigitalState\PlatformSsoLinkedinBundle\Provider\LinkedInUserProvider to:

   • Add custom logic for user creation/updates.
   • Example: Sync LinkedIn’s headline to a custom user field.

2. Pre/Post Auth Events Listen to events in services.yaml:

   services:
       App\EventListener\LinkedInAuthListener:
           tags:
               - { name: kernel.event_listener, event: ds_sso_linkedin.pre_auth, method: onPreAuth }
               - { name: kernel.event_listener, event: ds_sso_linkedin.post_auth, method: onPostAuth }
   

3. UI Customization

   • Override the login button template:

     {# templates/ds_sso_linkedin/login_button.html.twig #}
     <button class="your-custom-class">
         {{ 'ds_sso_linkedin.login_with_linkedin'|trans }}
     </button>
     

   • Extend the LinkedIn profile data displayed post-login via Twig filters.

4. Webhook Integration

   • Use LinkedIn’s Member Social Actions to trigger actions (e.g., "Share to LinkedIn" buttons) after login.
   • Example:

     // In your post-auth listener
     $this->linkedinApi->shareContent(['comment' => 'Just logged in via SSO!']);