adding_grant_extensions.md

Adding Grant Extensions

OAuth2 allows to use grant extensions. It will let you define your own new grant_types, when legacy grant_types do not cover your requirements.

Like classic grants, the grant extensions still requires valid client credentials, and the grant extension has to be added on the allowedGrantTypes property of the client.

Creating the GrantExtension

The GrantExtension class responsibility is to grant an access token, or not, based on the request parameters/headers.

To illustrate the use of a new grant extension, we'll create one that grants access_token like the bingo game. This is of course not something to do :)

Create your extension class:

<?php

// src/Acme/ApiBundle/OAuth/BingoGrantExtension.php

namespace Acme\ApiBundle\OAuth;

use FOS\OAuthServerBundle\Storage\GrantExtensionInterface;
use OAuth2\Model\IOAuth2Client;

/**
 * Play at bingo to get an access_token: May the luck be with you!
 */
class BingoGrantExtension implements GrantExtensionInterface
{
    /*
     * {@inheritdoc}
     */
    public function checkGrantExtension(IOAuth2Client $client, array $inputData, array $authHeaders)
    {
        // Check that the input data is correct
        if (!isset($inputData['number_1']) || !isset($inputData['number_2'])) {
            return false;
        }

        $numberToGuess1 = rand(0, 100);
        $numberToGuess2 = rand(0, 100);

        if ($numberToGuess1 != $inputData['number_1'] && $numberToGuess2 != $inputData['number_2']) {
            return false; // No number guessed, grant will fail
        }

        if ($numberToGuess1 == $inputData['number_1'] && $numberToGuess2 == $inputData['number_2']) {
            // Both numbers were guessed, we grant an access_token linked
            // to a user
            return array(
                'data' => $userManager->findRandomUser()
            );
        }

        if ($numberToGuess1 == $inputData['number_1'] || $numberToGuess2 == $inputData['number_2']) {
            // Only one of the numbers were guessed
            // We grant a simple access token

            return true;
        }

        return false; // No number guessed, the grant will fail
    }
}

Register the extension

You then have to register your class as a service, add the tag fos_oauth_server.grant_extension with the uri parameter (ie: the name of your grant type).

services:
    acme.api.oauth.bingo_extension:
        class: Acme\ApiBundle\OAuth\BingoGrantExtension
        tags:
            - { name: fos_oauth_server.grant_extension, uri: 'http://acme.com/grants/bingo' }

Usage

$ curl -XGET "http://acme.com/oauth/v2/token? \
grant_type=http://acme.com/grants/bingo& \
client_id=1_1& \
client_secret=secret& \
number_1=42& \
number_2=66"