Create Kytos API Authentication blueprint

Create Kytos Auth blueprint

docs/blueprints/EP018.rst

@@ -0,0 +1,176 @@
+:EP: 18
+:Title: Kytos API Authentication definition.
+:Authors: Carlos Magno <cmagnobarbosa@gmail.com>; Gleyberson Andrade <gleybersonandrade@gmail.com>
+:Created: 2019-09-05
+:Kytos-Version: 2019.2
+:Status: Draft
+:Type: Standards Track
+
+Abstract
+========
+
+This blueprint specifies how Kytos should handle authentication and protection
+of NApps HTTP REST endpoints. We are proposing that this task is accomplished
+through a specific authentication module. This module will be responsible for
+restricting unauthorized users access, as well as providing endpoints for
+registered users management.
+
+The endpoint restriction request happens when a decorator is inserted, ensuring
+access to only authenticated users. This endpoint can be accessed through a
+token, generated by the module after the user authentication request. It is
+not the purpose of this module to take care of the authorization part
+(access level).
+
+Motivation
+==========
+
+Today, all NApps REST endpoints that are created through decorator @rest are
+publicly exposed, so unauthorized persons or applications who have access to
+these endpoints can change Napps behavior. If the developer want to restrict
+this access, the developer should implement their own authentication framework,
+which can result in security failures, code duplication and a high
+implementation cost.
+
+Rationale
+=========
+
+Security and simplicity are important in development. We need to secure some
+endpoints, hiding the complexity of configuring these authentication
+mechanisms from the NApp developer.
+
+This proposal provides an authentication mechanism to the NApp developer, so
+each developer doesn't have to create their own mechanism.
+
+Specification
+=============
+
+From the NApps developers' point of view, they keep using the decorator
+@rest('endpoint'). In this blueprint, we propose the addition of a new
+decorator, which determines whether the endpoint will be public or private.
+By default, the endpoint will be public. If users want to create a private
+endpoint, they must use the @authenticated decorator as shown:
+
+.. code:: python
+
+    from kytos.core.decorators import rest, authenticated
+    
+    @rest('endpoint')
+    @authenticated
+    def method():
+        ...
+
+With this change, it is important to note that if any NApp needs the
+"authenticated" decorator, it needs to import it.
+
+Authentication will be done by Basic Authentication, when users submit their
+username and password, they receive a token with a predefined due date. This
+can be implemented using the pyJWT library.
+
+Endpoints REST:
+---------------
+
+.. code:: http
+    
+    POST /api/kytos/auth/v1/users/ - This endpoint creates new users.
+
+    $ curl -X POST \
+        -H 'Content-Type: application/json' \
+        -d '{"username":"babel42", "password":"youshallnotpass", "email": "babel42@email.com"}' \
+        URL
+
+.. code:: http
+
+    GET /api/kytos/auth/v1/login/ - This endpoint verifies a user and returns a valid token if authentication is correct.
+
+    $ curl -X GET \
+        -H 'Accept:application/json' \
+        -H 'Authorization:Basic username:password' \
+        URL
+
+.. code:: http
+
+    GET /api/kytos/auth/v1/users/ - This endpoint lists the registered users.
+
+    $ curl -X GET \
+        -H 'Accept:application/json' \
+        -H 'Authorization: Bearer ${TOKEN}' \
+        URL
+
+.. code:: http
+
+    GET /api/kytos/auth/v1/users/<user_id>/ - This endpoint gets details about a specific user.
+
+    $ curl -X GET \
+        -H 'Content-type:application/json' \
+        -H 'Accept:application/json' \
+        -H 'Authorization: Bearer ${TOKEN}' \
+        -d '{"user_id":"001"}' \
+        URL
+
+.. code:: http
+
+    DELETE /api/kytos/auth/v1/users/<user_id>/ - This endpoint delete a specific user.	
+
+    $ curl -X DELETE \
+        -H 'Content-type:application/json' \
+        -H 'Accept:application/json' \
+        -H 'Authorization: Bearer ${TOKEN}' \
+        -d '{"user_id":"001"}' \
+        URL
+
+.. code:: http
+
+    PATCH /api/kytos/auth/v1/users/<user_id>/ - This endpoint update a specific user.
+
+    $ curl -X PATCH \
+        -H 'Content-Type: application/json' \
+        -H 'Authorization: Bearer ${TOKEN}' \
+        -d '{"user_id":"001"}' \
+        URL
+
+Backwards Compatibility
+=======================
+
+This proposal doesn’t modify the existing project semantic, except for the
+inclusion of a new authentication module in kytos/core, with a decorator whose
+purpose is to control the restriction of access to rest endpoints. This new
+functionality makes the following dependencies mandatory: pyJWT and Storehouse
+NApp.
+
+Security Implications
+=====================
+
+The malicious user can capture a valid victim token and make requests on their
+behalf. One solution is that all endpoints must have HTTPS.
+
+How to Teach This
+=================
+
+Documentation should be changed to include these new features:
+
+    - For endpoints constraints, instructions should be added teaching users how to use @authenticated decorator.
+
+    - To list, create, and delete users, instructions should be added teaching users how to use the public endpoints of the authentication module:
+
+        - POST /api/kytos/auth/v1/users/ - Create a user.
+        - GET /api/kytos/auth/v1/login/ -  Authenticate a user.
+        - GET /api/kytos/auth/v1/users/ - List all users.
+        - GET /api/kytos/auth/v1/users/<user_id>/ - List specific user.
+        - DELETE /api/kytos/auth/v1/users/<user_id>/ - Delete specific user.
+        - PATCH /api/kytos/auth/v1/users/<user_id>/ - Update specific user.
+
+Open Issues
+===========
+
+References
+==========
+
+- `Start Blueprint: Kytos API Authentication <https://github.com/kytos/kytos/issues/861>`_
+- `Create Kytos API Authentication blueprint <https://github.com/kytos/kytos/pull/955>`_
+- `pyJWT <https://pyjwt.readthedocs.io/en/latest/usage.html>`_
+
+Copyright
+=========
+
+This document is placed in the public domain or under the CC0-1.0-Universal
+license, whichever is more permissive.