First iteration of authentication and security docs

This is a first iteration on basic security and authentication
documentation. It documents the security settings users might want to
pay attention to and explains how to configure them.

We're bumping the version of sphinx in order to enable the
"autosectionlabel" extension so we don't need to create explicit
labels for sections.

Change-Id: I694eb1a2aa03193335f11cbda40ed6962357c428

doc/source/conf.py

@@ -29,6 +29,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosectionlabel'
 ]
 
 # autodoc generation is a bit aggressive and a nuisance when doing heavy

doc/source/configuring.rst

@@ -28,6 +28,12 @@ For more details, click on the configuration parameters.
 +--------------------------------+------------------------------------------------------+------------------------------------------+
 | ARA_ENV_                       | Environment to load configuration for                | ``default``                              |
 +--------------------------------+------------------------------------------------------+------------------------------------------+
+| ARA_READ_LOGIN_REQUIRED_       | Whether authentication is required for reading data  | ``False``                                |
++--------------------------------+------------------------------------------------------+------------------------------------------+
+| ARA_WRITE_LOGIN_REQUIRED_      | Whether authentication is required for writing data  | ``False``                                |
++--------------------------------+------------------------------------------------------+------------------------------------------+
+| ARA_ENV_                       | Environment to load configuration for                | ``default``                              |
++--------------------------------+------------------------------------------------------+------------------------------------------+
 | ARA_LOG_LEVEL_                 | Log level of the different components                | ``INFO``                                 |
 +--------------------------------+------------------------------------------------------+------------------------------------------+
 | ARA_LOGGING_                   | Logging configuration                                | See ARA_LOGGING_                         |
@@ -139,6 +145,40 @@ In order to use the settings from the "dev" environment, you would set
 Another approach to environment-specific configuration is to use
 ``ARA_SETTINGS`` and keep your settings in different files instead.
 
+ARA_READ_LOGIN_REQUIRED
+~~~~~~~~~~~~~~~~~~~~~~~
+
+- **Environment variable**: ``ARA_READ_LOGIN_REQUIRED``
+- **Configuration file variable**: ``READ_LOGIN_REQUIRED``
+- **Type**: ``bool``
+- **Default**: ``False``
+- **Provided by**: `django-rest-framework permissions <https://www.django-rest-framework.org/api-guide/permissions>`_
+
+Determines if authentication is required before being authorized to query all
+API endpoints exposed by the server.
+
+There is no concept of granularity: users either have access to query
+everything or they don't.
+
+Enabling this feature first requires setting up :ref:`users <user management>`.
+
+ARA_WRITE_LOGIN_REQUIRED
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+- **Environment variable**: ``ARA_WRITE_LOGIN_REQUIRED``
+- **Configuration file variable**: ``WRITE_LOGIN_REQUIRED``
+- **Type**: ``bool``
+- **Default**: ``False``
+- **Provided by**: `django-rest-framework permissions <https://www.django-rest-framework.org/api-guide/permissions>`_
+
+Determines if authentication is required before being authorized to post data to
+all API endpoints exposed by the server.
+
+There is no concept of granularity: users either have access to query
+everything or they don't.
+
+Enabling this feature first requires setting up :ref:`users <user management>`.
+
 ARA_LOG_LEVEL
 ~~~~~~~~~~~~~
 

doc/source/index.rst

@@ -10,5 +10,6 @@ Table of Contents
 
     Installing ara-server <installing>
     Configuration settings and preferences <configuring>
+    Authentication and security <security>
     Using API clients with ara-server <using_api_clients>
     Architecture and workflows <arch>

doc/source/security.rst

@@ -0,0 +1,112 @@
+.. security:
+
+Authentication and security
+===========================
+
+ara-server ships with a default configuration that privileges simplicity and
+lets users get started quickly.
+
+By default:
+
+- A random SECRET_KEY will be generated once if none are supplied
+- No users are created
+- API authentication and permissions are not enabled
+- ALLOWED_HOSTS and CORS_ORIGIN_WHITELIST are configured for use on localhost
+
+These default settings can be configured according to the requirements of your
+deployments.
+
+Setting a custom secret key
+---------------------------
+
+By default, ara-server randomly generates a token for the :ref:`ARA_SECRET_KEY`
+setting if none have been supplied by the user.
+This value is persisted in the server configuration file in order to prevent
+the key from changing on every instanciation of the server.
+
+The default location for the server configuration file is
+``~/.ara/server/settings.yaml``.
+
+You can provide a custom secret key by supplying the ``ARA_SECRET_KEY``
+environment variable or by specifying the ``SECRET_KEY`` setting in your server
+configuration file.
+
+User management
+---------------
+
+ara-server leverages Django's `user management <https://docs.djangoproject.com/en/2.1/topics/auth/default/>`_
+but doesn't create any user by default.
+
+.. note::
+    Creating users does not enable authentication on the API.
+    In order to make authentication required for using the API, see `Enabling authentication for read or write access`_.
+
+In order to create users, you'll need to create a superuser account before
+running the API server::
+
+    $ ara-manage createsuperuser --username=joe --email=joe@example.com
+    Password:
+    Password (again):
+    Superuser created successfully.
+
+.. tip::
+    If you ever need to reset the password of a superuser account, this can be
+    done with the "changepassword" command::
+
+        $ ara-manage changepassword joe
+        Changing password for user 'joe'
+        Password:
+        Password (again):
+        Password changed successfully for user 'joe'
+
+Once the superuser has been created, make sure the API server is started and
+then login to the Django web administrative interface using the credentials
+you just set up.
+
+By default, you can start the API server with ``ara-manage runserver`` and
+access the admin interface at ``http://127.0.0.1:8000/admin/``.
+
+Log in to the admin interface:
+
+.. image:: _static/admin_panel_login.png
+
+Access the authentication and authorization configuration:
+
+.. image:: _static/admin_panel_auth.png
+
+And from here, you can manage existing users or create new ones:
+
+.. image:: _static/admin_panel_users.png
+
+Enabling authentication for read or write access
+------------------------------------------------
+
+Once you have created your users, you can enable authentication against the API
+for read (ex: GET) and write (ex: DELETE, POST, PATCH) requests.
+
+This is done with the two following configuration options:
+
+- :ref:`ARA_READ_LOGIN_REQUIRED` for read access
+- :ref:`ARA_WRITE_LOGIN_REQUIRED` for write access
+
+These settings are global and are effective for all API endpoints.
+
+Managing hosts allowed to serve the API
+---------------------------------------
+
+By default, :ref:`ARA_ALLOWED_HOSTS` authorizes ``localhost``, ``::1`` and
+``127.0.0.1`` to serve requests for the API server.
+
+In order to host an instance of ara-server on another domain, the domain must
+be part of this list or the application server will deny any requests sent to
+it.
+
+Managing CORS (cross-origin resource sharing)
+---------------------------------------------
+
+The :ref:`ARA_CORS_ORIGIN_WHITELIST` default is designed to allow a local development
+instance of an `ara-web <https://github.com/openstack/ara-web>`_ dashboard to
+communicate with a local development instance of ara-server.
+
+The whitelist must contain the domain names where you plan on hosting instances
+of ara-web.

test-requirements.txt

@@ -2,7 +2,7 @@ factory-boy
 bandit>=1.1.0 # Apache-2.0
 coverage
 flake8
-sphinx!=1.2.0,!=1.3b1,<1.3,>=1.1.2
+sphinx>=1.4
 sphinx-rtd-theme
 black==18.9b0 ; python_version >= '3.6' # Exact version for prerelease
 isort