Download the PHP package aeris/zf-auth without Composer

ZfAuth

Authentication/Authorization components for Zend Framework 2.

• Install
  • Configuration Reference
  • OAuth2 Database Setup
• Authentication
  • Handling invalid credentials
  • Identity Providers
  • Usage Example
  • Custom Identity Providers
• Authorization
  • Route Guards
  • Configuration
  • ControllerGuard
  • Custom Guards
• Voters
  • Using Voters
  • How Voters Work
  • Implementing Custom Voters
  • Voter Configuration Reference

Install

Install with composer

Add module to your application.config.php

Configuration Reference

OAuth2 Database Setup

If your using the Zf\OAuth2 module, you will need to create database tables for oauth storage. See /tests/data/zf-oauth-test.sql for an example MySQL oauth db schema.

Aeris\ZfAuth has a set of Doctrine entities which map to the oauth database tables, located under the Aeris\ZfAuth\Entity namespace.

You can see sample configuration files for wiring up Zf\OAuth2, and DoctrineOrmModule in /tests/config/autoload/

Authentication

ZfAuth attempts to authenticate requests using a set of IdentityProviders. By default, users can be authenticated as:

• User implementing IdentityInterface, as configured in zf_auth.authentication.user_entity_class (a request with an access_token)
• \Aeris\ZfAuth\Identity\OAuthClientIdentity (a request with only client_id/client_secret)
• \Aeris\ZfAuth\Identity\AnonymousIdentity (a request with no authentication keys)

Handling invalid credentials

If a request contains authentication credentials, but the identity provider is unable to provide an identity -- eg. the request contains an invalid/expired access_token -- an MvcEvent::EVENT_DISPATCH_ERROR event will be triggered, containing an \Aeris\ZfAuth\Exception\AuthenticationException.

This can be handled by whatever view mechanism you wish. If you're using Aeris\ZendRestModule, you would handle AuthenticationExceptions in your errors config:

Identity Providers

ZfAuth authenticates requests via Identity Providers, which expose IdentityInterface objects. An identity provider can be wrapped as a ZF2 service, and injected into controllers, authorization services, etc.

The default ZfAuth identity provider authenticates users from access tokens using the Zf\OAuth module, and returns a user of the type defined in the zf_auth.authentication.user_entity_class config.

The default identity provider is a ChainedIdentityProvider, which means that it will attempt to return an identity from a collection of identity providers, returning the first identity provided. An call to getIdentity() will look like:

• Find user associated with the requested access_token
• If no user is found, find a \Aeris\ZfAuth\Identity\OAuthClientIdentity associated with the requested client_id/client_secret
• If no user is found, return an \Aeris\ZfAuth\Identity\AnonymousIdentity instance

Usage Example

Custom Identity Providers

Let's say we have a super-special user, with a super-special static password, which let's them do super-special things. Here's how we might go about authenticating that user.

Now let's wire it up.

Authorization

ZfAuth provides two ways to restrict resource access to authorized identities:

1. Route Guards
2. Voters

Route guards allow you to restrict access to a resource before a request has made it to a controller, using a simple rule set. Voters allow you to restrict access to a specific resource, using advanced logic.

Route Guards

After a route has been matched to a controller, but before the controller action executes, ZfAuth will check your route guard rules, to see if the current identity passes each rule.

Configuration

Route guards are configured using the zf_auth.guards module option. Each key is the name of a guard service, and the value is an array of rules to apply to the guard.

This example config would let any user access any action in the IndexController, but only let users with an admin role access get, getList, update, and fooAction methods on the AdminController.

Note that any controller/action which is not configured will be restricted by default.

ControllerGuard

The Aeris\ZfAuth\Guard\ControllerGuard restricts access to controller actions based on the requesting user's role.

The options are:

• 'controller' The controller for which this rule applies (ControllerManager service name)
• 'actions' The actions for which this rule applies. Use '*' to apply this rule to all actions of the controller. Note that to use REST actions, you must be using Aeris\ZendRestModule\Mvc\Router\Http\RestSegment route types (from Aeris\ZendRestModule)
• 'roles' The roles which are allowed access to this controller action. Use '*' to allow any role.

Custom Guards

You can create a custom guard, which implements the GuardInterface:

The isGranted method should return true if the current identity is allowed to access the resource.

To demonstrate, let's make a guard that restricts users based on their username. Our final configuration will look like this:

Our UsernameGuard class will check the current controller and user identity against the rules provided in the configuration:

The last step is to register your guard with the ZfAuth guard manager:

Voters

Voters allow you to restrict access to specific resources.

Using Voters

The primary way to use voters is via the AuthService. Here's an example of how you might use the AuthService in a controller:

Notice that this controller implements Aeris\ZfAuth\Service\AuthServiceAwareInterface -- this will cause the controller to be automatically injected with the AuthService\Aeris\ZfAuth\Service\AuthService service by the ZF2 ControllerManager.

You can also grab the AuthService from the application service locator: $serviceLocator->get('AuthService\Aeris\ZfAuth\Service\AuthService')

How Voters Work

A Voter is a class implementing \Symfony\Component\Security\Core\Authorization\Voter\VoterInterface. The Voter::vote() method returns either:

• VoterInterface::ACESS_GRANTED
• VoterInterface::ACESS_DENIED
• VoterInterface::ACCESS_ABSTAIN

When you call AuthService::isGranted($action, $resource), the auth service runs through each registered voter, and collects votes. If any voter returns ACCESS_DENIED, then isGranted() will return false.

Implementing Custom Voters

Let's work off of the AnimalRestController::create() example from above. And let's say Mr. Boss Man gave us two rules that we must enforce:

1. Only logged in OAuth users may create animals
2. If you want to create a monkey, you must first be a monkey.

For these two rules, we will create two different voters:

Finally, we need to register these voters, using the zf_auth.voter_manager config:

Voter Configuration Reference