[X2Go-Commits] [x2gobroker] 06/06: x2gobroker.authservice: Document Auth Service client's authenticate() function.

[git-admin at x2go.org]

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 at 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