Iversauth Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require kankanamge/iversauth
   

2. Register Service Provider Add \Kankanamge\IversAuth\AuthServiceProvider::class to config/app.php under 'providers'.

3. Override Auth Middleware Replace 'auth' => \Illuminate\Auth\Middleware\Authenticate::class with:

   'auth' => \Kankanamge\IversAuth\AuthenticateMiddleware::class,
   

   in app/Http/Kernel.php.

4. Publish Config

   php artisan vendor:publish --provider="Kankanamge\IversAuth\AuthServiceProvider"
   

   Configure config/ivers_auth.php with your Ivers Auth app credentials (client ID, secret, callback URL).

5. First Use Case Redirect users to Ivers Auth for login:

   Route::get('/login', function () {
       return \Kankanamge\IversAuth\Facades\IversAuth::redirectToIversAuth();
   });
   

   The package handles the OAuth flow and redirects back to your app after authentication.

Implementation Patterns

Workflows

1. OAuth Flow Integration

   • Use \Kankanamge\IversAuth\Facades\IversAuth for all auth operations.
   • Example: Redirect to Ivers Auth:

     return IversAuth::redirectToIversAuth();
     

   • Handle callback (ensure /ivers-auth/callback is routed to the package’s controller).

2. User Data Fetching After successful auth, fetch user data:

   $user = IversAuth::getUser();
   // Manually create/update Laravel user if needed
   

3. Protected Routes Use the auth middleware (now AuthenticateMiddleware) to guard routes:

   Route::get('/dashboard', function () {
       return "Welcome!";
   })->middleware('auth');
   

4. Session Management The package manages sessions via Ivers Auth’s OAuth tokens. Avoid manual session handling unless extending functionality.

Integration Tips

• Laravel Users Table: The package does not auto-create users. Manually sync Ivers Auth data to your users table (e.g., via Auth::loginUsingId()).
• Custom User Model: Extend the package’s AuthServiceProvider to bind a custom user resolver:

  public function boot()
  {
      $this->app['auth']->viaRequest('ivers', function ($request) {
          return \App\Models\CustomUser::where('ivers_id', $request->user()->id)->first();
      });
  }
  

• Logout: Redirect to Ivers Auth’s logout endpoint:

  Route::get('/logout', function () {
      return IversAuth::logout();
  });
  

Gotchas and Tips

Pitfalls

1. No /login Route The README warns against routing to /login. Instead, use a custom route (e.g., /auth/ivers) and call redirectToIversAuth().

2. Missing User Sync The package only handles OAuth. You must manually link Ivers Auth users to your Laravel users table. Example:

   $iversUser = IversAuth::getUser();
   $localUser = User::firstOrCreate(
       ['email' => $iversUser->email],
       ['name' => $iversUser->name, 'ivers_id' => $iversUser->id]
   );
   Auth::login($localUser);
   

3. Callback URL Mismatch Ensure the callback_url in config/ivers_auth.php matches the route handling the OAuth callback (default: /ivers-auth/callback). Mismatches cause silent failures.

4. Token Expiry Ivers Auth tokens expire. The package does not auto-refresh tokens. Implement a refreshToken method or use Laravel’s Auth::onceUsingId() for temporary sessions.

Debugging

• OAuth Errors: Check Laravel logs for GuzzleHttp exceptions (common for invalid credentials or callback URLs).
• Missing Config: If auth fails, verify config/ivers_auth.php has valid client_id, client_secret, and redirect_url.
• Middleware Bypass: Ensure AuthenticateMiddleware is properly registered in Kernel.php. Test with:

  Route::get('/test-auth', function () {
      dd(auth()->check()); // Should return true if authenticated
  })->middleware('auth');
  

Extension Points

1. Custom User Provider Override the default user provider in AuthServiceProvider:

   public function boot()
   {
       $this->app['auth']->provider('ivers', function ($app) {
           return new \Kankanamge\IversAuth\IversUserProvider($app['config']['ivers_auth']);
       });
   }
   

2. Post-Auth Hooks Add logic after successful auth in a service provider’s boot():

   IversAuth::afterAuth(function ($user) {
       event(new UserLoggedIn($user));
   });
   

3. Token Storage Extend the package to store tokens in the database for persistence:

   IversAuth::setTokenStorage(function ($token) {
       Token::updateOrCreate(
           ['user_id' => auth()->id()],
           ['access_token' => $token->accessToken]
       );
   });
   

4. Fallback Auth Combine with Laravel’s default auth for hybrid flows:

   if (auth()->check()) {
       // User is logged in via Ivers Auth or local auth
   }