Teach users how to protect an endpoint: Add authentication… (#984)

Teach users how to protect an endpoint: Add authentication documentation

docs/developer/auth.rst

@@ -0,0 +1,92 @@
+******************
+Auth Documentation
+******************
+
+The authentication module (kytos.core.authentication) is a resource under
+development that provides a means of protection for REST endpoints.
+By using this resource, endpoints that are public by default,
+now require an authorization token to be accessed.
+
+All the authentication, token generation and configuration process is handled
+through the REST endpoints that are made available by default on
+kytos installation:
+
+This endpoint creates new users:
+
+.. code-block:: shell
+
+    POST http://127.0.0.1:8181/api/kytos/auth/users/
+
+    $ curl -X POST \
+        -H 'Content-Type: application/json' \
+        -d '{"username":"kytos",
+        "password":"your_password",
+        "email": "babel42@email.com"}' \
+        URL
+
+This endpoint verifies a user and returns a valid token if authentication
+is correct:
+
+.. code-block:: shell
+
+    GET http://127.0.0.1:8181/api/kytos/auth/login/
+
+    $ curl -X GET \
+        -H 'Accept:application/json' \
+        -H 'Authorization:Basic username:password' \
+        URL
+
+This endpoint lists the registered users:
+
+.. code-block:: shell
+
+    GET http://127.0.0.1:8181/api/kytos/auth/v1/users/
+
+    $ curl -X GET \
+        -H 'Accept:application/json' \
+        -H 'Authorization: Bearer ${TOKEN}' \
+        URL
+
+This endpoint gets details about a specific user:
+
+.. code-block:: shell
+
+    GET http://127.0.0.1:8181/api/kytos/auth/users/<user_id>/
+
+    $ curl -X GET \
+        -H 'Content-type: application/json' \
+        -H 'Accept: application/json' \
+        -H 'Authorization: Bearer ${TOKEN}' \
+        -d '{"user_id": "001"}' \
+        URL
+
+
+This endpoint deletes a specific user.
+
+.. code-block:: shell
+
+    DELETE http://127.0.0.1:8181/api/kytos/auth/v1/users/<user_id>/
+
+    $ curl -X DELETE \
+        -H 'Content-type: application/json' \
+        -H 'Accept: application/json' \
+        -H 'Authorization: Bearer ${TOKEN}' \
+        -d '{"user_id": "001"}' \
+        URL
+
+This endpoint update a specific user:
+
+.. code-block:: shell
+
+    PATCH http://127.0.0.1:8181/api/kytos/auth/v1/users/<user_id>/
+
+    $ curl -X PATCH \
+        -H 'Content-Type: application/json' \
+        -H 'Authorization: Bearer ${TOKEN}' \
+        -d '{"user_id": "001"}' \
+        URL
+
+
+The process to protect an endpoint is found in session `How to protect a NApp
+REST endpoint <https://docs.kytos.io/developer/creating_a_napp/>`_
+.

docs/developer/creating_a_napp.rst

@@ -102,27 +102,28 @@ If you want to create a new endpoint you should follow the steps below.
 
 - You need import the rest decorator method.
 - You need  declare a function using the rest decorator.
-- In the end of function you need return a string and the status code of your method.
+- In the end of function you need return a string and the status
+  code of your method.
 
 .. code-block:: python
 
   from flask import jsonify # import jsonify method to convert json to string
+  from kytos.core import KytosNapp, rest # import rest decorator method
+  from kytos.core import authenticated # import authenticated decorator method
 
-  from kytos.core.napps import rest #import rest decorator method
 
-  class Main(KytosNapps): # KytosNapps class
-
-    # all KytosNapps methods
-
-    # call the rest decorator to register your endpoint
-    @rest('sample_endpoint/<name>', methods=['GET'])
-    def my_endpoint(self, name):
-     """Sample of documentation.
+  class Main(KytosNapp):
+      # KytosNapps class
+      # all KytosNapps methods
+      # call the rest decorator to register your endpoint
+      @rest('sample_endpoint/<name>', methods=['GET'])
+      def my_endpoint(self, name):
+          """Sample of documentation.
+          Description for your method.
+          """
+          result = {"name": name}
+          return jsonify(result), 200  # return a string and http status code.
 
-     Description for your method.
-     """
-     result = {"name": name}
-     return jsonify(result), 200 # return a string and http status code
 
 When the kytos starts this napp will register an endpoint called
 `/api/<username>/<napp_name>/sample_endpoint/<name>` handling only **GET**
@@ -138,6 +139,131 @@ browser the result below, where `name` was given in the browser.
   }
 
 
