README.md

OAuth2 Server Bundle

OAuth2 Server Bundle for Symfony 2, built on the oauth2-server-php library.

Getting Started

See the Complete Documentation for information regarding the OAuth2.0 protocol and the PHP library used by this bundle to implement it.

For documentation specific to this bundle, continue reading below.

Bundle Overview

The following grant types are supported out the box:

• Client Credentials
• Authorization Code
• Refresh Token
• User Credentials (see below)

You can make token requests to the /token path via POST.

You can restrict the grant types available per client in the database, use a Compiler Pass or in your own TokenController you could do something like:

public function tokenAction()
{
    $server = $this->get('oauth2.server');

    // Override default grant types to authorization code only
    $server->addGrantType($this->get('oauth2.grant_type.authorization_code'));

    return $server->handleTokenRequest($this->get('oauth2.request'), $this->get('oauth2.response'));
}

Installation

Step 1: Add package to Composer

Use composer to add the requirement and download it by running the command:

$ php composer.phar require bshaffer/oauth2-server-bundle

Composer will update your composer.json and install the bundle to your project's vendor/bshaffer directory.

Step 2: Enable the bundle

Enable the bundle in the kernel:

<?php
// app/AppKernel.php

public function registerBundles()
{
    $bundles = array(
        // ...
        new OAuth2\ServerBundle\OAuth2ServerBundle(),
    );
}

Step 3: Install database

You'll need to update your schema to setup the Entities provided by this module.

$ php app/console doctrine:schema:update --force

Step 4: Add routes

You'll need to add the following to your routing.yml

# app/config/routing.yml

oauth2_server:
    resource: "@OAuth2ServerBundle/Controller/"
    type:     annotation
    prefix:   /

Step 5: Create a scope

You'll need to setup a scope before you can create a client, use this command. The description you give here will appear on the Authorization page.

$ php app/console OAuth2:CreateScope scope (description)

Step 6: Create a client

Use this console command to create a new client:

$ php app/console OAuth2:CreateClient client_id redirect_uri (grant_types) (scope)

Optional Configuration

You can override any of the built-in components in your own bundle by adding new parameters in your config.yml:

# app/config/config.yml

parameters:
    oauth2.storage.client_credentials.class: Amce\OAuth2ServerBundle\Storage\ClientCredentials

Where Amce\OAuth2ServerBundle\Storage\ClientCredentials is your own implementation of the ClientCredentials interface.

If you provide your own storage managers then you'll be able to hook everything up to your own custom Entities.

User Credentials (Resource Owner Password)

To make it easy to plug-in your own User Provider we've conformed to the UserInterface, UserProviderInterface & EncoderFactoryInterface.

Therefore to make proper use of the user credentials grant type you'll need to modify your config.yml with the relevant classes.

# app/config/config.yml

parameters:
    oauth2.user_provider.class: Amce\OAuth2ServerBundle\User\OAuth2UserProvider

If you want to take advantage of scope restriction on a per user basis your User entity will need to implement the OAuth2\ServerBundle\OAuth2UserInterface or OAuth2\ServerBundle\AdvancedOAuth2UserInterface.

Out of the box we do provide a basic user provider and entity for you to use. Setup your security.yml to use it:

# app/config/security.yml

security:
    encoders:
        OAuth2\ServerBundle\Entity\User:
            algorithm:          sha512
            encode_as_base64:   true
            iterations:         5000

    providers:
        oauth2:
            id: oauth2.user_provider

You'll need some users first though! Use the console command to create a new user:

$ php app/console OAuth2:CreateUser username password

Configuring Grant Types

You'll need to use a Compiler Pass to configure settings for a grant type. For example say we want our refresh tokens to always get renewed:

// Amce/OAuth2ServerBundle/AmceOAuth2ServerBundle.php

namespace Amce\OAuth2ServerBundle;

use Symfony\Component\HttpKernel\Bundle\Bundle;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Amce\OAuth2ServerBundle\DependencyInjection\Compiler\OAuth2CompilerPass;

class AmceOAuth2ServerBundle extends Bundle
{
    public function build(ContainerBuilder $container)
    {
        parent::build($container);

        $container->addCompilerPass(new OAuth2CompilerPass());
    }
}

// Amce/OAuth2ServerBundle/DependencyInjection\Compiler\OAuth2CompilerPass.php

namespace Amce\OAuth2ServerBundle\DependencyInjection\Compiler;

use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
use Symfony\Component\DependencyInjection\Reference;

class OAuth2CompilerPass implements CompilerPassInterface
{
    public function process(ContainerBuilder $container)
    {
        // Override Refresh Token Grant Type Settings
        $serviceId = 'oauth2.grant_type.refresh_token';
        if ($container->hasDefinition($serviceId)) {
            $definition = $container->getDefinition($serviceId);
            $definition->replaceArgument(1, array(
                'always_issue_new_refresh_token' => TRUE
            ));
        }
    }
}