Apiauthbundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require coresite/apiauthbundle
   

2. Register Bundle Add to app/AppKernel.php:

   new CoreSite\APIAuthBundle\CoreSiteAPIAuthBundle(),
   

3. Basic Security Configuration Configure app/config/security.yml:

   firewalls:
       api:
           pattern: ^/api
           stateless: true
           simple_preauth:
               authenticator: cs_apiauth_authenticator
               provider: cs_apiauth_user_provider
   

4. First Use Case

   • Create a token endpoint (/api_login_check) to authenticate users and return a token.
   • Use the token in subsequent API requests via the Authorization: Bearer <token> header.

Implementation Patterns

Token-Based Authentication Workflow

1. Login Flow

   • POST to /api_login_check with _username and _password.
   • The bundle handles authentication via cs_apiauth_login and returns a token.

2. Protected API Requests

   • Subsequent requests to /api/* must include the token in the Authorization header.
   • The cs_apiauth_authenticator validates the token and loads the user.

3. User Provider Integration

   • Extend CoreSite\APIAuthBundle\Security\User\APIUserProvider to fetch users from your data source (e.g., database, LDAP).
   • Example:

     services:
         cs_apiauth_user_provider:
             class: AppBundle\Security\User\CustomAPIUserProvider
             arguments: [@doctrine.orm.entity_manager]
     

4. Token Storage

   • Tokens are stored in the session by default. For stateless APIs, override the token storage logic in your authenticator.

Common Integration Points

• Custom Authenticators: Extend CoreSite\APIAuthBundle\Security\Authenticator\APIAuthenticator for custom token validation logic.
• Success/Failure Handlers: Override cs_apiauth_user_handler_authentication_success to customize token generation or response formatting.
• Token Expiry: Configure token TTL in security.yml or via a custom authenticator.

Gotchas and Tips

Pitfalls

1. Stateless Mode Conflicts

   • The bundle assumes stateless mode (stateless: true). If misconfigured, token validation may fail.
   • Ensure api firewall is stateless and api_login is anonymous.

2. Token Storage Assumptions

   • Default implementation relies on session storage. For stateless APIs, override token storage in the authenticator:

     public function getToken($credentials)
     {
         // Custom logic to fetch token from a database or cache
     }
     

3. User Provider Mismatch

   • The cs_apiauth_user_provider must return an object implementing CoreSite\APIAuthBundle\Security\User\APIUserInterface.
   • Debug provider issues with:

     bin/console debug:security
     

4. CSRF Protection

   • The bundle does not include CSRF protection for token endpoints. Add it manually if needed:

     api_login:
         pattern: ^/api/login
         stateless: true
         anonymous: ~
         csrf_protection: true
     

Debugging Tips

• Token Validation Errors

  • Check logs for Authentication failure messages. Common causes:
    • Invalid token format (must be Bearer <token>).
    • Expired token (implement TTL logic in authenticator).
  • Enable debug mode to see detailed errors:

    # app/config/config.yml
    framework:
        router:
            debug: "%kernel.debug%"
    

• Configuration Overrides

  • Override bundle defaults via config.yml:

    cs_apiauth:
        token_ttl: 3600       # Token time-to-live in seconds
        token_storage: session # or 'database'/'cache'
    

Extension Points

1. Custom Token Format Override CoreSite\APIAuthBundle\Security\Token\APIAuthToken to support JWT or other formats.

2. Multi-Tenant Support Extend the user provider to include tenant IDs in tokens:

   public function loadUserByToken($token)
   {
       $tenantId = $this->extractTenantIdFromToken($token);
       // Load user with tenant context
   }
   

3. Rate Limiting Integrate with nelmio/cors-bundle or lexik/jwt-authentication-bundle for rate limiting on token endpoints.