The document propose the way of integration PAM into Ganeti RAPI in order to support flexible authentification and authorization.
Signed-off-by: Oleg Ponomarev <[email protected]> --- Makefile.am | 1 + doc/design-optables.rst | 2 + doc/design-rapi-pam.rst | 134 ++++++++++++++++++++++++++++++++++++++++++++++++ doc/index.rst | 1 + doc/rapi.rst | 1 + 5 files changed, 139 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..340eaa4 --- /dev/null +++ b/doc/design-rapi-pam.rst @@ -0,0 +1,134 @@ +=============================================== +RAPI authentication and authorization using PAM +=============================================== + +.. contents:: :depth: 4 + +This document describes the proposed 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 (e.g. X.509); +- 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. In order to preserve backwards compability, +``ganeti-basic`` PAM module performing *authentication* and *account* +based on the contents of ``ganeti/rapi/users`` file. 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>`. + +In case of other authentication method, additional user's credintials +(e.g. rsa key) should be provided in ``Ganeti-RAPI-Credential`` field. +The field should be encoded using base64 algorithm as for the base +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 +============================= + +Below the way in which proposed solution help to reach the goals +specified in the :ref:`motivation section <motivation>`. + +Support for Different Authentication Methods +-------------------------------------------- + +Any 1 phase authentication method can be implemented using the proposed +implementation. For most cases it'll be even not necessary to write a +new PAM module because there are already lots of PAM modules that +support different authentication methods. The RAPI *applicant* will +only have to include the corresponding credentials into a http header. + +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, new configure +flag ``--enable_pam_rapi`` will be introduced. + +Other Changes +============= + +As writing PAM module can be the most universal solution for the +authorization, sometimes such flexibility is not necessary or not +available because of disabled PAM. In that case there 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 job for further processing. That will allow +to configure a filter that will reject all the jobs of some kind +initiated by some specific user i.e. add a user to a blacklist. +See :doc:`design-optables` for more information about filters. + +Other proposal is to introduce a new +:ref:`filter predicate <filter-predicates>`, ``username`` that will be +equal to the authenticated user name and thus will make it possible to +define a set of allowed users 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
