README

NOTE: This project is still on work progress!

aldee-apiAuth-bundle

A Symfony2 Web Service Helper and Authentication Handler Bundle

I. Installation

Install the bundle via composer

composer require aldee07/api-auth-bundle

Register the bundle

// app/AppKernel.php
new JMS\SerializerBundle\JMSSerializerBundle(),   
new Aldee\ApiAuthBundle\ApiAuthBundle(),

II. Configuration

To make things easier to use, I defined configurable settings as parameters. You can of course override the default configuration defined for this bundle. Here are the list of configurable parameter entries.

# app/config/config.yml -- but its up to you where as long as it is loaded in config and is under parameters context
parameters:
    aldeeapiauthbundle_config.user_provider: AppBundle\Security\UserProvider
    aldeeapiauthbundle_config.identifier: "apikey"
    aldeeapiauthbundle_config.asHeader: true

Parameters definition

aldeeapiauthbundle_config.user_provider - Required. The UserProvider class to load. You must create this UserProvider class on your own. This class is expected to implement Aldee\ApiAuthBundle\Security\ApiUserProviderInterface.
aldeeapiauthbundle_config.identifier - Optional. @see Aldee\ApiAuthBundle\Security\KeyAuthenticator::__construct( )
aldeeapiauthbundle_config.asHeader - Optional. @see Aldee\ApiAuthBundle\Security\KeyAuthenticator::__construct( )
aldeeapiauthbundle_config.allowCrossDomain - Optional. Whether or not allow cross domain. Default true

Security configuration

security:
    providers:
        aldeeapiauthbundle_user_provider:
            id: aldeeapiauthbundle_user_provider        
        #...

    firewalls:
        api:
            pattern: ^/api
            stateless: true # must be true
            simple_preauth:
                authenticator: aldeeapiauthbundle_key_authenticator
            provider: aldeeapiauthbundle_user_provider
        #...

UserProvider Configuration

Now that everything are all set, the last thing to do to make it work in accordance to your need is to create your custom UserProvider class by creating a UserProvider (see "Parameters definition") that implements a wrapper interface Aldee\ApiAuthBundle\Security\ApiUserProviderInterface.

namespace AppBundle\Security;

use AppBundle\Entity\MyUserEntity;
use Symfony\Component\Security\Core\User\UserInterface;
use Symfony\Component\Security\Core\Exception\UnsupportedUserException;
use Aldee\ApiAuthBundle\Security\ApiUserProviderInterface;

class UserProvider implements ApiUserProviderInterface
{
    /**
     * @inheritdoc
     */
    public function getUsernameForApiKey($apiKey)
    {
        // your db fetching here and return username
        //...
    }
    
    /**
     * @inheritdoc
     */
    public function loadUserByUsername($username) 
    {
        $myUser = new MyUserEntity();
        
        // your db fetching here that hydrates to $myUser
        //...
        
        return $myUser;        
    }
    
    /**
     * @inheritdoc
     */
    public function refreshUser(UserInterface $user) 
    {
        throw new UnsupportedUserException();
    }
    
    /**
     * @inheritdoc
     */
    public function supportsClass($class)
    {
        return 'Symfony\Component\Security\Core\User\User' === $class;
    }
}

III. Usage

class DefaultController extends Controller
{    
    /**
     * @Route("/api/example.json", name="example")
     */
    public function indexAction()
    {
        $response = $this->get('aldeeapiauthbundle_response');
        
        // The data result to be sent back to the client
        $data = [1, 2, 3, 'hello', 'world', 'foo' => ['bar', 'baz']];
        
        // Your custom api result status code
        $statusCode = 1501;
        
        // Http status code to be sent in the header
        $httpCode = 200; 
        
        // The response format to use (xml|json|yml)
        $format = 'json';
        
        // Your custom api result message
        $message = 'Success!';

        $response->prepare($data, $statusCode, $message);
        
        return $response->dispatch($httpCode, $format);
    }
}

aldee07 / api-auth-bundle

Maintainers

Details