README

Simple security library for web applications.

Usage

Require kavalanche/security.
```
 composer require kavalanche/security
```
Create UserProvider. Refer to Custom UserProvider section.
Create instance of Kavalanche\Security\Service\RememberUserService.

Create instance of AuthenticationProvider and inject your UserProvider and RememberUserService into it.

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

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 or pass desired path to $_SESSION['redirect-path']. 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

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.

Remember user

From version v1.1.0 there is a possibility to add Remember me checkbox to login form. This option sets a cookie in user's browser and logs him in automatically.

Default configuration:

login-form-remember-me-field: "rememberme"
remember-me-cookie-lifetime: 2592000 # 30 days

Password reset

From version v2.0.0 there is a new functionality of resetting user password. You can use it as follows:

Add route to form with email field (configurable)
Check default email template and replace it with your own if needed (password-reset-mail-template in configuration file)
Add route to send email that includes code:

# You must create a service for sending e-mails that implements Kavalanche\Security\Interfaces\MailerInterface
$passwordResetService = new Kavalanche\Security\Service\PasswordResetService($passwordResetRepo, $userProvider, $mailer);

# Form data is handled internally if you use correctly configured fields (please refer to parameters.yaml file)
$passwordResetService->processResetRequest();

# You can redirect user according to the output of this method

Add new password handling route that includes code:

# Form data is handled internally if you use correctly configured fields (please refer to parameters.yaml file)
$passwordResetService->resetPassword();

# You can redirect user according to the output of this method

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

kavalanche / security

Maintainers

Details