Singpass Login Laravel Package

## Getting Started
This package, **SingPass-Login**, enables seamless integration with Singapore's SingPass and Corppass authentication systems via FAPI 2.0. To get started:

1. **Installation**: Require the package via Composer:
   ```bash
   composer require accredifysg/singpass-login

2. Configuration: Publish the config file:

   php artisan vendor:publish --provider="Accredify\SingPassLogin\SingPassServiceProvider"
   

   Update .env with your FAPI credentials (client ID, secret, and callback URL).
3. First Use Case: Redirect users to SingPass for authentication:

   use Accredify\SingPassLogin\Facades\SingPass;
   
   $authUrl = SingPass::getAuthorizationUrl();
   return redirect()->away($authUrl);
   

   Handle the callback via the provided SingPassCallbackController or manually verify tokens.

Implementation Patterns

Authentication Workflow

1. Initiate Login:

   $authUrl = SingPass::getAuthorizationUrl([
       'scope' => 'openid profile email',
       'state' => 'unique_random_string', // CSRF protection
   ]);
   

   • Use scope to request user data (e.g., openid, profile, email).
   • Store state in the session for validation.

2. Callback Handling:

   • After user authorization, SingPass redirects to your callback URL with a code.
   • Exchange the code for a token:

     $token = SingPass::getAccessToken($authorizationCode);
     $userInfo = SingPass::getUserInfo($token);
     

   • Validate the state parameter to prevent CSRF attacks.

3. Token Management:

   • Store tokens securely (e.g., in the session or database).
   • Refresh tokens when expired using SingPass::refreshToken($refreshToken).

Corppass Support

• Corppass (for corporate users) is now supported via FAPI 2.0. Use the same methods as SingPass but ensure your FAPI credentials are configured for Corppass endpoints.

Session Integration

• Bind authenticated users to Laravel sessions:

  Auth::loginUsingId($userInfo['sub']); // Assuming 'sub' is the user ID
  

Gotchas and Tips

Breaking Changes in v3.0.0

1. Strict Types:

   • The package now declares strict types (declare(strict_types=1)). Ensure your project and dependencies are compatible.
   • Update PHP version to 8.0+ if not already using it.

2. FAPI 2.0 Mandatory:

   • Older FAPI 1.0 endpoints are deprecated. Migrate to FAPI 2.0 endpoints (e.g., /auth/realms/singpass/protocol/openid-connect/auth).
   • Update your .env to reflect the new FAPI 2.0 base URL:

     SINGPASS_FAPI_BASE_URL=https://fapi2.singpass.gov.sg
     

3. Token Handling:

   • The web-token/jwt-framework dependency was updated to v4.1.3. If you rely on custom JWT logic, test thoroughly for compatibility.

Debugging Tips

1. Token Validation Errors:

   • Use SingPass::validateToken($token) to debug token issues.
   • Enable verbose logging in the config:

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

2. Corppass-Specific Issues:

   • Corppass may require additional scopes or claims. Refer to SingPass Developer Portal for details.
   • Test Corppass flows in a sandbox environment first.

3. CSRF Protection:

   • Always validate the state parameter in the callback to prevent CSRF attacks. Example:

     if (!hash_equals(session('singpass_state'), $request->state)) {
         abort(403, 'Invalid CSRF state');
     }
     

Extension Points

1. Custom User Mapping:

   • Override the default user mapping logic by binding to the singpass.login event:

     event(new \Accredify\SingPassLogin\Events\LoginEvent($userInfo));
     

   • Handle the event to map SingPass data to your user model.

2. Token Storage:

   • Extend the SingPassTokenManager to implement custom storage (e.g., Redis):

     SingPass::setTokenManager(new CustomTokenManager());
     

3. Middleware:

   • Protect routes with SingPass authentication:

     Route::middleware(['auth.singpass'])->group(function () {
         // Protected routes
     });
     

   • Implement the middleware to verify tokens from the session.

---
**Note**: This assessment assumes the package is for **Laravel** (as per your request). Adjustments may be needed if the package has broader PHP support. The focus is on **FAPI 2.0/Corppass** changes and strict typing in v3.0.0.