Download the PHP package xfra35/f3-access without Composer
On this page you can find all versions of the php package xfra35/f3-access. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download xfra35/f3-access
More information about xfra35/f3-access
Files in xfra35/f3-access
Package f3-access
Short Description Route access control for the PHP Fat-Free Framework
License GPL-3.0
Homepage https://github.com/xfra35/f3-access
Informations about the package f3-access
Access
Route access control for the PHP Fat-Free Framework
This plugin for Fat-Free Framework helps you control access to your routes.
- Requirements
- Installation
- Basic usage
- Advanced usage
- Authorization failure
- HTTP methods access control
- Simple permission check
- Rules processing order
- Path precedence
- Subject precedence
- Routes uniqueness
- Path case insensitivity
- Wildcards and tokens
- Named routes
- Ini configuration
- Practical configuration examples
- Secure an admin area
- Secure MVC-like routes
- Secure RMR-like routes
- Secure a members-only site
- Pitfall
- API
- Potential improvements
Requirements
This plugin takes care about authorization, not authentication. So before using it, make sure you have a way to identify your app users.
Installation
To install this plugin, just copy the lib/access.php
file into your lib/
or your AUTOLOAD
folder.
Basic usage
Instantiate the plugin and define a default access policy (allow or deny) for your routes:
Then define a set of rules to protect a specific route:
or a group of routes:
And call the authorize()
method where it fits your app best (before or after $f3->run()
):
That's it!
We have restricted access to /secured.htm
and to all the URIs starting by /protected
.
Any user not identified as "admin" will get an error.
Bear in mind that "admin" can be anything meaningful to your application: a user name, group, role, right, etc..
So instead of "admin", we could have granted access to "[email protected]" or "admin-role" or "Can access admin area".
For this reason, from now on we will call "admin" a subject.
Multiple subjects can be addressed by a single rule:
NB: subject names can contain any character but commas.
Advanced usage
Authorization failure
A denied access will result in a 403 error if the subject is identified or a 401 if it is not. In our first example:
$somebody='client'
would get a 403 error (Forbidden)$somebody=''
would get a 401 error (Unauthorized => user should authenticate first)
You can provide a callback to the authorize()
method, which will be triggered when authorization fails:
The default behaviour (403/401) is then skipped, unless the fallback returns FALSE.
HTTP methods access control
Route permissions can be defined at HTTP method level:
In this example, only "admin" can modify /path
. Any other subject can only GET
it.
IMPORTANT: providing no HTTP method is equivalent to providing all HTTP methods (unless you're using named routes, see below).
E.g:
Simple permission check
If you need to check access permissions to a route for a specific subject, use the granted()
method:
This method performs a simple check and doesn't take any action (no error thrown).
Rules processing order
Path precedence
Rules are sorted from the most specific to the least specific path before being processed. So the following rules:
are processed in the following order:
IMPORTANT: the first rule for which the path matches applies. If no rule matches, the default policy applies.
Subject precedence
Specific subject rules are processed before global rules. So the following rules:
are processed in the following order:
- 2,3,1 for the subject "zag"
- 3,1 for the subject "zig"
Routes uniqueness
Rules are indexed by subject name and routes, so you can't have two rules for the same subject and the same route. If the case arises, the second rule erases the first:
In this example:
- rule #1 is ignored
- rule #3 is ignored for Dina only (not for Misha)
Path case insensitivity
For security purposes, paths are considered case insensitive, no matter the value of the framework CASELESS
variable.
Therefore, the following rules are equivalent:
Wildcards and tokens
Wildcards can be used at various places:
- instead of a route verb, meaning "any verb":
* /path
- equivalent to
/path
- equivalent to
GET|HEAD|POST|PUT|PATCH|DELETE|CONNECT /path
- equivalent to
- in a route path, meaning "any character":
GET /foo/*/baz
- instead of a subject, meaning "any subject":
$f3->allow('/','*')
- equivalent to
$f3->allow('/','')
- equivalent to
$f3->allow('/')
- equivalent to
NB: wildcards match empty strings, so /admin*
match /admin
.
Routes tokens are also supported, so $f3->allow('/blog/@id/@slug')
is recognized.
Since the plugin doesn't make use of the token names, you can as well drop them: $f3->allow('/blog/@/@')
In other words, @
is a wildcard for any character which is not a forward slash,
whereas *
matches everything, including forward slashes.
IMPORTANT: read the Pitfall section.
Named routes
If you're using named routes,
you can directly refer to their aliases: $f3->allow('@blog_entry')
;
In that case, providing no HTTP method is equivalent to providing the methods which are actually mapped to the given route. See:
Ini configuration
Configuration is possible from within an .ini file, using the ACCESS
variable.
Rules should be prefixed by the keywords "allow" or "deny" (case-insensitive):
It works with HTTP verbs as well:
Practical configuration examples
Secure an admin area
Secure MVC-like routes
Secure RMR-like routes
Secure a members-only site
Pitfall
Static routes overriding dynamic routes
Be careful when having static routes overriding dynamic routes.
Although not advised, the following setup is made possible by the framework:
From an authorization point of view, we may be tempted to write:
Doing so, we might think that the edit_role
can't access the /admin/user/new
path, but this is an illusion.
Indeed, the @id
token match any string, including new
.
To be convinced of this, just think that there's no difference between /admin/user/@id
and /admin/user/@anything
.
So in order to achieve a complete separation of roles, the correct configuration would be, in this situation:
A clearer setup would be:
- either to define one single path
/admin/user/@id
withid=new
being handled inside a single controller - or to define two unambiguous paths, for example
/admin/user/@id
and/admin/new-user
API
policy( $default=NULL )
Get/set the default policy (default='allow')
allow( $route, $subjects='' )
Allow specified subject(s) to access a given route
deny( $route, $subjects='' )
Deny specified subject(s) access to a given route
granted( $route, $subject='' )
Return TRUE if the given subject is granted access to the given route
NB: you can also check access against a set of subjects. This is useful for example if you've implemented a system of user roles or groups:
authorize( $subject='', $ondeny=NULL )
Return TRUE if the given subject is granted access to the current route
If $subject
is not provided, authorization is performed against "any" subject.
$ondeny
should be a valid F3 callback (either a PHP callable or a string)
See here for details about what happens when authorization fails.
NB: you can also perform authorization against a set of subjects. This is useful for example if you've implemented a system of user roles or groups: just pass the array of roles/groups to authorize a user. E.g:
Potential improvements
- Think about
HEAD
andCONNECT
: should they be authorized or consistently allowed?