First of all, if you still don’t know anything about Zend Expressive check it out: http://zendframework.github.io/zend-expressive/

Prerequisites:

• A decent grasp of PHP
• REST fundamentals
• Basic Zend Expressive knowledge

“Token based authentication works by ensuring that each request to a server is accompanied by a signed token which the server verifies for authenticity and only then responds to the request.”

So, we assume that we have a login page that will send the user credentials to our API endpoint (that will be http://api.mvlabs.it/api/v1/user/login in our example) and, if the given credentials are correct, then the API will respond with a token to the Front-End and the Front-End application will use the token to access the restricted resources in the following requests.

OK, so …how can I do that with Zend Expressive?

In Zend Expressive we could use a Middleware plugged into our pipeline to verify the token validity. So, for this scope we’ll use the tuupola/slim-jwt-auth middleware. It was originally developed for Slim but can be used with any framework that complies with the PSR-7 standard and of course, Zend Expressive is one of them! Yep, code reuse is a great thing enabled by Middleware! Ok, let’s take a look. First of all, we need to add to our Zend Expressive skeleton application the jwt auth middleware:

$ composer require tuupola/slim-jwt-auth

Now we need to add some configurations parameters that will be used by the JwtAuthentication Middleware. In fact, the only mandatory parameter is “secret” which is used to verify the token signature, only the issuer application has to know it and should never be disclosed in any way. So:

config/autoload/jwt-authentication.global.php

return [
   'jwt-authentication' => [
       "secret" => getenv("JWT_SECRET"),
       "path" => ["/"],
       "passthrough" => ["/api/v1/user/login", "/api/v1/ping"],
       "error" => function ($request, $response, &$arguments) {
           $data["status"] = "error";
           $data["message"] = $arguments["message"];

           return $response
               ->withHeader("Content-Type", "application/json")
               ->write(json_encode($data, JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT));
       }
   ]
];

Some notes about the configuration above:

• The optional path parameter allows us to specify the protected part of your website.
• With optional passthrough parameter we can make exceptions to path parameter.
• error is called when authentication fails. It receives last error message as argument.

Now we can create our JwtAuthentication Middleware through a factory with our configuration defined above.

src/App/Factory/JwtAuthenticationFactory.php

namespace App\Factory;

use Interop\Container\ContainerInterface;
use Slim\Middleware\JwtAuthentication;

class JwtAuthenticationFactory
{
   public function __invoke(ContainerInterface $container)
   {
       $config = $container->get('config');
       return new JwtAuthentication($config['jwt-authentication']);
   }
}

Now is time to add the Jwt Authentication Middleware to the ZE middleware pipeline, then it will have the responsibility to determine if a token is valid for the protected endpoints.

config/autoload/middleware-pipeline.global.php

return [
   'dependencies' => [
       'factories' => [
	...
           Slim\Middleware\JwtAuthentication::class => App\Factory\JwtAuthenticationFactory::class,
	...
       ],
   ],
   'middleware_pipeline' => [
       'always' => [
           'middleware' => [
	       ...
               Slim\Middleware\JwtAuthentication::class,
               ...
           ],
           'priority' => 10000,
    ],
    'routing' => [
       'middleware' => [
            ...
       ],
       'priority' => 1,
    ],
       ...
   ],
];

At this point we need to define some routes in our configuration file, so let’s add the following:

• /api/v1/ping unprotected example endpoint
• /api/v1/user/login (unprotected) used for authentication and token generation
• /api/v1/user/:id the protected endpoint example that returns user specific data

config/autoload/routes.global.php

return [
   'dependencies' => [
       'factories' => [
           App\Action\AuthAction::class => App\Action\AuthFactory::class,
       ],
   ],

   'routes' => [
       [
           'name' => 'api.ping',
           'path' => '/api/v1/ping',
           'middleware' => App\Action\PingAction::class,
           'allowed_methods' => ['GET'],
       ],
       [
           'name' => 'api.auth',
           'path' => '/api/v1/user/login',
           'middleware' => App\Action\AuthAction::class,
           'allowed_methods' => ['POST'],
       ],
       [
           'name' => 'api.user.get',
           'path' => '/api/v1/user/:id',
           'middleware' => App\Action\UsersAction::class,
           'allowed_methods' => ['GET'],
       ],
   ],
];

Now, we need to add the logic that will handles the data sent by the login form, validate it against a database, and after determining that the credentials are valid, will generate the token. So, we’ll define the AuthAction Middleware that will have those responsibilities:

namespace App\Action;
namespace App\Action;

use App\Entity\User;
use App\Service\UserService;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Zend\Diactoros\Response\JsonResponse;

class AuthAction
{
    private $userService;

    public function __construct(UserService $userService)
    {
        $this->userService = $userService;
    }

    public function __invoke(ServerRequestInterface $request, ResponseInterface $response, callable $next = null)
    {
        $post = $request->getParsedBody();
        $username = $post['username'];
        $password = $post['password'];

        $user = $this->userService->getUserByEmailPassword($username, $password);
        if ($user instanceof User) {
            $jwt = $this->userService->getAuthTokenForUser($user);

            return new JsonResponse([
                'time' => time(),
                'jwt' => $jwt,
            ]);
        }

        return new JsonResponse(['status' => 'error'], 401);
    }
}

Let’s take a detailed look to the token generation in the UserService:

namespace App\Service;

use App\Entity\User;
use Firebase\JWT\JWT;

class UserService
{

    ...

    public function geAuthTokenForUser(User $user)
    {
        $now = new \DateTime();
        $future = new \DateTime("now +2 hours");

        $random_number = openssl_random_pseudo_bytes(32); //generate using openssl_random_pseudo_bytes
        $jti = hash('sha256', $user->getId() . $random_number);
        $serverName =  $this->config['api']['endpoint'];
        /*
         * Create the token as an array
         */
        $data = [
            "iat" => $now->getTimeStamp(),  // Issued at: time when the token was generated
            'jti' => $jti, // Json Token Id: an unique identifier for the token
            'iss' => $serverName, // Issuer
            'nbf' => $now->getTimeStamp()+10, // Not before
            "exp" => $future->getTimeStamp(), // Expire
            'data' => [ // Data related to the signer user
                'userId' => $user->getId(), // userid from the users table
                'username' => $user->getUsername(), // User name
            ]
        ];

        /*
         * Encode the array to a JWT string. Second parameter is the key to encode the token.             *
         * The output token $jwt can be validated at http://jwt.io/
         */
        $jwt = JWT::encode(
            $data,
            $this->config['jwt-authentication']['secret'],
            "HS512"
        );

        return $jwt;
    }
}

In order to check that everything is OK, let’s do a test call to our authentication endpoint with postman, passing our authentication credentials.

Good, everything looks fine, so, at this point the client will have the token, and can store it using a storage mechanism like HTML5 Web Storage.

Now let’s retrieve a resource that is protected by our JWT mechanism. But first we need to set the Authorization header with the contents of the JWT in the format of Bearer [JWT]

As we can see in the image above, we can access to the restricted resource once that we passed our authentication token.

Summary

This is a very reliable method to secure your information. From here on, you can try to implement a token based authentication using ZE in your next API. Feel free to share your constructive feedback or ask a question. Drop a note below, we’ll be happy to receive your comments!

For starters, what is routing?

The fundamental principle of routing is to match incoming requests reaching an application and decide which fragment of code to execute. That could mean matching either an http request or a console requests (if you are interacting with a Command Line Interface application), and extracting the parameters that determine which snippet of code (IE which controller and then which action) to execute. The other basic principle is to assemble URLs and commands back. That is, from a set of parameters, to build the path of the route. In terms of an example, this means coming up with the /products/view/some_product URL starting from the controller = products, action = view, slug = some_product parameters*.

*I am aware this might not be the best possible example URL, but I hope it gets the message across in simple terms.

Why should we care about routing?

There are different reasons why routing is important. The simplest and most important one is that without routing your application won’t work Even in a working application, though, properly handling routing is important. That’s for different reasons, which can be summarized as follows:

- good URLs are easier to remember, type and share through word of mouth
- they also make it easier for search engines to properly index websites and web applications
- they allow for clean RESTful interfaces to be build
- they improve web application security, because they make it easier for parameters to be properly handled

Routing within the Zend Framework 2

Under the Hood

The basic unit of routing is a so called route, which is nothing but a PHP class implementing the following interface:

namespace Zend\Mvc\Router;

use zend\Stdlib\RequestInterface as Request;

interface RouteInterface
{
  public static function factory(array $options = array());
  public function match(Request $request);
  public function assemble(array $params = array(), array $options = array());
}

The RouteInterface includes the  static method factory, which is used to create new routes. Every route is constructed with arguments (usually fetched from specific project/module configuration file). The match method, in turn, accepts a new Request, and determines if the request matches current route. If true, it then returns a RouteMatch object, which is a container object, that includes the route name and most likely all route parameters and values. Last, we also have the assemble method, which takes options and parameters and builds the path of a route (usually an URL).

We will rarely need to worry about implementation details of these methods, though, because the framework will take care of passing the configuration and creating our routes according to our definitions in each module configuration directives (as we’ll shortly see).

Defining new routes

Routes for each module shall be defined within the module configuration file, which can be found in every module’s root folder. The default Zend Framework Skeleton app also has its own Module.php file in /config/modules.config.php:

The section dealing with routing is the one which goes under the router key; routes contains a list of our routes in array form:

return array(
  'router' => array(
    'routes' => array(
      'contact' => array(
        'type' => 'Literal',
        'options' => array(
          'route'    => '/contact',
          'defaults' => array(
            'controller' => 'Application\Controller\Contact',
            'action'     => 'index',
          ),
        ),
      ),
    ),
  ),
),

In the basic example above, we defined a route named “contact”, of type Literal (all different Route types will be covered in a forthcoming post). Basically we just told the framework to dispatch users requesting the ‘/contact’ URL to the Contact controller, and to have the IndexAction method to be executed.

What about route stacks

The ZF2 router is a collection of routes, based on a priority stack. As it was happening in Zend Framework 1, routes can be added to a route list; the last added route is the one tested first. The same now happens in ZF2; we can now also take advantage of the new priority attribute, though. This means that every route will have a priority value, and highest priorty route will be tested first. I’m sure this will make it easier to keep things organized without needing to worry much about route position within configuration files. This will also make it easier for custom configurations to be used to override third party default configurations.

Every router (there are different types, which we’ll take a look at shortly) implements this interface:

namespace Zend\Mvc\Router;

interface RouteStackInterface extends RouteInterface
{
  public function addRoute($name, $route, $priority = null);
  public function addRoutes(array $routes);
  public function removeRoute($name);
  public function setRoutes(array $routes);
}

All methods are self-explanatory, so I won’t go in further detail here. This is with the exception of the setRoutes method, which probably deserves some explanation. This method in fact replaces current routes in the stack with the new ones provided as an argument. So, it first removes current routes, then adding the new ones.

Router types

There are different implementations of the aforementioned Router base class:

• SimpleRouteStack: the most basic implementation, which we can use and extend to make our own router stack class.
• Http\TreeRouteStack: the most common kind of router, it is used to create a tree of routes to deal with http requests, using a B-tree algorithm to match routes (this ensures that evaluation is efficiently made, as we’ll shortly see).
• Console\SimpleRouteStack: used in the realm of CLI applications and use to take care of command line arguments. This kind of router will be processed when our application is run from a console terminal window.

Tree Routing

Zend Framework 2 introduces the Tree Routing concept as a big innovation. In fact, it’s very easy to use and its performance is great also: it’s much faster than its ZF1 counterpart. This is for multiple reasons: first off is the fact that the framework doesn’t try to match incoming requests with every single route anymore. This happens because every route can now have an unlimited number of children routes, which aren’t evaluated if parent route didn’t match the request first. Children routes are in fact only instantiated when the router matches or assembles their respective parent routes.

A Tree Route will consist of the following configuration:

• A base route, known as root route, which describes the base path (first part of an URL, for example);
• The may_terminate key, which is set to false by default, telling the router whether the route may terminate or not.
• The child_routes key, an array containing additional routes that stem from the base “route”. Each child route can itself be a Tree Route

Example:

return array(
  'router' => array(
    'routes' => array(
      'zf' => array(
      'type' => 'Literal',
      'options' => array(
        'route' => '/zf',
        'defaults' => array(
        '__NAMESPACE__' => 'Application\Controller',
        'controller'    => 'Article',
        'action'        => 'index',
      ),
    ),
    'may_terminate' => true,
    'child_routes' => array(
    'default' => array(
      'type'    => 'Segment',
      'options' => array(
        'route'    => '/:action',
        'constraints' => array(
          'action'     => '[a-zA-Z][a-zA-Z0-9_-]*',
        ),
      ),
    ),
  ),

Summary

In this first post about the Zend Framework 2 routing, I’ve introduced what’s a route, what’s routing, how the routing system works in the Zend Framework 2, and how it differs (especially from a performance point of view) from the ZF1 implementation. In my next post, I will be covering different HTTP route types we have at hand. Is there anything else you’d like to know? Just let me know with a comment below.