Authenticating Users
Little to none web applications need no mechanism for user login or checking user privileges. In this chapter, we'll talk about:
- user login and logout
- custom authenticators and authorizators
→ Installation and requirements
In the examples, we will use an object of class Nette\Security\User, which represents the current user
and which you get by passing it using dependency
injection. In presenters simply call $user = $this->getUser()
.
In version 3.0 the interfaces still had the I
prefix, so the names were
Nette\Security\IUserStorage
, IAuthenticator
and IAuthorizer
etc. Furthermore, the
Nette\Security\SimpleIdentity
class was called Nette\Security\dentity
.
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.');
}
This is how to log out the user:
$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.
In presenter, you can verify login in the startup()
method and redirect a non-logged-in user to the
login page.
protected function startup()
{
parent::startup();
if (!$this->getUser()->isLoggedIn()) {
$this->redirect('Sign:in');
}
}
Expiration
The user login expires along with expiration of repository, which is usually a
session (see the session expiration setting). However,
you can also set a shorter time interval after which the user is logged out. The setExpiration()
method, which is
called before login()
, is used for this purpose. Provide a string with a relative time as a parameter:
// login expires after 30 minutes of inactivity
$user->setExpiration('30 minutes');
// cancel set expiration
$user->setExpiration(null);
The $user->getLogoutReason()
method tells if the user has been logged out because the time interval has
expired. It returns either the constant Nette\Security\UserStorage::LOGOUT_INACTIVITY
if the time expired or
UserStorage::LOGOUT_MANUAL
when the logout()
method was called.
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 in configuration:
security:
users:
# 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;
use Nette\Security\SimpleIdentity;
class MyAuthenticator implements Nette\Security\Authenticator
{
private $database;
private $passwords;
public function __construct(
Nette\Database\Explorer $database,
Nette\Security\Passwords $passwords
) {
$this->database = $database;
$this->passwords = $passwords;
}
public function authenticate(string $username, string $password): SimpleIdentity
{
$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 SimpleIdentity(
$row->id,
$row->role, // or array of roles
['name' => $row->username]
);
}
}
Note: The interface was different in version 3.0:
use Nette;
class MyAuthenticator implements Nette\Security\IAuthenticator
{
public function authenticate(array $credentials): Nette\Security\IIdentity
{
[$username, $password] = $credentials;
// ...
return new Nette\Security\Identity(
$row->id,
$row->role, // nebo pole více rolí
['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).
We will add the authenticator to the configuration as a service of the DI container:
services:
- MyAuthenticator
$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 using $user->logout()
, 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 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.
Storage for Logged User
The two basic pieces of information about the user, i.e., whether they are logged in and their identity, are usually carried in the session. Which can be changed. For storing this information is
responsible an object implementing the Nette\Security\UserStorage
interface. There are two standard implementations,
the first transmits data in a session and the second in a cookie. These are the
Nette\Bridges\SecurityHttp\SessionStorage
and CookieStorage
classes. You can choose the storage and
configure it very conveniently in configuration security ›
authentication.
You can also control exactly how identity saving (sleep) and restoring (wakeup) will take place. All you need is
for the authenticator to implement the Nette\Security\IdentityHandler
interface. This has two methods:
sleepIdentity()
is called before the identity is written to storage, and wakeupIdentity()
is called
after the identity is read. The methods can modify the contents of the identity, or replace it with a new object that returns. The
wakeupIdentity()
method may even return null
, which logs the user out.
As an example, we will show a solution to a common question on how to update identity roles right after restoring from a
session. In the method wakeupIdentity()
we pass the current roles to the identity, eg from the database:
final class Authenticator implements
Nette\Security\Authenticator, Nette\Security\IdentityHandler
{
public function sleepIdentity(IIdentity $identity): IIdentity
{
// here you can change the identity before storing after logging in,
// but we don't need that now
return $identity;
}
public function wakeupIdentity(IIdentity $identity): ?IIdentity
{
// updating roles in identity
$userId = $identity->getId();
$identity->setRoles($this->facade->getUserRoles($userId));
return $identity;
}
And now we return to the cookie-based storage. It allows you to create a website where users can log in without the need to use
sessions. So it does not need to write to disk. After all, this is how the website you are now reading works, including the forum.
In this case, the implementation of IdentityHandler
is a necessity. We will only store a random token representing
the logged user in the cookie.
So first we set the desired storage in the configuration using
security › authentication › storage: cookie
.
We will add a column authtoken
in the database, in which each user will have a completely random, unique and unguessable string of sufficient length (at
least 13 characters). The repository CookieStorage
stores only the value $identity->getId()
in the
cookie, so in sleepIdentity()
we replace the original identity with a proxy with authtoken
in the ID, on
the contrary in the method wakeupIdentity()
we restore whole identity from the database according authtoken:
final class Authenticator implements
Nette\Security\Authenticator, Nette\Security\IdentityHandler
{
public function authenticate(string $username, string $password): SimpleIdentity
{
$row = $this->db->fetch('SELECT * FROM user WHERE username = ?', $username);
// check password
...
// we return the identity with all the data from the database
return new SimpleIdentity($row->id, null, (array) $row);
}
public function sleepIdentity(IIdentity $identity): SimpleIdentity
{
// we return a proxy identity, where in the ID is authtoken
return new SimpleIdentity($identity->authtoken);
}
public function wakeupIdentity(IIdentity $identity): ?SimpleIdentity
{
// replace the proxy identity with a full identity, as in authenticate()
$row = $this->db->fetch('SELECT * FROM user WHERE authtoken = ?', $identity->getId());
return $row
? new SimpleIdentity($row->id, null, (array) $row)
: null;
}
}
Multiple Independent Authentications
It is possible to have several independent logged users within one site and one session at a time. For example, if we want to have separate authentication for frontend and backend, we will just set a unique session namespace for each of them:
$user->getStorage()->setNamespace('backend');
It's necessary to keep in mind that this must be set at all places belonging to the same segment. When using presenters, we will set the namespace in the common ancestor – usually the BasePresenter. In order to do so we will extend the checkRequirements() method:
public function checkRequirements($element): void
{
$this->getUser()->getStorage()->setNamespace('backend');
parent::checkRequirements($element);
}
Multiple Authenticators
Dividing an application into segments with independent authentication generally requires different authenticators. However,
registering two classes that implement Authenticator into config services would trigger an error because Nette wouldn't know which
of them should be autowired to the
Nette\Security\User
object. Which is why we must limit autowiring for them with autowired: self
so that
it's activated only when their class is specifically requested:
services:
-
create: FrontAuthenticator
autowired: self
class SignPresenter extends Nette\Application\UI\Presenter
{
/** @var FrontAuthenticator */
private $authenticator;
public function __construct(FrontAuthenticator $authenticator)
{
$this->authenticator = $authenticator;
}
}
We only need to set our authenticator to the User object before calling method login() which typically means in the login form callback:
$form->onSuccess[] = function (Form $form, \stdClass $data) {
$user = $this->getUser();
$user->setAuthenticator($this->authenticator);
$user->login($data->username, $data->password);
// ...
};