Symfony a RESTFul app: Security ( FOSOAuthServerBundle )

In the previous post we set up a basic symfony project aiming to develop a RESTFul solution.

Now we are on the last post of this series, “Security“. You may question:

Why security as the last post, should not be security the first thing we should ensure?

Sure, security can be, and from my point of view; the most controversial and complex topic on our business. There a lot of ways to enforce security on our apps, ones may say some of those solutions are not bullet proof, others may say some of them are too complicated for their business. The truth is that you should study a lot about this topic and decide by your self which is the best solution for your business at the right moment.

Because all of that is why i leave this post for the last of this series so you can decide to read it or not, or even if it should be part of this series or not; i hope what ever your call is, this post remains useful.

As always all the code on this series can be found on this github repository under the symfony2_restful_example branch.

Securing a RESTFul App:

In almost all the cases you will need to perform some kind of user authentication and authorization, unless your app is completely open to anonymous, but for the sake of this post i will assume that you will need it.

From the many security approaches out there i will talk about only two of them, both i have used it on the past.

API Key Authentication and WSSE:

Both approaches share the same concept where the final authentication is performed with the API Token. In the first case is much basic since the clients need to know the token from the start and that can be used from 3th sources to attack our system. The WSSE specification describe a more secure process where the user authenticate with their credentials and then the API Token is delivered to the clients for farther use.

Both on this section are well documented on the symfony official documentation, so i will not extend on they and how to implement it.

• API Key Authentication
• WSSE

OAuth:

As wikipedia describes:

OAuth is an open standard for authorization. OAuth provides client applications a ‘secure delegated access’ to server resources on behalf of a resource owner.

The standard evolve from version 1.0 to version 2.0

OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices.

On this post we will talking about version 2.0 of OAuth since its more complete. This approach is used for authentication on almost all the social networks ans services that we use now a day (Google, Facebook, Twitter, LinkedIn, Github, etc)

FOSOAuthServerBundle:

Yes another bundle from FOS, this one will allow us to use OAuth2 on our projects. Sadly the documentation of this bundle is no so great as the others, and there are as always several ways to make it work; so i will focus on make it work for our little example, also i will try to explain the approach i choose to follow and the reasons why.

Lest start installing the bundle

composer require friendsofsymfony/oauth-server-bundle

And enable it on the AppKernel

new FOS\OAuthServerBundle\FOSOAuthServerBundle(),

Great we have the bundle installed. To work we need to define four models that in fact are the main terms of the OAuth2 specification, Client, AccessToken, RefreshToken and AuthCode. To keep following our clean architecture lets put this models inside our Customer package, they should look like this:

Client.php

<?php

namespace Customer;

use FOS\OAuthServerBundle\Entity\Client as BaseClient;

class Client extends BaseClient
{
    protected $id;
    protected $name;

    public function setName($name)
    {
        $this->name = $name;
    }

    public function getName()
    {
        return $this->name;
    }
}

I add to the client the property name so we can identify our client humanly, maybe on your business rules you can even find some other data like, the version of the client, the target platforms, etc.

AccessToken.php

<?php

namespace Customer;

use FOS\OAuthServerBundle\Entity\AccessToken as BaseAccessToken;

class AccessToken extends BaseAccessToken
{
    protected $id;
    protected $client;
    protected $customer;
}

RefreshToken.php

<?php

namespace Customer;

use FOS\OAuthServerBundle\Entity\RefreshToken as BaseRefreshToken;

class RefreshToken extends BaseRefreshToken
{
    protected $id;
    protected $client;
    protected $customer;
}

AuthCode.php

<?php

namespace Customer;

use FOS\OAuthServerBundle\Entity\AuthCode as BaseAuthCode;

class AuthCode extends BaseAuthCode
{
    protected $id;
    protected $client;
    protected $customer;
}

As you can see all the classes extend from the models exported by the bundle.

But we need to integrate it with symfony and doctrine so lets create our entities and the mapping.

AppBundle/Entity/Client.php

