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

KnpUGuardBundle

by knpuniversity

Simple and lovely Symfony authentication

KnpGuardPlugin

Add simple and beautiful authentication to your Symfony project.

Build Status

This is a library is usable, but is alpha, and backwards compatibility
is not guaranteed yet. 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).

Installation

This bundle requires Symfony 2.6 or higher.

First, wave your composer wand to install things:

composer require knpuniversity/guard-bundle:dev-master

Next, plug the bundle into your app/AppKernel.php file:

public function registerBundles()
{
    $bundles = array(
        // -> add just this ONE line
        new KnpU\GuardBundle\KnpUGuardBundle(),
    );

    // ...
}

Now, start using it!

Usage

For an example application, see knpuniversity/symfony-guard-demo.

Whether you want to authenticate via a form login, by reading an API token
or both, you'll follow the same 3-step process:

1) Create an Authenticator class

Each time you want to authenticate a user, you'll start by creating a class
that extends KnpU\GuardBundle\Guard\AbstractGuardAuthenticator
(or implements KnpU\GuardBundle\Guard\GuardAuthenticatorInterface).
For examples, see TokenAuthenticator
and FormLoginAuthenticator.

This interface has a method for every part of the authentication process,
from fetching the credentials (e.g. username/password or API token) from
the request to handling success and error situations.

2) Create a User Provider

A User Provider is basically a class that knows how to load your "users".
It's passed to the getUser() method of your authenticator. Whether you
are loading users from a database or elsewhere, I recommend creating your
own user provider class.

For example, see UserProvider
from the demo project.

3) Register the authenticator (and user provider) as a service

The authenticators are plain old services, so this is easy. For example,

# app/config/services.yml
services:
    app.form_login_authenticator:
        class: AppBundle\Security\FormLoginAuthenticator
        arguments: ['@security.password_encoder', '@router']

    app.token_authenticator:
        class: AppBundle\Security\TokenAuthenticator
        arguments: []

   app.user_provider:
        class: AppBundle\Security\UserProvider
        arguments: ['@doctrine.orm.entity_manager']

4) Configure security.yml

For a full example security.yml, see security.yml
in the demo app.

There are basically only two critical areas to configure: providers
and firewalls:

security:
    encoders:
        AppBundle\Entity\User: bcrypt

    providers:
        # the service id to your provider (you can also use other providers,
        # like the "entity" provider)
        main_provider:
            id: app.user_provider

    firewalls:
        secured_area:
            # this firewall applies to all URLs
            pattern: ^/
            anonymous: true

            knpu_guard:
                authenticators:
                    - app.form_login_authenticator
                    - app.token_authenticator
                # provider: main_provider

                # since you have 2 authenticators, you'll choose which "start"
                # method is called when the user should be asked to login
                # entry_point: app.token_authenticator
                entry_point: app.form_login_authenticator

            # any other keys, like remember_me, switch_user, logout, etc

    # ...

First, you'll register your user provider under the providers key. Next,
add a knpu_guard key under your firewall with an authenticators key.
Here, put the service ids of all your authenticators: you may have just one.

That's it! Your authenticators should be called on every request, and they
can authenticate to their heart's desire.

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.
  • Merge pull request #2 from stof/patch-1
    By weaverryan, 1 year ago
  • Merge pull request #1 from royopa/patch-1
    By weaverryan, 1 year ago
  • Improve the wording of the readme
    By stof, 1 year ago
  • remove trailling spaces
    By royopa, 1 year ago
  • fixing old namespaces
    By weaverryan, 1 year ago
  • inline docs
    By weaverryan, 1 year ago
  • fixing package name
    By weaverryan, 1 year ago
  • removing the old library stuff - this is just the bundle
    By weaverryan, 1 year ago
  • updating branch in README
    By weaverryan, 1 year ago
  • using dev-master for now
    By weaverryan, 1 year ago
  • updating install
    By weaverryan, 1 year ago
  • Adding an extra: a class where you can control authentication exception messages!
    By weaverryan, 1 year ago
  • Adding missing guard.xml services
    By weaverryan, 1 year ago
  • updating README for pre-release install
    By weaverryan, 1 year ago
  • removing minimum stability flag
    By weaverryan, 1 year ago
  • extra line
    By weaverryan, 1 year ago
  • small tweaks to composer.json
    By weaverryan, 1 year ago
  • Removing target-dir
    By weaverryan, 1 year ago
  • Making requirements clear
    By weaverryan, 1 year ago
  • Chaning Travis - we only support 2.6 and higher
    By weaverryan, 1 year ago
  • adding a very quick README
    By weaverryan, 1 year ago
  • changing case!
    By weaverryan, 1 year ago
  • Adding build status
    By weaverryan, 1 year ago
  • forgot an important piece!
    By weaverryan, 1 year ago
  • Adding initial travis (based off of FOSRestBundle)
    By weaverryan, 1 year ago
  • adding a readme
    By weaverryan, 1 year ago
  • Configuring PHPUnit and getting the tests to pass!
    By weaverryan, 1 year ago
  • Adding composer and license
    By weaverryan, 1 year ago
  • moving tests and updating namespaces
    By weaverryan, 1 year ago
  • Updating a lot of namespaces
    By weaverryan, 1 year ago