Socialite Amazon Laravel Package

Getting Started

Minimal Steps

1. Install the Package

   composer require n30/socialiteproviders-amazon
   

   Ensure your project meets the PHP ≥ 7.2 requirement and has one of the supported Socialite packages (socialiteproviders/manager, joelbutcher/socialstream, or laravel/socialite).

2. Configure Amazon Provider Add the provider to your config/services.php:

   'amazon' => [
       'client_id'     => env('AMAZON_CLIENT_ID'),
       'client_secret' => env('AMAZON_CLIENT_SECRET'),
       'redirect'      => env('AMAZON_REDIRECT_URI'),
   ],
   

   Add these to your .env:

   AMAZON_CLIENT_ID=your_amazon_client_id
   AMAZON_CLIENT_SECRET=your_amazon_client_secret
   AMAZON_REDIRECT_URI=http://your-app.test/auth/amazon/callback
   

3. Register the Provider If using socialiteproviders/manager or socialstream, add this to AppServiceProvider:

   use N30\SocialiteProviders\Amazon\AmazonExtendSocialite;
   
   public function boot()
   {
       $socialite = $this->app->make(Socialite::class);
       $socialite->extend('amazon', function ($app) use ($socialite) {
           return AmazonExtendSocialite::socialite($app, $socialite);
       });
   }
   

4. Add Routes

   Route::get('/auth/amazon', [AuthController::class, 'redirectToAmazon'])->name('amazon.login');
   Route::get('/auth/amazon/callback', [AuthController::class, 'handleAmazonCallback']);
   

5. First Use Case Implement a controller method to handle the OAuth flow:

   public function redirectToAmazon()
   {
       return Socialite::driver('amazon')->redirect();
   }
   
   public function handleAmazonCallback()
   {
       try {
           $user = Socialite::driver('amazon')->user();
           // Map Amazon user to your app's user model (e.g., create/update).
       } catch (\Exception $e) {
           return redirect('/login')->with('error', 'Amazon login failed.');
       }
   }
   

Implementation Patterns

Workflows

1. User Authentication Flow

   • Redirect users to Amazon via Socialite::driver('amazon')->redirect().
   • Handle the callback with Socialite::driver('amazon')->user() to fetch user data (e.g., id, email, name).
   • Map Amazon’s user data to your local user model (e.g., using create() or firstOrCreate()).

2. Integration with SocialStream (JetStream)

   • If using socialstream, extend the provider in app/Providers/SocialStreamServiceProvider:

     SocialStream::extend('amazon', function () {
         return new \N30\SocialiteProviders\Amazon\AmazonExtendSocialite();
     });
     

   • Configure SocialStream’s config/socialstream.php to include Amazon:

     'providers' => [
         'amazon' => [
             'client_id'     => env('AMAZON_CLIENT_ID'),
             'client_secret' => env('AMAZON_CLIENT_SECRET'),
             'redirect'      => env('AMAZON_REDIRECT_URI'),
         ],
     ],
     

3. Standalone Socialite Usage

   • For custom apps without socialstream or manager, manually extend Socialite in AppServiceProvider (as shown in Getting Started).
   • Use the provider like any other Socialite driver:

     $amazonUser = Socialite::driver('amazon')->user();
     

4. User Data Mapping

   • Amazon’s user() method returns an array with keys like id, email, name, avatar, etc. Customize how you map this to your user model:

     $user = User::firstOrCreate(
         ['email' => $amazonUser->email],
         [
             'name' => $amazonUser->name,
             'amazon_id' => $amazonUser->id,
             'avatar' => $amazonUser->avatar ?? null,
         ]
     );
     

5. Error Handling

   • Wrap Socialite calls in try-catch blocks to handle:
     • Invalid credentials (Exception).
     • Missing required fields (e.g., email).
     • Redirect URI mismatches (configured in Amazon Developer Console).

Gotchas and Tips

Pitfalls

1. Amazon Developer Console Setup

   • Redirect URI Mismatch: Ensure the redirect_uri in your .env matches exactly (including http vs. https) what’s registered in the Amazon Developer Console.
   • Sandbox vs. Production: Use Amazon’s Login with Amazon sandbox for testing (https://www.amazon.com/ap/oa). Switch to production (https://www.amazon.com/ap/oa) only after approval.
   • Client Secret Exposure: Never hardcode client_secret in your codebase. Use .env and ensure it’s in your .gitignore.

2. Missing User Fields

   • Amazon’s OAuth response may omit email or name if not requested in the scope. Add these to your redirect() call:

     Socialite::driver('amazon')->scopes(['profile', 'email'])->redirect();
     

   • If email is missing, fall back to a generic placeholder (e.g., amazon_{user_id}@yourdomain.com).

3. SocialStream-Specific Issues

   • Provider Registration: If using socialstream, ensure the provider is listed in config/socialstream.php before booting the service provider.
   • Middleware Conflicts: SocialStream’s middleware may interfere with custom auth logic. Test routes like /login and /callback in isolation.

4. Deprecation Risks

   • The package is lightly maintained (1 star, last release 2023). Monitor for breaking changes if upgrading Laravel/Socialite.
   • For long-term projects, consider forking the repo or contributing to socialiteproviders/manager directly.

5. Debugging Tips

   • Enable Socialite Logging: Add this to AppServiceProvider to debug OAuth responses:

     Socialite::setClient(new \GuzzleHttp\Client([
         'debug' => true,
     ]));
     

   • Inspect Raw User Data: Dump the raw response from Socialite::driver('amazon')->user() to verify expected fields:

     dd($amazonUser->toArray());
     

Extension Points

1. Custom User Mapping

   • Override the default user mapping by extending AmazonExtendSocialite:

     class CustomAmazonExtendSocialite extends \N30\SocialiteProviders\Amazon\AmazonExtendSocialite
     {
         public function user()
         {
             $user = parent::user();
             // Custom logic (e.g., parse custom claims).
             return $user;
         }
     }
     

   • Register it in AppServiceProvider:

     $socialite->extend('amazon', function ($app) {
         return new CustomAmazonExtendSocialite($app['request']);
     });
     

2. Adding Scopes Dynamically

   • Extend the provider to support dynamic scopes (e.g., based on user role):

     Socialite::driver('amazon')->scopes(['profile', 'email', 'custom_scope'])->redirect();
     

3. Localization

   • Customize error messages or labels by publishing the package’s views (if available) or overriding them in your app’s resources/views/vendor/socialite-amazon.

4. Testing

   • Use Pest or PHPUnit to mock the Amazon provider:

     Socialite::shouldReceive('driver:amazon')->andReturnSelf()
         ->shouldReceive('user')->andReturn((new \N30\SocialiteProviders\Amazon\User)->setRaw([
             'id' => '123',
             'email' => 'user@example.com',
         ]));