<?php

namespace AppBundle\Entity;

use Customer\Client as BaseClient;

class Client extends BaseClient
{
}

AppBundle/Entity/AccessToken.php

<?php

namespace AppBundle\Entity;

use Customer\AccessToken as BaseAccessToken;

class AccessToken extends BaseAccessToken
{
}

AppBundle/Entity/RefreshToken.php

<?php

namespace AppBundle\Entity;

use Customer\RefreshToken as BaseRefreshToken;

class RefreshToken extends BaseRefreshToken
{
}

AppBundle/Entity/AuthCode.php

<?php

namespace AppBundle\Entity;

use Customer\AuthCode as BaseAuthCode;

class AuthCode extends BaseAuthCode
{
}

AppBundle/Resources/config/doctrine/Client.orm.yml

AppBundle\Entity\Client:
    type: entity
    table: client
    id:
        id:
            id: true
            type: integer
            generator: { strategy: AUTO }
    fields:
        name:
            type: string
            lenght: 255
    lifecycleCallbacks: {  }

AppBundle/Resources/config/doctrine/AccessToken.orm.yml

AppBundle\Entity\AccessToken:
    type: entity
    table: access_token
    id:
        id:
            id: true
            type: integer
            generator: { strategy: AUTO }
    manyToOne:
        user:
            targetEntity: Customer
            joinColumn:
                name: costumer_id
                referencedColumnName: id
        client:
            targetEntity: Client
            joinColumn:
                name: client_id
                referencedColumnName: id
    lifecycleCallbacks: {  }

AppBundle/Resources/config/doctrine/RefreshToken.orm.yml

AppBundle\Entity\RefreshToken:
    type: entity
    table: refresh_token
    id:
        id:
            id: true
            type: integer
            generator: { strategy: AUTO }
    manyToOne:
        user:
            targetEntity: Customer
            joinColumn:
                name: costumer_id
                referencedColumnName: id
        client:
            targetEntity: Client
            joinColumn:
                name: client_id
                referencedColumnName: id
    lifecycleCallbacks: {  }

AppBundle/Resources/config/doctrine/AuthCode.orm.yml

AppBundle\Entity\AuthCode:
    type: entity
    table: auth_code
    id:
        id:
            id: true
            type: integer
            generator: { strategy: AUTO }
    manyToOne:
        user:
            targetEntity: Customer
            joinColumn:
                name: costumer_id
                referencedColumnName: id
        client:
            targetEntity: Client
            joinColumn:
                name: client_id
                referencedColumnName: id
    lifecycleCallbacks: {  }

Great we have our model set, lets finish the bundle configuration on config.yml.

fos_oauth_server:
    db_driver: orm
    client_class:        AppBundle\Entity\Client
    access_token_class:  AppBundle\Entity\AccessToken
    refresh_token_class: AppBundle\Entity\RefreshToken
    auth_code_class:     AppBundle\Entity\AuthCode
    service:
        user_provider: fos_user.user_manager

Note that is important to add the service for the user provider since we are using FOSUserBundle, if you have any other user provider you need to put it here.

I know a lot of steps but we are almost done, just two more configurations before we can actually start coding. Lets configure our security file security.yml, that is the main reason we are going through this post.

# To get started with security, check out the documentation:
# http://symfony.com/doc/current/book/security.html
security:
    encoders:
        FOS\UserBundle\Model\UserInterface: bcrypt

    providers:
        fos_userbundle:
            id: fos_user.user_provider.username

    firewalls:
        # disables authentication for assets and the profiler, adapt it according to your needs
        dev:
            pattern:      ^/(_(profiler|wdt)|css|images|js)/
            security:     false

        oauth_token:
            pattern:      ^/oauth/v2/token
            security:     false

        api_doc:
            pattern:      ^/api/doc
            security:     false

        api:
            pattern:      ^/api
            fos_oauth:    true
            stateless:    true

    access_control:
        - { path: ^/api, roles: [ IS_AUTHENTICATED_FULLY ] }

