Singpass Login Laravel Package

Technical Evaluation

Architecture Fit

• Modular FAPI 2.0 Core: The package’s separation of shared FAPI 2.0 choreography (DPoP, PAR, PKCE, JWT) from provider-specific logic (SingPass/MyInfo/CorpPass) aligns well with Laravel’s modularity. This reduces code duplication and simplifies future provider additions.
• Event-Driven Design: Leverages Laravel’s event system for post-login/post-data-retrieval actions, enabling clean decoupling of authentication logic from business logic.
• Configuration-Driven: Provider-specific settings (scopes, routes, credentials) are externalized, making it easy to toggle features or swap providers without refactoring.

Integration Feasibility

• Laravel Native: Built for Laravel (uses Laravel’s HTTP, Auth, and Event systems), requiring minimal boilerplate. Composer integration and vendor:publish simplify setup.
• FAPI 2.0 Compliance: Supports Pushed Authorization Requests (PAR), DPoP, PKCE, and JWT assertions, meeting SingPass/MyInfo/CorpPass requirements without manual OAuth2/OIDC implementation.
• JWKS Management: Automates key rotation and signing for DPoP proofs, reducing cryptographic complexity.

Technical Risk

• Key Management: Requires secure handling of NDI_PRIVATE_JWKS (private key for JWT assertions). Misconfiguration could lead to token forgery or revocation issues.
• Token Validation: Relies on unverified JWT parsing for scope checks (e.g., MyInfo). Malformed tokens may cause silent failures or incorrect scope assumptions.
• State Management: Uses Laravel’s session for CSRF protection (state parameter). Session storage must be persistent and secure (e.g., Redis for distributed setups).
• Deprecation Risk: SingPassUser::getNric() is deprecated; migration to sub_attributes.identity_number may require refactoring existing listeners.
• Provider-Specific Quirks: CorpPass’s hierarchical identity model (entity + actor) adds complexity. Misconfigured scopes (e.g., missing user.identity) may break actor resolution.

Key Questions

1. Key Storage: How will NDI_PRIVATE_JWKS be stored securely (e.g., AWS KMS, HashiCorp Vault)?
2. Session Backend: Is Laravel’s default session driver (file) suitable, or will Redis/Memcached be used for distributed state?
3. Error Handling: How will token validation failures (e.g., malformed JWTs) be surfaced to end-users (e.g., redirect to error page vs. silent fallback)?
4. Scope Validation: Are all requested scopes (e.g., MyInfo’s nationality, dob) whitelisted in config/myinfo.php?
5. CorpPass Entity Resolution: How will the application map CorpPass’s entity (company) and actor (user) to internal models?
6. Logging: With NDI_LOGS_ENABLED=false by default, how will debugging be handled in production?
7. Rate Limiting: Are there API rate limits for SingPass/MyInfo/CorpPass endpoints that require throttling middleware?
8. Testing: How will the integration be tested (e.g., mocking SingPass’s PAR endpoint, validating DPoP proofs)?

Integration Approach

Stack Fit

• Laravel Ecosystem: Seamless integration with Laravel’s:
  • Authentication: Uses Laravel’s Auth facade for session-based login.
  • Events: Leverages Laravel’s event system for post-login actions.
  • Routing: Registers routes under web middleware (CSRF protection).
  • Configuration: Uses Laravel’s config system with .env overrides.
• PHP Version: Requires PHP 8.1+ (for named arguments, attributes). Ensure compatibility with your PHP version.
• Dependencies: Minimal external dependencies (only league/oauth2-server for FAPI 2.0). No heavy frameworks like Symfony.

Migration Path

1. Prerequisites:
   • Laravel 9+ (PHP 8.1+).
   • Composer access to install the package.
   • Secure storage for NDI_PRIVATE_JWKS (e.g., encrypted .env or secrets manager).
