Authenticating Users
********************

<div class=perex>

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

</div>

→ [Installation and requirements |@home#Installation]

In the examples, we will use an object of class [api:Nette\Security\User], which represents the current user and which you get by passing it using [dependency injection |dependency-injection:passing-dependencies]. In presenters simply call `$user = $this->getUser()`.


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`.

```php
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:

```php
$user->logout();
```

And checking if user is logged in:

```php
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.

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


Expiration
==========

The user login expires along with [expiration of repository|#Storage for Logged User], which is usually a session (see the [session expiration|http:configuration#session] 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:

```php
// 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::LogoutInactivity` if the time expired or `UserStorage::LogoutManual` 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 [api:Nette\Security\SimpleAuthenticator], which can be defined in [configuration]:

```neon
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 [api: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::IdentityNotFound` or `Authenticator::InvalidCredential`.

```php
use Nette;
use Nette\Security\SimpleIdentity;

class MyAuthenticator implements Nette\Security\Authenticator
{
	public function __construct(
		private Nette\Database\Explorer $database,
		private Nette\Security\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],
		);
	}
}
```

The MyAuthenticator class communicates with the database through [Nette Database Explorer |database:explorer] and works with table `users`, where column `username` contains the user's login name and column `password` contains [hash|passwords]. 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 |#roles], and an array with additional data (in our case, the username).

We will add the authenticator to the configuration [as a service |dependency-injection:services] of the DI container:

```neon
services:
	- MyAuthenticator
```


$onLoggedIn, $onLoggedOut Events
--------------------------------

Object `Nette\Security\User` has [events|nette:glossary#Events] `$onLoggedIn` and `$onLoggedOut`, so you can add callbacks that are triggered after a successful login or after the user logs out.


```php
$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:

```php
$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 [api:Nette\Security\IIdentity] interface, the default implementation is [api: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|configuration].

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:

```php
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|utils:random] 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:

```php
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:

```php
$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() |api:Nette\Application\UI\Presenter::checkRequirements()] method:

```php
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 |dependency-injection:autowiring] 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:

```neon
services:
	-
		create: FrontAuthenticator
		autowired: self
```

```php
class SignPresenter extends Nette\Application\UI\Presenter
{
	public function __construct(
		private FrontAuthenticator $authenticator,
	) {
	}
}
```

We only need to set our authenticator to the User object before calling method [login() |api:Nette\Security\User::login()] which typically means in the login form callback:

```php
$form->onSuccess[] = function (Form $form, \stdClass $data) {
	$user = $this->getUser();
	$user->setAuthenticator($this->authenticator);
	$user->login($data->username, $data->password);
	// ...
};
```