Lets talk about this configuration line by line:

encoders:
    FOS\UserBundle\Model\UserInterface: bcrypt

providers:
    fos_userbundle:
        id: fos_user.user_provider.username

We introduce the encoder and the user provider in the previous post about FOSUserBundle.

Firewalls, as we know; are the symfony way to secure routes by patterns so lets have a break down on the firewalls we have configured:

dev:
    pattern:      ^/(_(profiler|wdt)|css|images|js)/
    security:     false

The development default firewall so we can access the development profiler page and the static files, no security enabled.

api_doc:
    pattern:      ^/api/doc
    security:     false

api:
    pattern:      ^/api
    fos_oauth:    true
    stateless:    true

And the firewalls from the previous posts to access the api end points and the api documentation, notice that i add a prefix “api”, to the path; trying to differentiate it from the oauth ones. Also notice that we set the authentication on the api route to be ensure with the FOSOAuthServerBundle.

oauth_token:
    pattern:      ^/oauth/v2/token
    security:     false

I leave to the final the oauth token end point, since this can be the controversial point. As we can see this end point do not have any security enabled, this is the default configuration provided by the bundle documentation. What this end point does is retrieve the data from the request and validate the client with the public id and the secret, as well the redirect uri, the grant type, the scope and lastly the user with the username and password.

This last part its what makes me doubt of the security since the username and the password are been sent as plain text on the request, and from my point of view this is not a good idea.

For the sake of the post lets leave this discussion for the final part of the post series, Secure the token path; and lets keep going with the configuration and coding.

access_control:
    - { path: ^/api, roles: [ IS_AUTHENTICATED_FULLY ] }

Finally in the access control section lets secure our api to be only accessed by fully authenticated users.

Great we have our security mechanism in place, lets test it. But first we need a client and our user authorize that client. The bundle comes with an implementation for that authorization part, that can be configured to be anything you need, its basically a page like the ones from facebook and google, where the user allow the application to gave authentication for it.

So, Why we don’t include it on our example?

Since this post series its about a RESTFul app, there is no view where the user see this allowing page, going even farther our internal API should not be allowed from our user, lets say we are not exporting our API to third party developers, so our app clients should be always allowed for our clients. For that matter i create a command that allow us to create new clients and authorized them for all our users, lets see it.

<?php
namespace AppBundle\Command;

use Symfony\Bundle\FrameworkBundle\Command\ContainerAwareCommand;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\HttpFoundation\Request;

class CreateOAuthClientCommand extends ContainerAwareCommand
{
    protected function configure()
    {
        $this
            ->setName('oauth:client:create')
            ->setDescription('Create OAuth Client')
            ->addArgument(
                'name',
                InputArgument::REQUIRED,
                'Client Name?'
            )
            ->addArgument(
                'redirectUri',
                InputArgument::REQUIRED,
                'Redirect URI?'
            )
            ->addArgument(
                'grantType',
                InputArgument::REQUIRED,
                'Grant Type?'
            );
    }

    protected function execute(InputInterface $input, OutputInterface $output)
    {
        $container = $this->getContainer();
        $oauthServer = $container->get('fos_oauth_server.server');

        $name = $input->getArgument('name');
        $redirectUri = $input->getArgument('redirectUri');
        $grantType = $input->getArgument('grantType');

        $clientManager = $container->get('fos_oauth_server.client_manager.default');
        $client = $clientManager->createClient();
        $client->setName($name);
        $client->setRedirectUris([$redirectUri]);
        $client->setAllowedGrantTypes([$grantType]);
        $clientManager->updateClient($client);

        $output->writeln(sprintf("<info>The client <comment>%s</comment> was created with <comment>%s</comment> as public id and <comment>%s</comment> as secret</info>",
            $client->getName(),
            $client->getPublicId(),
            $client->getSecret()));

        $customers = $container->get('doctrine')->getRepository('AppBundle:Customer')->findAll();

        foreach ($customers as $customer) {
            $queryData = [];
            $queryData['client_id'] = $client->getPublicId();
            $queryData['redirect_uri'] = $client->getRedirectUris()[0];
            $queryData['response_type'] = 'code';
            $authRequest = new Request($queryData);

            $oauthServer->finishClientAuthorization(true, $customer, $authRequest, $grantType);

            $output->writeln(sprintf("<info>Customer <comment>%s</comment> linked to client <comment>%s</comment></info>",
                $customer->getId(),
                $client->getName()));
        }
    }
}

