From 5bd5df11e3d805f247b6b3a21ec472e90e6d35e7 Mon Sep 17 00:00:00 2001 From: Simon Rozsival Date: Thu, 12 Jan 2017 10:58:31 +0100 Subject: [PATCH] API analysis - architecture and authentication --- Rewritten-docs.md | 46 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 42 insertions(+), 4 deletions(-) diff --git a/Rewritten-docs.md b/Rewritten-docs.md index 17b84d6..3945848 100644 --- a/Rewritten-docs.md +++ b/Rewritten-docs.md @@ -208,7 +208,7 @@ System features represents directly accessible functionality to users of the system. They describe the evaluation system in general and also university addons (mostly administrative features). -#### Pure user requirements +#### Requirements of the users - users have their own account in the system - system users can be members of multiple groups (reflecting courses or labs) @@ -908,9 +908,47 @@ patterns used in this framework (e.g., dependency injection, authentication, routing). There is a good extension for the Nette framework which makes usage of Doctrine 2 very straightforward. -@todo: what database can be used, how it is mapped and used within code - -@todo: authentication, some possibilities and describe used jwt +#### Architecture of the system + +The Nette framework is an MVP (Model, View, Presenter) framework. It has many +tools for creating complex websites and we need only a subset of them or we use +different libraries which suite our purposes better: + +- **Model** - the model layer is implemented using the Doctrine 2 ORM insead of +Nette Database +- **View** - the whole view layer of the Nette framework (e.g., the Latte engine +used for HTML template rendering) is unnecessary since we will return all the +responses encoded in JSON. JSON is a common format used in APIs and we decided +to prefer it to XML or a custom format. +- **Presenter** - the whole lifecycle of a request processing of the Nette +framework is used. The Presenters are used to group the logic of the individual +API endpoints. The routing mechanism is modified to distinguish the actions by +both the URL and the HTTP method of the request. + +#### Authentication + +To make certain data and actions acessible only for some specific users, there +must be a way how these users can prove their identity. We decided to avoid +PHP sessions to make the server stateless (session ID is stored in the cookies +of the HTTP requests and responses). The server issues a specific token for the +user after his/her identity is verified (i.e., by providing email and password) +and sent to the client in the body of the HTTP response. The client must remember +this token and attach it to every following request in the *Authorization* header. + +The token must be valid only for a certain time period ("log out" the user after +a few hours of inactivity) and it must be protected against abuse (e.g., an attacker +must not be able to issue a token which will be considered valid by the system and +using which the attacker could pretend to be a different user). We decided to use +the JWT standard (the JWS). + +The JWT is a base64-encoded string which contains three JSON documents - a header, +some payload, and a signature. The interesting parts are the payload and the signature: +the payload can contain any data which can identify the user and metadata of the token +(i.e., the time when the token was issued, the time of expiration). The last part is a +digital signature contains a digital signature of the header and payload and it +ensures that nobody can issue their own token and steal someone's identity. Both of +these characteristics give us the opportunity to validate the token without storing +all of the tokens in the database. @todo: solution of forgotten password, why this in particular