Nette Security: Access Control

Introduction

Authentication & Authorization library for Nette.

• user login and logout
• verifying user privileges
• securing against vulnerabilities
• how to create custom authenticators and authorizators
• Access Control List

Documentation can be found on the website.

It requires PHP version 8.2 and supports PHP up to 8.5.

Support Me

Do you like Nette Security? Are you looking forward to the new features?

Thank you!

Authentication

Authentication means user login, ie. the process during which a user's identity is verified. The user usually identifies himself using username and password. Verification is performed by the so-called authenticator. If the login fails, it throws Nette\Security\AuthenticationException.

try {
	$user->login($username, $password);
} catch (Nette\Security\AuthenticationException $e) {
	$this->flashMessage('The username or password you entered is incorrect.');
}

Logging him out:

$user->logout();

And checking if user is logged in:

echo $user->isLoggedIn() ? 'yes' : 'no';

Simple, right? And all security aspects are handled by Nette for you.

You can also set the time interval after which the user logs off (otherwise he logs off with session expiration). This is done by the method setExpiration(), which is called before login(). Specify a string with relative time as a parameter:

// login expires after 30 minutes of inactivity
$user->setExpiration('30 minutes');

// cancel expiration
$user->setExpiration(null);

Expiration must be set to value equal or lower than the expiration of sessions.

The reason of the last logout can be obtained by method $user->getLogoutReason(), which returns either the constant Nette\Security\User::LogoutInactivity if the time expired or User::LogoutManual when the logout() method was called.

In presenters, you can verify login in the startup() method:

protected function startup()
{
	parent::startup();
	if (!$this->getUser()->isLoggedIn()) {
		$this->redirect('Sign:in');
	}
}

Authenticator

It is an object that verifies the login data, ie usually the name and password. The trivial implementation is the class Nette\Security\SimpleAuthenticator, which can be defined this way

$authenticator = new Nette\Security\SimpleAuthenticator([
	# name => password
	'johndoe' => 'secret123',
	'kathy' => 'evenmoresecretpassword',
]);

This solution is more suitable for testing purposes. We will show you how to create an authenticator that will verify credentials against a database table.

An authenticator is an object that implements the Nette\Security\Authenticator interface with method authenticate(). Its task is either to return the so-called identity or to throw an exception Nette\Security\AuthenticationException. It would also be possible to provide an fine-grain error code Authenticator::IDENTITY_NOT_FOUND or Authenticator::INVALID_CREDENTIAL.

use Nette;

class MyAuthenticator implements Nette\Security\Authenticator
{
	private $database;
	private $passwords;

	public function __construct(Nette\Database\Context $database, Nette\Security\Passwords $passwords)
	{
		$this->database = $database;
		$this->passwords = $passwords;
	}

	public function authenticate($username, $password): Nette\Security\IIdentity
	{
		$row = $this->database->table('users')
			->where('username', $username)
			->fetch();

		if (!$row) {
			throw new Nette\Security\AuthenticationException('User not found.');
		}

		if (!$this->passwords->verify($password, $row->password)) {
			throw new Nette\Security\AuthenticationException('Invalid password.');
		}

		return new Nette\Security\SimpleIdentity(
			$row->id,
			$row->role, // or array of roles
			['name' => $row->username]
		);
	}
}

The MyAuthenticator class communicates with the database through Nette Database Explorer and works with table users, where column username contains the user's login name and column password contains hash. After verifying the name and password, it returns the identity with user's ID, role (column role in the table), which we will mention later , and an array with additional data (in our case, the username).

$onLoggedIn, $onLoggedOut events

Object Nette\Security\User has events $onLoggedIn and $onLoggedOut, so you can add callbacks that are triggered after a successful login or after the user logs out.

$user->onLoggedIn[] = function () {
	// user has just logged in
};

Identity

An identity is a set of information about a user that is returned by the authenticator and which is then stored in a session and retrieved using $user->getIdentity(). So we can get the id, roles and other user data as we passed them in the authenticator:

$user->getIdentity()->getId();
// also works shortcut $user->getId();

$user->getIdentity()->getRoles();

// user data can be access as properties
// the name we passed on in MyAuthenticator
$user->getIdentity()->name;

Importantly, when user logs out, identity is not deleted and is still available. So, if identity exists, it by itself does not grant that the user is also logged in. If we want to explicitly delete the identity, we logout the user by $user->logout(true).

Thanks to this, you can still assume which user is at the computer and, for example, display personalized offers in the e-shop, however, you can only display his personal data after logging in.

Identity is an object that implements the Nette\Security\IIdentity interface, the default implementation is Nette\Security\SimpleIdentity. And as mentioned, identity is stored in the session, so if, for example, we change the role of some of the logged-in users, old data will be kept in the identity until he logs in again.

Authorization

Authorization determines whether a user has sufficient privileges, for example, to access a specific resource or to perform an action. Authorization assumes previous successful authentication, ie that the user is logged in.

For very simple websites with administration, where user rights are not distinguished, it is possible to use the already known method as an authorization criterion isLoggedIn(). In other words: once a user is logged in, he has permissions to all actions and vice versa.

if ($user->isLoggedIn()) { // is user logged in?
	deleteItem(); // if so, he may delete an item
}

Roles

The purpose of roles is to offer a more precise permission management and remain independent on the user name. As soon as user logs in, he is assigned one or more roles. Roles themselves may be simple strings, for example, admin, member, guest, etc. They are specified in the second argument of SimpleIdentity constructor, either as a string or an array.

As an authorization criterion, we will now use the method isInRole(), which checks whether the user is in the given role:

if ($user->isInRole('admin')) { // is the admin role assigned to the user?
	deleteItem(); // if so, he may delete an item
}

As you already know, logging the user out does not erase his identity. Thus, method getIdentity() still returns object SimpleIdentity, including all granted roles. The Nette Framework adheres to the principle of "less code, more security", so when you are checking roles, you do not have to check whether the user is logged in too. Method isInRole() works with effective roles, ie if the user is logged in, roles assigned to identity are used, if he is not logged in, an automatic special role guest is used instead.

Authorizator

In addition to roles, we will introduce the terms resource and operation:

• role is a user attribute - for example moderator, editor, visitor, registered user, administrator, ...
• resource is a logical unit of the application - article, page, user, menu item, poll, presenter, ...
• operation is a specific activity, which user may or may not do with resource - view, edit, delete, vote, ...

An authorizer is an object that decides whether a given role has permission to perform a certain operation with specific resource. It is an object implementing the Nette\Security\Authorizator interface with only one method isAllowed():

class MyAuthorizator implements Nette\Security\Authorizator
{
	public function isAllowed($role, $resource, $operation): bool
	{
		if ($role === 'admin') {
			return true;
		}
		if ($role === 'user' && $resour