This is an automated email from the git hooks/post-receive script. x2go pushed a change to branch master in repository x2gobroker. from 4558970 Copyright: Happy (new) year 2018 (belated). new b7590e7 x2gobroker.authmechs: Write API documentation. new 932baa6 x2gobroker.authmechs: Add FIXME about non-working~ inheritance among authmech classes. new 6899764 docs/source/conf.py: Switch to Sphinx theme 'haiku' if Sphinx >= 1.0 is available at build time. new 28cdc49 docs/source:index.rst: Write an introduction text for the API documentation. new 03ffe64 x2gbroker/_paramiko.py: Grammar fix in __doc__ string. new e1e8429 x2gobroker.authservice: Document Auth Service client's authenticate() function. The 6 revisions listed above as "new" are entirely new to this repository and will be described in separate emails. The revisions listed as "adds" were already present in the repository and have only been added to this reference. Summary of changes: docs/source/conf.py | 4 +- docs/source/index.rst | 99 ++++++++++++++++++++++++++++-- x2gobroker/_paramiko.py | 2 +- x2gobroker/authmechs/__init__.py | 1 - x2gobroker/authmechs/base_authmech.py | 31 ++++++++++ x2gobroker/authmechs/https_get_authmech.py | 52 ++++++++++++++++ x2gobroker/authmechs/none_authmech.py | 29 +++++++++ x2gobroker/authmechs/pam_authmech.py | 46 ++++++++++++++ x2gobroker/authmechs/testsuite_authmech.py | 25 ++++++++ x2gobroker/authservice.py | 30 +++++++++ 10 files changed, 309 insertions(+), 10 deletions(-) -- Alioth's /home/x2go-admin/maintenancescripts/git/hooks/post-receive-email on /srv/git/code.x2go.org/x2gobroker.git
This is an automated email from the git hooks/post-receive script. x2go pushed a commit to branch master in repository x2gobroker. commit b7590e7f140fd9e531060bf1eda778d180856934 Author: Mike Gabriel <mike.gabriel@das-netzwerkteam.de> Date: Tue Sep 11 15:00:56 2018 +0200 x2gobroker.authmechs: Write API documentation. --- x2gobroker/authmechs/__init__.py | 1 - x2gobroker/authmechs/base_authmech.py | 24 ++++++++++++++ x2gobroker/authmechs/https_get_authmech.py | 52 ++++++++++++++++++++++++++++++ x2gobroker/authmechs/none_authmech.py | 29 +++++++++++++++++ x2gobroker/authmechs/pam_authmech.py | 46 ++++++++++++++++++++++++++ x2gobroker/authmechs/testsuite_authmech.py | 25 ++++++++++++++ 6 files changed, 176 insertions(+), 1 deletion(-) diff --git a/x2gobroker/authmechs/__init__.py b/x2gobroker/authmechs/__init__.py index 6c377e8..0d89658 100644 --- a/x2gobroker/authmechs/__init__.py +++ b/x2gobroker/authmechs/__init__.py @@ -16,4 +16,3 @@ # along with this program; if not, write to the # Free Software Foundation, Inc., # 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. - diff --git a/x2gobroker/authmechs/base_authmech.py b/x2gobroker/authmechs/base_authmech.py index e1cda02..dd6c667 100644 --- a/x2gobroker/authmechs/base_authmech.py +++ b/x2gobroker/authmechs/base_authmech.py @@ -18,6 +18,30 @@ # 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. class X2GoBrokerAuthMech(object): + """\ + Base *authentication mechanism* class. This class is not supposed to + be used as an authentication mechanism in running setups. (It let's + authentication always fail). + + It is rather so, that more specific authentication mechanisms should + inherit from this class. All features common to more specific + authentication mechanisms go in here. + """ def authenticate(self, username, password, **kwargs): + """\ + Dummy :func:`authenticate()` method of :class:`X2GoBrokerAuthMech`. + + :param username: The broker username sent by the client (ignored) + :type username: ``str`` + :param password: The broker password sent by the client (ignored) + :type password: ``str`` + :param kwargs: Any other parameter (for future features' compatibility, all ignored for now) + :type kwargs: ``dict`` + + :returns: Authentication failure (always!) + :rtype: ``bool`` + + + """ return False diff --git a/x2gobroker/authmechs/https_get_authmech.py b/x2gobroker/authmechs/https_get_authmech.py index fbba640..6e01ddf 100644 --- a/x2gobroker/authmechs/https_get_authmech.py +++ b/x2gobroker/authmechs/https_get_authmech.py @@ -35,8 +35,60 @@ import http.client import base64 class X2GoBrokerAuthMech(object): + """\ + + X2Go Session Broker's **https_get** *authentication mechanism*: + + This authentication mechanism can be attached to a web server + that provides some test URL protected by http(s) Basic + Authentication. + + When the :func:`authenticate()` function gets called, it attempts + to retrieve the test URL via a http(s) GET request. The webserver + serving that URL then sends a response back, demanding + ``Authorization``. + + For the Basic Authorization request that gets sent back to the + webserver, the username and password provided by the X2Go client + application get used. + + """ def authenticate(self, username, password, config=None, **kwargs): + """\ + The **https_get** authentication mechanism's :func:`authenticate()` + method attempts authentication against a http(s) server. + + It lets broker authentication succeed if the upstream webserver + grants authentication to a given test URL. Otherwise, broker + authencation fails. + + The test URL is provided as set of config parameters passed in + via the ``config`` function parameter. If no config is given, the + default authentication will be performed against + ``http://localhost/auth``. + + The configuration object provided as ``config`` to this method + requires to understand this API (a class from module + :mod:`configparser` should do this for you):: + + host = config.get_value('authmech_https_get','host') + path = config.get_value('authmech_https_get','path') + port = config.get_value('authmech_https_get','port') + + :param username: The broker username sent by the client + :type username: ``str`` + :param password: The broker password sent by the client + :type password: ``str`` + :param config: A :mod:`configparser` compliant configuration object + :param type: ``<configparser-like-obj>`` + :param kwargs: Any other parameter (for future features' compatibility, all ignored for now) + :type kwargs: ``dict`` + + :returns: Authentication success or failure. + :rtype: ``bool`` + + """ ## FIXME: these should really be specificed in master config file and have better error checking diff --git a/x2gobroker/authmechs/none_authmech.py b/x2gobroker/authmechs/none_authmech.py index 9110e07..f4ce316 100644 --- a/x2gobroker/authmechs/none_authmech.py +++ b/x2gobroker/authmechs/none_authmech.py @@ -18,6 +18,35 @@ # 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. class X2GoBrokerAuthMech(object): + """\ + + X2Go Session Broker's **none** *authentication mechanism*: + + Use this *authentication mechanism* for setups, where users are always + granted access to the broker. No authentication is required. + + **WARNING:** Only use this authentication mechanism on private or VPN'ed + networks. Don't use it, if your broker is reachable on the internet or in + networks with non-trusted hosts. + + **NOTE:** The broker will not be able to distinguish between users when delivering + available servers and session to the user's X2Go Client application. + """ def authenticate(self, username, password, **kwargs): + """\ + The **none** authentication mechanism's :func:`authenticate()` method always + returns ``True`` to the user, so X2Go Session Broker access gets always granted. + + :param username: The broker username sent by the client (ignored) + :type username: ``str`` + :param password: The broker password sent by the client (ignored) + :type password: ``str`` + :param kwargs: Any other parameter (for future features' compatibility, all ignored for now) + :type kwargs: ``dict`` + + :returns: Authentication success (always!) + :rtype: ``bool`` + + """ return True diff --git a/x2gobroker/authmechs/pam_authmech.py b/x2gobroker/authmechs/pam_authmech.py index 5dea596..7fa0e30 100644 --- a/x2gobroker/authmechs/pam_authmech.py +++ b/x2gobroker/authmechs/pam_authmech.py @@ -27,8 +27,54 @@ import x2gobroker.authservice from x2gobroker.loggers import logger_error class X2GoBrokerAuthMech(object): + """\ + + X2Go Session Broker's **PAM** *authentication mechanism*: + + This is the most commonly used and most flexible authentication + mechanism in X2Go Session Broker. You can run the full scope of + PAM authentication mechanisms (POSIX, LDAP, Kerberos, etc.) over + it. + + **NOTE:** You can fine-tune PAM's authentication backends in the + corresponding PAM service file ``/etc/pam.d/x2gobroker``. + + **WARNING:** The PAM authentication mechanism requires an extra + X2Go Session Broker tool: the X2Go Session Broker's + Authentication Service. Reason: Some PAM authentication + modules (e.g. ``pam_unix.so``) require root privileges during the + authentication process. The X2Go Session Broker's Auth Service + runs with these root privileges and provides a communication socket to + the X2Go Session Broker where authentication requests are proxied + over. + + If you don't need root privileges for PAM authentication (e.g. + LDAP), simply don't run the X2Go Broker Auth Service and + authentication against PAM are done directly by the session + broker as system user ``x2gobroker``. + """ def authenticate(self, username, password, **kwargs): + """\ + The **PAM** authentication mechanism's :func:`authenticate()` + tries to proxy authentication through X2Go Session Broker's Auth + Service first and, if that fails, attempts another authentication + against PAM directly (which fails for some PAM modules). + + It returns ``True`` to the user, if authentication against PAM + has been successful. + + :param username: The broker username sent by the client + :type username: ``str`` + :param password: The broker password sent by the client + :type password: ``str`` + :param kwargs: Any other parameter (for future features' compatibility, all ignored for now) + :type kwargs: ``dict`` + + :returns: Authentication success or failure. + :rtype: ``bool`` + + """ if username and password: try: diff --git a/x2gobroker/authmechs/testsuite_authmech.py b/x2gobroker/authmechs/testsuite_authmech.py index 47272ec..d3b2a7a 100644 --- a/x2gobroker/authmechs/testsuite_authmech.py +++ b/x2gobroker/authmechs/testsuite_authmech.py @@ -18,8 +18,33 @@ # 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. class X2GoBrokerAuthMech(object): + """\ + Unit testing *authentication mechanism* class. Used internally for + running unit tests of the :mod:`x2gobroker` module's code base. + + Don't use this!!! + + """ def authenticate(self, username, password, **kwargs): + """ + Test function, faking sucessful authentication for user ``test`` + with password ``sweet`` and user ``jacques`` with accentuated + characters in the password ``thérèse``. + + Don't use this!!! + + :param username: The broker username sent by the client (ignored) + :type username: ``str`` + :param password: The broker password sent by the client (ignored) + :type password: ``str`` + :param kwargs: Any other parameter (for future features' compatibility, all ignored for now) + :type kwargs: ``dict`` + + :returns: Authentication failure (always!) + :rtype: ``bool`` + + """ # return ``True`` for user test with password sweet... (used by the unit tests) if username == 'test' and password == 'sweet': -- Alioth's /home/x2go-admin/maintenancescripts/git/hooks/post-receive-email on /srv/git/code.x2go.org/x2gobroker.git
This is an automated email from the git hooks/post-receive script. x2go pushed a commit to branch master in repository x2gobroker. commit 932baa66fe7edefcca6e87f4923f9340bef31409 Author: Mike Gabriel <mike.gabriel@das-netzwerkteam.de> Date: Tue Sep 11 15:42:45 2018 +0200 x2gobroker.authmechs: Add FIXME about non-working~ inheritance among authmech classes. --- x2gobroker/authmechs/base_authmech.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/x2gobroker/authmechs/base_authmech.py b/x2gobroker/authmechs/base_authmech.py index dd6c667..2973e23 100644 --- a/x2gobroker/authmechs/base_authmech.py +++ b/x2gobroker/authmechs/base_authmech.py @@ -28,6 +28,13 @@ class X2GoBrokerAuthMech(object): authentication mechanisms go in here. """ + ### FIXME: Currently we don't let the other authmech classes inherit + # from this class. Technically, this is ok as we override everything in + # here in the sub-classes anyway. However, this should be fixed... + # + # E.g. the unit tests fail if tests.X2GoBrokerAuthMech inherits from + # base.X2GoBrokerAuthMech. This needs some investigation. + def authenticate(self, username, password, **kwargs): """\ Dummy :func:`authenticate()` method of :class:`X2GoBrokerAuthMech`. -- Alioth's /home/x2go-admin/maintenancescripts/git/hooks/post-receive-email on /srv/git/code.x2go.org/x2gobroker.git
This is an automated email from the git hooks/post-receive script. x2go pushed a commit to branch master in repository x2gobroker. commit 68997642726a4d7f9bfa75b694060eb10d1705b9 Author: Mike Gabriel <mike.gabriel@das-netzwerkteam.de> Date: Tue Sep 11 16:21:25 2018 +0200 docs/source/conf.py: Switch to Sphinx theme 'haiku' if Sphinx >= 1.0 is available at build time. --- docs/source/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 498883c..b896e24 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -133,9 +133,9 @@ todo_include_todos = True # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -sphinx_want_ver = distutils.version.LooseVersion('1.3') +sphinx_want_ver = distutils.version.LooseVersion('1.0') if sphinxver >= sphinx_want_ver: - html_theme = 'classic' + html_theme = 'haiku' else: html_theme = 'default' -- Alioth's /home/x2go-admin/maintenancescripts/git/hooks/post-receive-email on /srv/git/code.x2go.org/x2gobroker.git
This is an automated email from the git hooks/post-receive script. x2go pushed a commit to branch master in repository x2gobroker. commit 28cdc4902e5675342518459359a29ba55fdd5f31 Author: Mike Gabriel <mike.gabriel@das-netzwerkteam.de> Date: Tue Sep 11 16:21:42 2018 +0200 docs/source:index.rst: Write an introduction text for the API documentation. --- docs/source/index.rst | 99 +++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 93 insertions(+), 6 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index e35fb50..954df7c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,15 +3,103 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to X2Go Session Broker's documentation! -=============================================== +Welcome to X2Go Session Broker's Documentation +============================================== -Contents: +Brokerage for X2Go is the add-on feature that turns X2Go into a site-wide +configurable desktop solution. With brokerage support, site-admins can... -.. toctree:: - :maxdepth: 2 + * provision X2Go client session profiles on-the-fly via one or more central + broker servers + * provision X2Go client session profiles based on user and/or group privileges + * hook X2Go client into non-PAM, non-SSH authentication mechanisms + * let X2Go users resume suspended sessions on X2Go server farms + * etc. + +There are many X2Go broker implementations out there, mostly running in +commercial production environments. Mostly highly customized for the +customer that ordered such a broker. + +The official **X2Go Session Broker** is the attempt of providing X2Go users +with a generically configurable X2Go broker that is easy to administrate. + +This API documentation is about Python X2GoBroker. Python X2GoBroker is +the brainy backend behind X2Go Session Broker. The goal of this API +documentation is to provide enough information for you to allow you +customizing X2Go Session Broker to your needs and also possibly +contribute your code back to the X2Go developers' community. + +With this broker approach, we attempt at providing + + (a) a free and quickly-to-use broker for X2Go + (b) an easy-to-extend piece of Python software that allows + site admins and/or developers to adapt the current code + base to their specific use cases + (c) a brokerage solution hat can be used in production environments + +The Concept +----------- + +In standalone setups, an X2Go client application knows the session +profiles that the user configure locally (in a file named +``~/.x2goclient/sessions`` (or in the Windows registry, for *X2Go Client +for Windows*). + +In brokerage setups, there is one (or more) server(s) that tell the X2Go +client application what X2Go servers and session types are available on +the corporate network. + +The **authentication** to an X2Go sessions falls into two parts: + + (1) authentication against the X2Go Session Broker + (2) authentication against the X2Go Server (where the remote session will be run) + +This authentication split-up adds an extra authentication step that we +try to reduce by providing the so-calls broker autologon feature. An X2Go +client that could successfully authenticate against an X2Go Session +Broker is legitimate to launch an X2Go session on attached X2Go servers. +So, the second authentication step (to the actual X2Go Server) can be +handled by the broker internally. + +To achieve this, the X2Go Session Broker requires a tool on each attached +X2Go server, the so called **X2Go Broker Agent**. X2Go Session Broker can +ask the X2Go Broker Agent to perform several tasks: + * temporarily deploy public SSH user keys + * query X2Go server load factors + * check, if a remote X2Go server is actually available for login + (Down for maintenance? Maximum number of users already reached?) + * query the attached servers, if logging-in broker user already has + a running (or suspended) session + * do some extra checks on X2Go Server integrity (site-admin hackable, + e.g. file systems writeable, home directories mounted, etc.) +Further Information +------------------- + +Please do not hesitate to ask for more information. Visit our website [1] or contact the developers [2]. + +References +---------- + + * [1] https://wiki.x2go.org/ + * [2] mailto:x2go-dev@lists.x2go.org + +Commercial Support +------------------ + +Commercial support for the X2Go Session Broker is provided by: + + * DAS-NETZWERKTEAM, Mike Gabriel <mike.gabriel@das-netzwerkteam.de> + + +Contents +-------- + +.. toctree:: + :maxdepth: 4 + + x2gobroker Indices and tables ================== @@ -19,4 +107,3 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` - -- Alioth's /home/x2go-admin/maintenancescripts/git/hooks/post-receive-email on /srv/git/code.x2go.org/x2gobroker.git
This is an automated email from the git hooks/post-receive script. x2go pushed a commit to branch master in repository x2gobroker. commit 03ffe64d642fa219ee52b20dfebf003ba54eb0f3 Author: Mike Gabriel <mike.gabriel@das-netzwerkteam.de> Date: Tue Sep 11 16:25:44 2018 +0200 x2gbroker/_paramiko.py: Grammar fix in __doc__ string. --- x2gobroker/_paramiko.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/x2gobroker/_paramiko.py b/x2gobroker/_paramiko.py index ffaada0..2f45db8 100644 --- a/x2gobroker/_paramiko.py +++ b/x2gobroker/_paramiko.py @@ -18,7 +18,7 @@ # 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. """\ -Monkey Patch and feature map for Python Paramiko +Monkey patches and feature map for Python Paramiko """ -- Alioth's /home/x2go-admin/maintenancescripts/git/hooks/post-receive-email on /srv/git/code.x2go.org/x2gobroker.git
This is an automated email from the git hooks/post-receive script. x2go pushed a commit to branch master in repository x2gobroker. commit e1e8429150637e11a20e20583dd01784bc34f63b Author: Mike Gabriel <mike.gabriel@das-netzwerkteam.de> Date: Tue Sep 11 17:35:53 2018 +0200 x2gobroker.authservice: Document Auth Service client's authenticate() function. --- x2gobroker/authmechs/pam_authmech.py | 2 +- x2gobroker/authservice.py | 30 ++++++++++++++++++++++++++++++ 2 files changed, 31 insertions(+), 1 deletion(-) diff --git a/x2gobroker/authmechs/pam_authmech.py b/x2gobroker/authmechs/pam_authmech.py index 7fa0e30..d059aac 100644 --- a/x2gobroker/authmechs/pam_authmech.py +++ b/x2gobroker/authmechs/pam_authmech.py @@ -46,7 +46,7 @@ class X2GoBrokerAuthMech(object): authentication process. The X2Go Session Broker's Auth Service runs with these root privileges and provides a communication socket to the X2Go Session Broker where authentication requests are proxied - over. + over. See :func:`x2gobroker.authservice.authenticate()`. If you don't need root privileges for PAM authentication (e.g. LDAP), simply don't run the X2Go Broker Auth Service and diff --git a/x2gobroker/authservice.py b/x2gobroker/authservice.py index 4200589..d8d6755 100644 --- a/x2gobroker/authservice.py +++ b/x2gobroker/authservice.py @@ -26,6 +26,36 @@ from x2gobroker.loggers import logger_broker def authenticate(username, password, service="x2gobroker"): + """\ + Attempt PAM authentication proxied through X2Go Broker's Auth + Service. + + The X2Go Broker Auth Service runs with root privileges. For PAM + authentication mechanisms like the ``pam_unix.so`` PAM module, the + login process requires root privileges (as, staying with the example + of ``pam_unix.so``, the ``/etc/shadow`` file, where those passwords + are stored, is only accessible by the root superuser). + + As the X2Go Session Broker runs with reduced system privileges, it + has to delegate the actual PAM authentication process to the X2Go + Broker Auth Service. + + For this, X2Go Session Broker needs to connect to the Auth Service's + authentication socket (see the ``X2GOBROKER_AUTHSERVICE_SOCKET`` + variable in :mod:`x2gobroker.defaults`) and send the string + ``<username>\\r<password>\\r<service>\\n`` to the socket (where service + is the name of the PAM service file to use. + + :param username: username to use during authentication + :type username: ``str`` + :param password: password to use during authentication + :type password: ``str`` + + :returns: Authentication success or failure + :rtype: ``bool`` + + """ + s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) logger_broker.debug('authservice.authenticate(): connecting to authentication service socket {socket}'.format(socket=x2gobroker.defaults.X2GOBROKER_AUTHSERVICE_SOCKET)) s.connect(x2gobroker.defaults.X2GOBROKER_AUTHSERVICE_SOCKET) -- Alioth's /home/x2go-admin/maintenancescripts/git/hooks/post-receive-email on /srv/git/code.x2go.org/x2gobroker.git
-
git-admin＠x2go.org