Developed with love by KnpLabs Hire us for your project!
0

KnpUGuardBundle

by knpuniversity

Simple and lovely Symfony authentication

KnpUGuardBundle

Add simple and beautiful authentication to your Symfony project.

Build Status

This library is deprecated since Symfony 2.8 and won't work with Symfony 3.

The original purpose was to get feedback and use-cases from people so that we can merge this feature into Symfony itself
(see symfony/symfony#14673).

Now it's good (see news from Symfony).

Upgrade to Symfony 3

On Symfony 2.8, use the official Guard component.

Step 1 - Remove the library from your composer.json

Be sure to be on Symfony 2.8, open composer.json file and remove the library:

Before:
json
{
"require": {
"php": ">=5.5",
"symfony/symfony": "~2.8",
"...": "...",
"knpuniversity/guard-bundle": "~0.1@dev"
},
}

Now:
json
{
"require": {
"php": ">=5.5",
"symfony/symfony": "~2.8",
"...": "..."
},
}

Step 2 - Remove it from your AppKernel

If you're using the Symfony framework, remove the KnpUGuardBundle from AppKernel.php.

Step 3 - Modify firewall(s)

Open and modify security.yml file, replace in your firewall(s) key(s) knpu_guard by guard:

Before:
```yaml

app/config/security.yml

security:
# ...

firewalls:
    # ...

    main:
        anonymous: ~
        logout: ~

        knpu_guard:
            authenticators:
                - app.form_login_authenticator

        # maybe other things, like form_login, remember_me, etc
        # ...

Now:
```yaml
# app/config/security.yml
security:
    # ...

    firewalls:
        # ...

        main:
            anonymous: ~
            logout: ~

            guard:
                authenticators:
                    - app.form_login_authenticator

            # maybe other things, like form_login, remember_me, etc
            # ...

Step 4 - Update Authenticator(s)

Update uses in Authenticator(s) class(es).

Warning: checkCredentials() NOW must return true in order for authentication to be successful.
In KnpUGuard, if you did NOT throw an AuthenticationException, it would pass.

Before:
```php
use KnpU\Guard\Authenticator\AbstractFormLoginAuthenticator;
use KnpU\Guard...;
// ...

class FormLoginAuthenticator extends AbstractFormLoginAuthenticator
{
// ...

public function checkCredentials($credentials, UserInterface $user)
{
    // ...

    if ($password !== 'correctPassword') {
        throw new AuthenticationException();
    }

    // do nothing, allow authentication to pass
}

// ...

}
```

Now:
```php
use Symfony\Component\Security\Guard\Authenticator\AbstractFormLoginAuthenticator;
use Symfony\Component\Security\Guard...;
// ...

class FormLoginAuthenticator extends AbstractFormLoginAuthenticator
{
// ...

public function checkCredentials($credentials, UserInterface $user)
{
    // ...

    if ($password !== 'correctPassword') {
        // returning anything NOT true will cause an authentication failure
        return;
        // or, you can still throw an AuthenticationException if you want to
        // throw new AuthenticationException();
    }

    // return true to make authentication successful
    return true;
}

// ...

}
```

Step 5 - Yes we can test it

Upgrade to Symfony 3 (won't be worst than from Symfony 1 to Symfony 2) ;-)

Documentation

Find a full tutorial here: https://knpuniversity.com/screencast/guard

Basic Usage

Check out the Tutorial for real documentation.
But here's the basic idea.

Guard works by creating a single class - an authenticator - that handles everything
about how you want to authenticate your users. And authenticator implements
KnpU\Guard\GuardAuthenticatorInterface)

Here are some real-world examples from the tutorial:

Goal Code Tutorial
Authenticate by reading an X-TOKEN header ApiTokenAuthenticator.php How to Authenticate via an API Token
Form login authentication FormLoginAuthenticator.php How to Create a Login Form
Social Login (Facebook) FacebookAuthenticator.php Social Login with Facebook

Contributing

Find a bug or a use-case that this doesn't support? Open an Issue
so we can make things better.

License

This library is under the MIT license. See the complete license in the LICENSE file.

Copyright (c) KnpUniversity <http://knpuniversity.com/>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished
to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.