Sso Sysuser Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require banovo/sso-sysuser-bundle
   

   Add to config/app.php under providers:

   Banovo\SsoSysUserBundle\SsoSysUserBundle::class,
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Banovo\SsoSysUserBundle\SsoSysUserBundle" --tag="config"
   

2. First Use Case: User Authentication via SSO

   • Configure your SSO provider (e.g., SAML, OAuth) in config/sso_sysuser.php.
   • Extend the base SysUser model (if needed) by creating a custom model:

     use Banovo\SsoSysUserBundle\Models\SysUser;
     
     class CustomSysUser extends SysUser { ... }
     

   • Register the model binding in AppServiceProvider:

     use Banovo\SsoSysUserBundle\Models\SysUser;
     
     public function boot()
     {
         SysUser::setModel(CustomSysUser::class);
     }
     

3. Trigger SSO Login Use the SsoSysUser facade to redirect users to the SSO provider:

   use Banovo\SsoSysUserBundle\Facades\SsoSysUser;
   
   Route::get('/login', function () {
       return SsoSysUser::login();
   });
   

Implementation Patterns

Workflow: SSO-Integrated User Flow

1. Login Redirect Use SsoSysUser::login() to redirect users to the SSO provider.

   Route::get('/sso-login', function () {
       return SsoSysUser::login(['return_to' => route('dashboard')]);
   });
   

2. Callback Handling Configure the SSO callback route (e.g., /sso/callback) to handle the response:

   Route::get('/sso/callback', [SsoSysUserController::class, 'callback']);
   

   The controller will automatically:

   • Validate the SSO response.
   • Create/update the user in the database.
   • Authenticate the user.

3. User Synchronization Override SsoSysUser::syncUser() to customize user data mapping:

   SsoSysUser::syncUser($ssoData, function ($user, $ssoData) {
       $user->name = $ssoData['name'];
       $user->email = $ssoData['email'];
       $user->sso_id = $ssoData['sub']; // Unique SSO identifier
       $user->save();
   });
   

4. Role/Group Assignment Use middleware or events to assign roles after SSO login:

   SsoSysUser::afterLogin(function ($user) {
       $user->assignRole('sso_user');
   });
   

Integration Tips

• Laravel Auth Integration The bundle works seamlessly with Laravel’s built-in auth. Use Auth::user() to access the SysUser model after SSO login.

• Custom User Models Extend SysUser to add custom fields or relationships:

  class CustomSysUser extends SysUser {
      public function departments() {
          return $this->belongsToMany(Department::class);
      }
  }
  

• Multi-SSO Support Configure multiple SSO providers in config/sso_sysuser.php and route users dynamically:

  SsoSysUser::login(['provider' => 'google']);
  

• Testing Mock SSO responses in tests:

  $this->mock(SsoSysUser::class)->shouldReceive('validateResponse')->andReturn($ssoData);
  

Gotchas and Tips

Pitfalls

1. Missing Config

   • Ensure config/sso_sysuser.php is properly set up with your SSO provider credentials (e.g., SAML metadata, OAuth client ID/secret).
   • Fix: Run php artisan vendor:publish --tag="config" and verify the config.

2. Callback Route Mismatch

   • The SSO provider’s callback URL must match the route defined in your app (e.g., /sso/callback).
   • Fix: Check the SSO provider’s documentation for the exact callback URL format.

3. User Sync Conflicts

   • If sso_id is not unique, users may be duplicated or overwritten.
   • Fix: Ensure sso_id is set in the syncUser callback and marked as unique in the database.

4. Session Issues

   • SSO logins may fail if sessions are not configured correctly (e.g., SESSION_DRIVER=file in .env).
   • Fix: Use a reliable session driver (e.g., redis or database).

5. Deprecated Methods

   • The package is outdated (last release: 2022). Some Laravel features (e.g., Facades, Auth) may require manual adjustments.
   • Fix: Check the source code for deprecated calls and update them.

Debugging Tips

• Enable Logging Add this to config/sso_sysuser.php:

  'debug' => env('SSO_DEBUG', false),
  

  Logs will appear in storage/logs/laravel.log.

• Validate SSO Response Dump the raw SSO response in the callback controller:

  public function callback() {
      $response = SsoSysUser::getResponse();
      \Log::info('SSO Response:', $response);
      // ...
  }
  

• Test with Postman Simulate SSO callbacks using Postman to verify the /sso/callback endpoint before integrating with the provider.

Extension Points

1. Custom Providers Extend the SsoProvider class to support unsupported SSO types (e.g., CAS):

   class CustomSsoProvider extends \Banovo\SsoSysUserBundle\Providers\SsoProvider {
       public function validateResponse($response) { ... }
   }
   

2. Event Listeners Listen for SSO events to trigger custom logic:

   SsoSysUser::listen('user.synced', function ($user) {
       // Send welcome email
   });
   

3. Middleware Protect routes with SSO-only access:

   Route::middleware(['sso'])->group(function () {
       // SSO-protected routes
   });
   

   Register the middleware in app/Http/Kernel.php:

   protected $routeMiddleware = [
       'sso' => \Banovo\SsoSysUserBundle\Middleware\SsoMiddleware::class,
   ];
   

4. Database Schema Customize the sys_users table by publishing and modifying the migration:

   php artisan vendor:publish --tag="migrations"