2. Installation:

   composer require accredifysg/singpass-login
   php artisan vendor:publish --provider="Accredifysg\SingPassLogin\SingPassLoginServiceProvider" --tag="config"
   

3. Configuration:
   • Populate .env with SingPass/MyInfo/CorpPass credentials (e.g., SINGPASS_CLIENT_ID, MYINFO_REDIRECT_URI).
   • Configure JWKS and DPoP settings in config/ndi.php.
   • Define scopes and routes in provider-specific configs.
4. Customization:
   • Override default listeners (e.g., SingPassSuccessfulLoginEvent) to map SingPass/MyInfo/CorpPass data to your user model.
   • Extend or replace controllers if default routes/behavior are insufficient.
5. Testing:
   • Test PAR flow with SingPass’s staging environment first.
   • Validate DPoP proofs and token exchanges using tools like OIDC Debugger.
   • Mock provider responses in unit tests (e.g., using Http::fake()).

Compatibility

• Laravel Versions: Tested with Laravel 9/10. May require adjustments for older versions (e.g., PHP 8.0).
• Provider Updates: SingPass/MyInfo/CorpPass may change their FAPI 2.0 endpoints or scopes. Monitor their developer docs for breaking changes.
• Caching: The package caches OpenID discovery documents. Ensure your cache driver (e.g., Redis) is configured.
• HTTPS: All routes require HTTPS (SingPass/MyInfo/CorpPass enforce this). Use Laravel’s trustedproxy middleware if behind a load balancer.

Sequencing

1. Phase 1: Core Integration
   • Implement SingPass Login with minimal scopes (openid, name, email).
   • Test PAR flow and DPoP validation.
2. Phase 2: MyInfo/CorpPass
   • Add MyInfo for user data retrieval (e.g., nationality, dob).
   • Implement CorpPass for entity-actor resolution (if needed).
3. Phase 3: Advanced Features
   • Customize listeners for complex user mapping (e.g., CorpPass’s hierarchical identity).
   • Add rate limiting or retry logic for token exchanges.
4. Phase 4: Monitoring
   • Enable NDI_LOGS_ENABLED=true and integrate logs with your monitoring system (e.g., Sentry, Datadog).

Operational Impact

Maintenance

• Key Rotation: NDI_PRIVATE_JWKS must be rotated periodically (follow SingPass/MyInfo/CorpPass guidelines). Automate this with a cron job or secrets manager.
• Dependency Updates: Monitor league/oauth2-server for FAPI 2.0 updates. Test package upgrades in staging.
• Configuration Drift: Provider configs (e.g., SINGPASS_DISCOVERY_ENDPOINT) may change. Use feature flags or environment-specific configs to manage drift.
• Deprecations: Stay updated on package deprecations (e.g., SingPassUser::getNric()). Plan migrations proactively.

Support

• Debugging: Enable NDI_LOGS_ENABLED=true for troubleshooting. Logs include:
  • PAR/DPoP token payloads.
  • Token exchange responses.
  • UserInfo data retrieval.
• Provider Outages: SingPass/MyInfo/CorpPass may experience downtime. Implement:
  • Retry logic for token exchanges (exponential backoff).
  • Fallback UIs for failed logins (e.g., "SingPass service unavailable").
• Compliance: Ensure logging adheres to SingPass/MyInfo’s data protection policies (e.g., avoid logging PII like NRIC).

Scaling

• Session Storage: Use Redis/Memcached for distributed session storage if scaling horizontally.
• Rate Limiting: Implement Laravel’s throttle middleware for /ndi/jwks or auth endpoints if hit by abuse.
• Caching: Cache OpenID discovery documents and JWKS to reduce latency:

  // config/ndi.php
  'cache_discovery' => true,
  'cache_jwks' => true,
  

• Asynchronous Processing: For CorpPass/MyInfo data retrieval, consider queueing MyInfoDataRetrievedEvent/CorpPassDataRetrievedEvent to avoid blocking the auth flow.

Failure Modes