: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: Finished
:Type: Standards Track

********************************************
EP018 - Kytos API Authentication definition.
********************************************

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:: console
    
    POST /api/kytos/core/auth/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:: console

    GET /api/kytos/core/auth/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:: console

    GET /api/kytos/core/auth/users/ - This endpoint lists the registered users.

    $ curl -X GET \
        -H 'Accept:application/json' \
        -H 'Authorization: Bearer ${TOKEN}' \
        URL

.. code:: console

    GET /api/kytos/core/auth/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:: console

    DELETE /api/kytos/core/auth/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:: console

    PATCH /api/kytos/core/auth/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/core/auth/users/ - Create a user.
        - GET /api/kytos/core/auth/login/ -  Authenticate a user.
        - GET /api/kytos/core/auth/users/ - List all users.
        - GET /api/kytos/core/auth/users/<user_id>/ - List specific user.
        - DELETE /api/kytos/core/auth/users/<user_id>/ - Delete specific user.
        - PATCH /api/kytos/core/auth/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.
