few words on authentication

Web-API.md

@@ -62,7 +62,6 @@ public function actionCreateAccount() {
 }
 ```
 
-Authorization of users is based on validating his access token, which is obtained by users on successful login. This token has predefined validity period and has to be renewed before expiration to stay logged in. The token is sent to the API in HTTP Authorization header as value in format `Bearer <token>`. Requests with invalid or malformed token are treated as anonymous access with all its restrictions.
 
 The [Doctrine](https://github.com/Kdyby/Doctrine) 
 [ORM](https://en.wikipedia.org/wiki/Object-relational_mapping) framework is used 
@@ -73,6 +72,22 @@ documentation](http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/
 
 The API is capable of sending email messages. They can inform administrator about errors and users about submission evaluation or temporary link to change forgotten password. The [Nette Mail](https://doc.nette.org/en/2.4/mailing) extension provides nice interface for sending messages through external SMTP server (**preferred**) or builtin PHP function `mail`. It is important to set up the mailserver properly to ensure message delivery to the clients. The messages are rendered in HTML format via simple _Latte_ templates.
 
+### Authentication
+
+Instead of relying on PHP sessions, we decided to use an authentication flow 
+based on JWT tokens (RFC 7519). On successful login, the user is issued an 
+access token that they have to send with subsequent requests using the HTTP 
+Authorization header (`Authorization: Bearer <token>`). The token has a limited 
+validity period and has to be renewed periodically using a dedicated API 
+endpoint. 
+
+To implement this behavior in Nette framework, a new `IUserStorage` 
+implementation was created, along with an `IIdentity` and authenticators for 
+both our internal login service and CAS.
+
+An advantage of this approach is being able control the authentication process
+completely instead of just receiving session data through a global variable.
+
 ## Installation
 
 The web API requires a PHP runtime version at least 7. Which one depends on actual configuration, there is a choice between _mod_php_ inside Apache, _php-fpm_ with Apache or Nginx proxy or running it as standalone uWSGI script. Common thing is, that there are some PHP extensions, that have to be installed on the system. Namely ZeroMQ binding (`php-zmq` package or similar), MySQL module (`php-mysqlnd` package) and ldap extension module for CAS authentication (`php-ldap` package). Make sure that the extensions are loaded in your `php.ini` file (`/etc/php.ini` or files in `/etc/php.d/`).