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.gabr...@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
_______________________________________________
x2go-commits mailing list
x2go-commits@lists.x2go.org
https://lists.x2go.org/listinfo/x2go-commits
