The document propose a way of integration PAM into Ganeti RAPI in
order to support flexible authentification and authorization.
Signed-off-by: Oleg Ponomarev <oponoma...@google.com>
---
Makefile.am | 1 +
doc/design-optables.rst | 2 +
doc/design-rapi-pam.rst | 132 ++++++++++++++++++++++++++++++++++++++++++++++++
doc/index.rst | 1 +
doc/rapi.rst | 1 +
5 files changed, 137 insertions(+)
create mode 100644 doc/design-rapi-pam.rst
diff --git a/Makefile.am b/Makefile.am
index 0080f00..3c5c8ee 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -724,6 +724,7 @@ docinput = \
doc/design-query-splitting.rst \
doc/design-query2.rst \
doc/design-query-splitting.rst \
+ doc/design-rapi-pam.rst \
doc/design-reason-trail.rst \
doc/design-repaird.rst \
doc/design-reservations.rst \
diff --git a/doc/design-optables.rst b/doc/design-optables.rst
index 6c0c1e0..4c6599f 100644
--- a/doc/design-optables.rst
+++ b/doc/design-optables.rst
@@ -115,6 +115,8 @@ CONTINUE.
Filter chains are processed in increasing order of priority (lowest number
means highest priority), then watermark, then UUID.
+.. _filter-predicates:
+
Predicates available for the filter rules
-----------------------------------------
diff --git a/doc/design-rapi-pam.rst b/doc/design-rapi-pam.rst
new file mode 100644
index 0000000..b5bc5ed
--- /dev/null
+++ b/doc/design-rapi-pam.rst
@@ -0,0 +1,132 @@
+===============================================
+RAPI authentication and authorization using PAM
+===============================================
+
+.. contents:: :depth: 4
+
+This design document describes a way of :doc:`rapi` authentication
+and authorization refactoring by using pluggable authentication modules
+(PAM).
+
+Current State
+=============
+
+Currently :doc:`rapi` supports authentication using *basic* https
+protocol. The users are stored in a file (usually
+``/var/lib/ganeti/rapi/users``) and have either read or write rights.
+Please read :ref:`rapi-users` for more details.
+
+.. _motivation:
+
+Motivation
+==========
+
+During the GanetiCon 2015 the following features were requested by the
+community:
+
+- Support for different authentication methods;
+- Granular access to different RAPI command subsets;
+- Granular access to different target instances.
+
+The last two statements may be desired when an administrator wants to
+provide some restricted cluster or instance management rights for users.
+
+Proposed Implementation
+=======================
+
+Ganeti RAPI will use PAM for *authentication* and *account*
+(authorization) purposes. ``ganeti-basic`` PAM module performing
+*authentication* and *account* based on the contents of
+``ganeti/rapi/users`` file will be distributed with Ganeti. Ganeti rapi
+will interact with PAM using ``ganeti-rapi`` service name. The default
+configuration for ``ganeti-rapi`` PAM service will just use
+``ganeti-basic`` module.
+
+A good documentation on client-server PAM model is available
+at http://www.linux-pam.org/pre/doc/current-draft.txt.
+
+Authentication Specific Details
+-------------------------------
+
+In case of *basic* http authentication, the username and password will
+be extracted as they are presented in the
+:ref:`standard form <basic-protocol>`. Note, that independent from
+authentication method, all interactions will be performed via https
+protocol.
+
+In case of another authentication method, additional user's credintials
+(e.g. request signature) should be provided in
+``Ganeti-RAPI-Credential`` field. The field should be encoded using
+base64 algorithm as for the *basic* authentication.
+
+Ganeti will copy the username to ``PAM_USER`` field of a ``pam_handler``
+and the contents of ``Ganeti-RAPI-Credential`` http header fielf to
+``PAM_AUTHTOK`` field of a ``pam_handler``.
+
+User's password will be send as a reply to each request made by
+*conversation function* with ``PAM_PROMPT_ECHO_OFF`` message constant.
+Other requests will be just ignored.
+
+Authorization Specific Details
+------------------------------
+
+Ganeti will pass several parameters that might be useful for the
+*authorization* phase to the modules via the private PAM environmental
+variables (using ``pam_setenv``)
+
+GANETI_RAPI_URI
+ The requested URI.
+GANETI_REQUEST_BODY
+ The body of a request.
+
+One More Time About the Goals
+=============================
+
+Support for Different Authentication Methods
+--------------------------------------------
+
+The proposed solution allows to use signatures of any kind instead of
+user password or in addition to it. It allows an administrator to
+support more complex and secure authentication schemes than just a basic
+authentication.
+
+Granular Access to Different Command Subsets
+--------------------------------------------
+
+This functionality can be implemented just by writing more complex
+authorization module that will permit or deny execution of some command
+based on the environment variables passed and some additional config
+file.
+
+Granular Access to Different Target Instances
+---------------------------------------------
+
+For such kind of authorization, a PAM module may be implemented as
+well. The main difference is that for complex access rights maintaining
+the module will have to store users rights and lists of owned objects
+on some kind of dynamic database instead of simple static config file.
+
+Switching Between the Old and the New Implementations
+-----------------------------------------------------
+
+As the changes introduced should be backwards compatible, a new
+configure flag ``--enable_pam_rapi`` will be introduced.
+
+Other Changes
+=============
+
+As writing PAM module is an universal solution for the authorization
+problem, sometimes such flexibility is not necessary or not
+available because of disabled PAM. In that case it is still possible
+to provide granular access to the RAPI.
+
+For that purpose ``RAPI-Auth:username`` will be added to the reason
+trail just before sending a job for a further processing. That will
+allow to configure a filter that will reject job subsets initiated
+by some specific user i.e. add a user to a blacklist. See
+:doc:`design-optables` for more information about job filters.
+
+Another proposal is to introduce a new
+:ref:`filter predicate <filter-predicates>`, ``username`` that will
+contain the authenticated user's login and thus will make it possible to
+define an allowed user set for each operation.
diff --git a/doc/index.rst b/doc/index.rst
index a8b3fba..e5535eb 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -140,6 +140,7 @@ Draft designs
design-plain-redundancy.rst
design-query2.rst
design-query-splitting.rst
+ design-rapi-pam.rst
design-reason-trail.rst
design-repaird.rst
design-restricted-commands.rst
diff --git a/doc/rapi.rst b/doc/rapi.rst
index d6cab78..13533e5 100644
--- a/doc/rapi.rst
+++ b/doc/rapi.rst
@@ -107,6 +107,7 @@ Alternatively, the appropriate parameter of your HTTP client
In the current version ``ganeti-rapi``'s realm, ``Ganeti Remote
API``, can only be changed by modifying the source code.
+.. _basic-protocol:
Protocol
--------
--
2.6.0.rc2.230.g3dd15c0