What do we did here, this command receive the client name, the redirect uri and the grant type, after create the client it retrieve all the users/customers and authorize the recently created app to all. After the execution of this command we should be able to request an access token for a user and then authenticate to query the API. Lest see it on an example:

app/console oauth:client:create client1 www.client1.com code

We create an application named client1, should see an output like this:

The client client1 was created with 88_5qhmvel4ozoko8ws0gc8404s40s40k040k04s8okoo44wcww40 as public id and 4431nwlagk8wsok00sogkkwscgk44k8g484ow04c8o4cwc000s as secret
Customer 55f0369e0cdac linked to client client1

Now we can navigate to the token end point and request the access token

/oauth/v2/token?client_id=89_6488j8o9pickwwgwgos800gkws8o0wk8kwcs84skoo4c04gksw&client_secret=5vmzu0sro10kw8sosg4ccoco4ccs48wwog0kkcgwoksw800s0&grant_type=password&redirect_uri=www.client1.com&username=fabien&password=fabien

As you can see we need to include the username and password of the user in plain text. The response of this request should look like this:

{"access_token":"NDdhYTRjMmQ3MmNmZjZjOWFjYTA5NDQwZmZhNTgwMjczYzYyMDg5ODYzMWZmZjQ2MGUxMDJmNjNmNzI5Zjk4ZA","expires_in":3600,"token_type":"bearer","scope":null,"refresh_token":"YWIzMThhZDY1MGQzZGRlYjlhOGRiYTJjZTdmZjZmMWUyY2Y0YmUyZjRhMTU0YjE5N2VjYzcwZDQ4OTZlZDdlYg"}

Finally we can use the access token to query the api, lets try our old customers end point:

/api/customers

With the header:

Authorization: Bearer NDdhYTRjMmQ3MmNmZjZjOWFjYTA5NDQwZmZhNTgwMjczYzYyMDg5ODYzMWZmZjQ2MGUxMDJmNjNmNzI5Zjk4ZA

And we should see the expected response:

{
id: "55f0369e0cdac"
username: "fabien"
username_canonical: "fabien"
email: "fabien@symfony.com"
email_canonical: "fabien@symfony.com"
enabled: true
salt: "aru3jkvy1r4gcoock4gwocko0w8w4sk"
password: "$2y$13$aru3jkvy1r4gcoock4gwoO2/lUF5PVlUHOqJIUCX9geX7jZxxjTfC"
locked: false
expired: false
roles:
  [0]
credentials_expired: false
links: {
  self: {
    href: "/customers/55f0369e0cdac"
    }
  customers: {  
    href: "/customers"  
    } 
  } 
}

Till now we have successfully configured an OAuth2 service, great.

Conclusion:

Security is really a hard topic to talk about, but i hope this post point you to some ideas on how to accomplish it. OAuth2 is a great protocol, i always think that if the big companies are using something, that something suppose to be good ;).

At the end i decide to add one more post to the series to talk about and of course show some code on what solution do i apply to solve the security flaw on the token path.

Series:

1. Motivation
2. REST Levels 0, 1, 2 ( FOSRestBundle, JMSSerializerBundle )
3. REST Levels 0, 1, 2 ( FOSUserBundle )
4. REST Levels 0, 1, 2 ( NelmioApiDocBundle )
5. REST Levels 3 ( BazingaHateoasBundle )
6. Security ( FOSOAuthServerBundle )
7. Security ( Securing the token path )
8. Security ( Securing the token path – FIXED )

Advertisements