+
+How to protect a NApp REST endpoint
+===================================
+
+
+By default, all the REST endpoints created with @rest decorator are public.
+To protect these endpoints is necessary to use an @authenticated decorator.
+This decorator is able to create an authentication and protection layer to
+endpoints, abstracting the complexity of using this functionality for developers.
+
+Initially, we recommend completing the tutorials:
+`Preparing the Development environment
+<https://docs.kytos.io/developer/setup_develop_environment/>`_ and
+`How to create a rest endpoint for you napp
+<https://docs.kytos.io/developer/creating_a_napp/#how-to-create-a-rest-endpoint-for-your-napp>`_
+.
+
+To use this resource you must complete the following steps:
+
+- Install an environment with kytos, kytos-utils,
+  python-openflow and storehouse NApp;
+- Create a user to access protected endpoints;
+- Import the authenticated decorator;
+- Secure the REST endpoints by using the @authenticated decorator.
+
+
+*Using this feature, endpoints marked as protected require
+the provision of a token to perform the requested operations*.
+
+Considering the environment is complete,
+the first step is create an authentication user. Run the following
+command in terminal to create it:
+
+.. code-block:: shell
+
+ (kytos-environment)$ kytosd -f -C
+
+ Username: <username>
+ Email: <email>
+ Password: <password>
+
+
+
+Now that the user has been created, import the authenticated decorator on NApp
+that you want to protect.
+
+
+.. code-block:: python
+
+  from flask import jsonify # import jsonify method to convert json to string
+  from kytos.core import KytosNapp, rest # import rest decorator method
+  from kytos.core import authenticated # import authenticated decorator method
+
+
+  class Main(KytosNapp):
+      # KytosNapps class
+      # all KytosNapps methods
+      # call the rest decorator to register your endpoint
+      @rest('sample_endpoint/<name>', methods=['GET'])
+      @authenticated
+      def my_endpoint(self, name):
+          """Sample of documentation.
+          Description for your method.
+          """
+          result = {"name": name}
+          return jsonify(result), 200  # return a string and http status code.
+
+
+Then, when this endpoint is accessed without sending a token,
+the following message will be seen:
+
+.. code-block:: json
+
+  {
+    "error": "Token not sent or expired"
+  }
+
+
+Now, to access this endpoint you must login with the created user credentials
+by submitting the username and password.
+
+.. code-block:: shell
+
+  GET http://0.0.0.0:8181/api/kytos/core/auth/login/
+
+  $ curl -X GET \
+    -H 'Accept: application/json' \
+    -H 'Authorization: Basic <username>: <password>' \
+    URL
+
+
+You will receive a token as response:
+
+.. code-block:: json
+
+  {
+   "token": "<token>"
+  }
+
+Finally, you can access the protected endpoint sending the token:
+
+.. code-block:: shell
+
+  GET http://0.0.0.0:8181/api/<username>/<napp_name>/sample_endpoint/<name>
+
+  $ curl -X GET \
+    -H 'Content-type: application/json' \
+    -H 'Accept: application/json' \
+    -H 'Authorization: Bearer ${TOKEN}' \
+    URL
+
+You will receive a token as response:
+
+.. code-block:: json
+
+  {
+    "name": "<name>"
+  }
+
+
+*REST requests can be made using a REST client.*
+
+
+
+
 How to document your API Rest
 =============================
 
@@ -287,7 +413,7 @@ worry if your NApp does not have this file.
 How the events works
 ====================
 
-With the purpose of performing the communication between NApps in the `Kytos Project` 
+With the purpose of performing the communication between NApps in the `Kytos Project`
 any NApp can send or receive events.
 
 Create Kytos Event
@@ -371,7 +497,7 @@ Create your Meta-NApp
 
 A Meta-NApp is a NApp that doesn't contain executable code, is used to specify
 dependencies of a given package and just installs and enables/disables a
-specific set of napps. 
+specific set of napps.
 
 To create your Meta-NApp, just like a common NApp, you need to use your
 napp-server name and insert some NApp information. The difference is just the
@@ -415,10 +541,12 @@ The basic Meta-NApp structure is described below.
        ├── kytos.json
        ├── README.rst
 
-- **kytos.json**: This is your Meta-NApp's main file, where the dependencies are defined.
-- **README.rst**: Main description and information about your Meta-NApp, ensure that it includes a brief description of the dependencies
+- **kytos.json**: This is your Meta-NApp's main file,
+  where the dependencies are defined.
+- **README.rst**: Main description and information about your Meta-NApp,
+  ensure that it includes a brief description of the dependencies
 
-How to create a basic NApp dependency 
+How to create a basic NApp dependency
 =====================================
 
 First, you have to edit the `kytos.json` and set the napp_dependencies field with

docs/developer/index.rst

@@ -86,6 +86,7 @@ Kytos Summit provides an opportunity for developers, contributors and other inte
    setup_develop_environment
    Kytos API <./kytos_api/kytos>
    creating_a_napp
+   auth
    how_to_contribute
    hacking
    security

docs/developer/intro.rst

@@ -14,6 +14,7 @@ In this section you will learn about:
 - :doc:`Preparing your Development Environment </developer/setup_develop_environment/>`
 - :doc:`Kytos API </developer/kytos_api/kytos>`
 - :doc:`How to develop your NApp </developer/creating_a_napp/>`
+- :doc:`Authentication Module </developer/auth/>`
 - :doc:`How to Contribute </developer/how_to_contribute/>`
 - :doc:`Hacking </developer/hacking/>`
 - :doc:`Security </developer/security/>`