Auth Gateway Laravel Package

Getting Started

First Steps

1. Installation

   composer require bibrokhim/auth-gateway
   

   Publish the config file (if available) and run migrations:

   php artisan vendor:publish --provider="Bibrokhim\AuthGateway\AuthGatewayServiceProvider"
   php artisan migrate
   

2. Basic Setup Register the service provider in config/app.php:

   'providers' => [
       Bibrokhim\AuthGateway\AuthGatewayServiceProvider::class,
   ],
   

3. First Use Case: OAuth2 Client Integration Configure a provider (e.g., Google) in config/auth-gateway.php:

   'providers' => [
       'google' => [
           'client_id' => env('GOOGLE_CLIENT_ID'),
           'client_secret' => env('GOOGLE_CLIENT_SECRET'),
           'redirect' => env('GOOGLE_REDIRECT_URI'),
       ],
   ],
   

   Add a route to initiate login:

   Route::get('/login/google', [AuthGatewayController::class, 'redirectToProvider'])->name('login.google');
   

Implementation Patterns

Workflow: OAuth2 Authentication

1. Redirect to Provider Use the facade or service to generate an auth URL:

   use Bibrokhim\AuthGateway\Facades\AuthGateway;
   
   $url = AuthGateway::provider('google')->getAuthorizationUrl();
   return redirect()->to($url);
   

2. Handle Callback Process the callback in a route:

   Route::get('/login/google/callback', [AuthGatewayController::class, 'handleProviderCallback']);
   

   public function handleProviderCallback()
   {
       $provider = AuthGateway::provider('google');
       $user = $provider->getUserFromCallback(request());
   
       // Attach or create user in your system
       auth()->login($user);
   
       return redirect()->intended('/dashboard');
   }
   

Workflow: JWT Token Management

If the package supports JWT, generate tokens post-authentication:

$token = AuthGateway::token()->createForUser($user);
return response()->json(['token' => $token]);

Integration Tips

• Middleware: Use auth:api or custom middleware to protect routes.
• User Mapping: Extend the User model to include provider-specific fields (e.g., google_id).
• Events: Listen for auth.gateway.loggedin or similar events to trigger post-auth actions.

Gotchas and Tips

Pitfalls

1. Missing Config Ensure auth-gateway.php is published and configured. Default values may not exist.

   php artisan vendor:publish --tag=auth-gateway-config
   

2. Callback Validation Always validate the state parameter in callbacks to prevent CSRF:

   $provider->validateCallbackState(request()->query('state'));
   

3. User Creation Logic The package may not handle user creation in your database. Implement a UserProvider or middleware to map external users to your system.

4. Token Expiry If using JWT, set expiry times in the config and handle token refresh logic manually.

Debugging

• Logs: Enable debug mode in auth-gateway.php to log OAuth2 requests/responses.
• Provider Errors: Check the error and error_description query params in failed callbacks.

Extension Points

1. Custom Providers Extend Bibrokhim\AuthGateway\Providers\Provider to support unsupported OAuth2 providers.

2. User Mapping Override the mapUser() method in your provider config to customize user data storage.

3. Token Storage If not using JWT, implement a custom token manager by binding the AuthGatewayTokenManager interface.

4. Scopes/Permissions Use the scopes() method in provider config to request additional permissions:

   'google' => [
       'scopes' => ['email', 'profile'],
   ],