security/README.md

Kavalanche/Security

Simple security library for web applications.

Usage

1. Require kavalanche/security.

   composer require kavalanche/security
   

2. Create UserProvider. Refer to Custom UserProvider section.

3. Instantiate AuthenticationProvider and inject your UserProvider into it.

   $authenticationProvider = new Kavalanche\Security\Provider\AuthenticationProvider($userProvider);
   

4. Check if user is authenticated.

   try {
       $user = $authenticationProvider->authenticate();
   } catch (Kavalanche\Security\Exception\SecurityException $ex) {
       // if you want to allow unauthenticated users, then assign false or null to $user
   
       // if you require user to be authenticated do as follows
       if (!$e instanceof Kavalanche\Security\Exception\UserNotAuthenticatedException) {
           // put message in flash session and redirect to user form
           // or do whatever your use case demands
       }
   }
   

   You can specify redirect-path in security.yaml. Default is /.

   By default expected login form field names are email and password.

   You can change them by creating a config file named {app_root}/config/security.yaml and setting these variables:

   • login-form-identifier-field for identifier field
   • login-form-password-field for password field

5. Don't forget to put session_start() at the beginning of your file.

Custom UserProvider

If you want to user different UserProvider, you can create your. It must implement Kavalanche\Security\Interface\UserProviderInterface.

class UserProvider implements Kavalanche\Security\Interface\UserProviderInterface {

    public function loadUser($identifier) {
    
        // Fetch your User
        // Don't forget which type of identifier you defined in `security.yaml`
        
        // You can create your own User class (it must implement Kavalanche\Security\UserInterface)
        if ($user instanceof Kavalanche\Security\UserInterface) {
            return $user;
        }

        throw new Kavalanche\Security\Exception\SecurityException('Invalid username.');
    }

}

You can configure identifier type in your {app_root}/config/security.yaml file by setting identifier variable. Possible values are: email, username.

Other informations

• It's your obligation to ensure that the usernames are unique.
• You can use this library however you want. To secure the whole application or just some routes.
• You can add multiple roles to each user. Simply assign an array with roles or permissions with $user->setRoles() setter.

To do

• Implement some kind of request abstraction to encapsulate Requests (symfony/http-foundation?)
• Add helper to check permissions