Skip to content

Commit

Permalink
docs: introduce deployment & development guides
Browse files Browse the repository at this point in the history
Add one page covering deployment issues and one page covering
development.

The motivation of introducing these docs right now is to ensure
there's a place where the authentication scheme can be documented.
Other sections of the docs are light on detail at the moment.
  • Loading branch information
rohanpm committed Sep 10, 2020
1 parent 018228e commit 06458bd
Show file tree
Hide file tree
Showing 5 changed files with 122 additions and 7 deletions.
9 changes: 7 additions & 2 deletions docs/api-guide.rst
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,13 @@ For a full reference on the available endpoints, see:
Authentication
--------------

Authentication is currently unimplemented in exodus-gw; any clients with
access to the service can perform all operations.
The exodus-gw API does not include any direct support for authentication and is
instead expected to be deployed behind a reverse-proxy implementing any desired
authentication mechanism. Consult your organization's internal documentation for
authentication info for your specific exodus-gw installation.

See :ref:`deploy-guide` for more information on how to integrate an authentication
mechanism.


Uploading blobs
Expand Down
75 changes: 75 additions & 0 deletions docs/deployment.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
.. _deploy-guide:

Deployment Guide
================


Target platform
---------------

exodus-gw is an ASGI application which may be deployed using any ASGI-compliant
web server. The development team's recommended setup is summarized as:

- Use OpenShift >= 4.x to deploy the service.

- Use the exodus-gw images at https://quay.io/repository/exodus/exodus-gw to run
the service. These images run the service using gunicorn & uvicorn on RHEL8.

In general, the
`uvicorn deployment advice <https://www.uvicorn.org/deployment/>`_
applies.

- Deploy the service's primary container behind a reverse-proxy implementing
authentication according to your organization's needs (see next section).


Authentication & Authorization
------------------------------

The exodus-gw service does not implement any authentication mechanism. It is instead
designed to integrate with a reverse-proxy implementing any desired mechanism.

.. warning::
If exodus-gw is deployed without an authenticating reverse-proxy, the service must
be considered completely unsecured - all users will be able to perform all operations.

This reverse-proxy must add an ``X-RhApiPlatform-CallContext`` header onto all incoming
requests. This header must contain a base64-encoded form of the following JSON object:

.. code-block:: json
{
"client": {
"roles": ["someRole", "anotherRole"],
"authenticated": true,
"serviceAccountId": "clientappname"
},
"user": {
"roles": ["viewer"],
"authenticated": true,
"internalUsername": "someuser"
}
}
The ``roles`` and ``authenticated`` fields influence whether an exodus-gw request will be
permitted - the necessary roles are documented on relevant exodus-gw API endpoints.
Other fields are unused or used only for logging.

The separate ``client`` and ``user`` fields can be used to separate service accounts
(machine users) from human users, but this does not affect exodus-gw.

Within Red Hat, a container known as "platform-sidecar" is used as the reverse proxy - consult
internal documentation for information on this component. In other contexts, any reverse
proxy may be used as long as it produces headers according to the scheme documented above.


Settings
--------

.. autoclass:: exodus_gw.settings.Settings()
:members:

exodus-gw may be configured by the following settings.

Each settings value may be overridden using an environment variable of the
same name, prefixed with ``EXODUS_GW_`` (example: ``EXODUS_GW_CALL_CONTEXT_HEADER``).
34 changes: 34 additions & 0 deletions docs/development.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
.. _dev-guide:

Development Guide
=================

This document contains useful info for developers contributing
to the exodus-gw project.


Spoofing authentication
-----------------------

The exodus-gw service parses an ``X-RhApiPlatform-CallContext`` header for information
relating to authentication & authorization; see :ref:`deploy-guide` for more info on
this scheme.

During development, arbitrary values for this header may be used to test the
behavior of endpoints with various roles. However, due to the format of this header,
generating these values by hand can be cumbersome.

To assist in this, a helper script is provided in the exodus-gw repo at
``scripts/call-context``. This script accepts any number of role names as arguments
and produces a header value which will produce an authenticated & authorized request
using those roles.

For example, if we want to use ``curl`` to make a request to an endpoint needing
``qa-uploader`` role, we can use the following command:

.. code-block:: shell
curl \
-H "X-RhApiPlatform-CallContext: $(scripts/call-context qa-uploader)" \
http://localhost:8080/some/qa/endpoint
2 changes: 2 additions & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ Publishing microservice for Red Hat's Content Delivery Network.

api-guide
api
deployment
development

Overview
--------
Expand Down
9 changes: 4 additions & 5 deletions exodus_gw/settings.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,10 @@


class Settings(BaseSettings):
"""Settings for the server.
Each setting defined here can be overridden by an environment variable
of the same name, prefixed with "EXODUS_GW_".
"""
# Settings for the server.
#
# Each setting defined here can be overridden by an environment variable
# of the same name, prefixed with "EXODUS_GW_".

call_context_header: str = "X-RhApiPlatform-CallContext"
"""Name of the header from which to extract call context (for authentication
Expand Down

0 comments on commit 06458bd

Please sign in to comment.