Permissions

Rewritten-docs.md

@@ -1515,7 +1515,28 @@ exercise authors double-check what they upload to the fileserver and solutions
 to assignments can be uploaded in a single request, which makes it easy for the
 fileserver to create an archive of the solution files.
 
-@todo permission handling, roles, etc.
+#### Permissions
+
+In a system storing user data has to be implemented some kind of permission
+checking. Previous chapters implies, that each user has to have a role, which
+corresponds to his/her privileges. Our research showed, that three roles are
+sufficient -- student, supervisor and administrator. The user role has to be
+checked with every request. The good points is, that roles nicely match with
+granuality of API endpoints, so the permission checking can be done at the
+beginning of each request. That is implemented using PHP annotations, which
+allows to specify allowed user roles for each request with very little of code,
+but all the business logic is the same, together in one place.
+
+However, roles cannot cover all cases. For example, if user is a supervisor, it
+relates only to groups, where he/she is a supervisor. But using only roles
+allows him/her to act as supervisor in all groups in the system. Unfortunately,
+this cannot be easily fixed using some annotations, because there are many
+different cases when this problem occurs. To fix that, some additional checks
+can be performed at the beginning of request processing. Usually it is only one
+or two simple conditions.
+
+With this two concepts together it is possible to easily cover all cases of
+permission checking with quite a small amount of code.
 
 #### Solution loading