RFL.authentication 1.0.0__py3-none-any.whl

RFL.authentication-1.0.0.dist-info/METADATA

@@ -0,0 +1,24 @@
+Metadata-Version: 2.1
+Name: RFL.authentication
+Version: 1.0.0
+Summary: Rackslab Foundation Library: authentication package
+Author-email: Rémi Palancher <remi@rackslab.io>
+License: GPLv3+
+Project-URL: Homepage, https://github.com/rackslab/RFL
+Project-URL: Bug Tracker, https://github.com/rackslab/RFL/issues
+Keywords: utility,basic
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Requires-Dist: RFL.core
+Requires-Dist: PyJWT
+Requires-Dist: python-ldap
+
+# RFL: authentication package
+
+Generate and validate JWT tokens.

RFL.authentication-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+rfl/authentication/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rfl/authentication/errors.py,sha256=BCdOrQRdj1k5Co_HW-f8bhs0Su96hkcqMNN2gjFGkxA,498
+rfl/authentication/jwt.py,sha256=nxFrScrDO4fYVF_LXQJ642ayQbqXAa09vffjJqbWz_k,6173
+rfl/authentication/ldap.py,sha256=LzRISee_T7n20YyzVFPUlxcaOoXHAJoA9YIK3a3oVx8,12827
+rfl/authentication/user.py,sha256=lFYJCscipF5SpEYwr8-wYAt5P3cDxLYaTUQzvR2U_Y0,479
+RFL.authentication-1.0.0.dist-info/METADATA,sha256=ZepYHW3TA4L5yRRH5IJFWlbGCcxaibDc3ocojKHEJwk,868
+RFL.authentication-1.0.0.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
+RFL.authentication-1.0.0.dist-info/top_level.txt,sha256=EIloiMrXuRz8n0vqkCE6NM9Ze1S2mrbCKBcdtWaM_og,4
+RFL.authentication-1.0.0.dist-info/RECORD,,

RFL.authentication-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.43.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

RFL.authentication-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rfl

rfl/authentication/errors.py

@@ -0,0 +1,35 @@
+# Copyright (c) 2023 Rackslab
+#
+# This file is part of RFL.
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from rfl.core.errors import RFLError
+
+
+class AuthenticationError(RFLError):
+    pass
+
+
+class LDAPAuthenticationError(AuthenticationError):
+    pass
+
+
+class JWTError(AuthenticationError):
+    pass
+
+
+class JWTPrivateKeyGeneratorError(JWTError):
+    pass
+
+
+class JWTPrivateKeyLoaderError(JWTError):
+    pass
+
+
+class JWTDecodeError(JWTError):
+    pass
+
+
+class JWTEncodeError(JWTError):
+    pass

rfl/authentication/jwt.py

@@ -0,0 +1,170 @@
+# Copyright (c) 2023 Rackslab
+#
+# This file is part of RFL.
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import secrets
+from datetime import datetime, timezone, timedelta
+import logging
+from pathlib import Path
+
+import jwt
+
+from .user import AuthenticatedUser
+from .errors import (
+    JWTPrivateKeyGeneratorError,
+    JWTPrivateKeyLoaderError,
+    JWTDecodeError,
+    JWTEncodeError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def jwt_gen_key(path: Path):
+    """Generate JWT private key with random data. Raise JWTPrivateKeyGeneratorError in
+    case of error."""
+    logger.info("Generating JWT private key file %s", path)
+    try:
+        with open(path, "w+") as fh:
+            fh.write(secrets.token_hex(32))
+    except (FileNotFoundError, NotADirectoryError, PermissionError) as err:
+        raise JWTPrivateKeyGeneratorError(
+            f"Error while generating JWT key {path}: {err}"
+        ) from err
+    path.chmod(0o400)  # restrict access to encryption key
+
+
+class JWTPrivateKeyLoader:
+    pass
+
+
+class JWTPrivateKeyFileLoader(JWTPrivateKeyLoader):
+    def __init__(
+        self,
+        path: Path = None,
+        value: str = None,
+        create: bool = False,
+        create_parent: bool = False,
+    ):
+        if path is not None:
+            logger.debug("Loading JWT private key from path %s", path)
+            self.path = path
+            self.key = None
+            self._load_path(create, create_parent)
+        elif value is not None:
+            logger.debug("Loading JWT private key from value")
+            self.path = None
+            self.key = value
+        else:
+            raise JWTPrivateKeyLoaderError(
+                "Either key value or a path must be given to load JWT private key"
+            )
+
+    def _load_path(self, create: bool, create_parent: bool) -> None:
+        """Load the JWT private key from path. If create argument is True, the private
+        key is randomly generated if not present. If create_parent is True, the parent
+        directory of the private key is also created if not present. Raise
+        JWTPrivateKeyLoaderError if create_parent is False and private parent directory
+        does not exist or if create is False and private key file does not exist."""
+        # Create tokens directory if missing
+        if not self.path.parent.exists():
+            if create_parent:
+                logger.info("Creating JWT private key directory %s", self.path.parent)
+                try:
+                    self.path.parent.mkdir()
+                    self.path.parent.chmod(0o755)  # be umask agnostic
+                except PermissionError as err:
+                    raise JWTPrivateKeyLoaderError(
+                        "Permission denied to create key parent directory "
+                        f"{self.path.parent}"
+                    ) from err
+            else:
+                raise JWTPrivateKeyLoaderError(
+                    f"Token private key parent directory {self.path.parent} not found"
+                )
+        # Generate instance tokens encryption key file if missing
+        if not self.path.exists():
+            if create:
+                jwt_gen_key(self.path)
+            else:
+                raise JWTPrivateKeyLoaderError(
+                    f"Token private key file {self.path} not found"
+                )
+        # Load the instance tokens encryption key
+        try:
+            with open(self.path, "r") as fh:
+                self.key = fh.read()
+        except PermissionError as err:
+            raise JWTPrivateKeyLoaderError(
+                f"Permission error to access private key file {self.path}"
+            ) from err
+        if not len(self.key):
+            raise JWTPrivateKeyLoaderError(f"Key loaded from file {self.path} is empty")
+
+
+class JWTManager:
+    def __init__(self, audience: str, algorithm: str, loader: JWTPrivateKeyLoader):
+        self.audience = audience
+        self.algorithm = algorithm
+        self.key = loader.key
+
+    def decode(self, token) -> AuthenticatedUser:
+        """Decode the given token with the encryption key an returns the user of
+        this token."""
+        try:
+            payload = jwt.decode(
+                token,
+                self.key,
+                audience=self.audience,
+                algorithms=[self.algorithm],
+            )
+        except jwt.InvalidSignatureError as err:
+            raise JWTDecodeError("Token signature is invalid") from err
+        except jwt.ExpiredSignatureError as err:
+            raise JWTDecodeError("Token is expired") from err
+        except jwt.InvalidAudienceError as err:
+            raise JWTDecodeError("Token audience is invalid") from err
+        except jwt.exceptions.DecodeError as err:
+            raise JWTDecodeError(f"Unable to decode token: {str(err)}") from err
+        return AuthenticatedUser(login=payload["sub"], groups=payload["groups"])
+
+    def generate(self, user: AuthenticatedUser, duration: int) -> str:
+        """Returns a JWT token for the given user, signed with the encryption
+        key, for the configured audience and valid for the given duration."""
+        try:
+            token = jwt.encode(
+                {
+                    "iat": datetime.now(tz=timezone.utc),
+                    "exp": datetime.now(tz=timezone.utc) + timedelta(days=duration),
+                    "aud": self.audience,
+                    "sub": user.login,
+                    "groups": user.groups,
+                },
+                self.key,
+                algorithm=self.algorithm,
+            )
+        except NotImplementedError as err:
+            raise JWTEncodeError(f"JWT token encode error: {str(err)}") from err
+        # For compatibility with PyJWT < 2
+        if isinstance(token, bytes):
+            return token.decode()
+        return token
+
+    @classmethod
+    def key(
+        cls,
+        audience: str,
+        algorithm: str,
+        path: Path,
+        create: bool = False,
+        create_parent: bool = False,
+    ):
+        return cls(
+            audience,
+            algorithm,
+            JWTPrivateKeyFileLoader(
+                path=path, create=create, create_parent=create_parent
+            ),
+        )

rfl/authentication/ldap.py

@@ -0,0 +1,315 @@
+# Copyright (c) 2023 Rackslab
+#
+# This file is part of RFL.
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from typing import Union, List, Tuple
+from pathlib import Path
+import logging
+
+import ldap
+
+from .user import AuthenticatedUser
+from .errors import LDAPAuthenticationError
+
+
+logger = logging.getLogger(__name__)
+
+
+class LDAPAuthentifier:
+    def __init__(
+        self,
+        uri,
+        cacert: Union[Path, None],
+        user_base: str,
+        user_class: str,
+        group_base: str,
+        user_fullname_attribute: str,
+        group_name_attribute: str,
+        starttls: bool = False,
+        bind_dn: Union[str, None] = None,
+        bind_password: Union[str, None] = None,
+        restricted_groups: Union[List[str], None] = None,
+    ):
+        self.uri = uri
+        self.cacert = cacert
+        self.user_base = user_base
+        self.user_class = user_class
+        self.group_base = group_base
+        self.user_fullname_attribute = user_fullname_attribute
+        self.group_name_attribute = group_name_attribute
+        self.starttls = starttls
+        self.bind_dn = bind_dn
+        self.bind_password = bind_password
+        self.restricted_groups = restricted_groups
+
+    def connection(self):
+        connection = ldap.initialize(self.uri.geturl())
+        # SSL/TLS setup
+        if self.uri.geturl().startswith("ldaps") or self.starttls:
+            connection.protocol_version = ldap.VERSION3
+            # Force server certificate validation
+            connection.set_option(ldap.OPT_X_TLS_REQUIRE_CERT, ldap.OPT_X_TLS_DEMAND)
+            # For LDAPS and STARTTLS, libldap require the path to CA certificates to be
+            # defined to authentication server certificate. If the cacert option is
+            # defined, use it else use default system CA certificates directory defined
+            # in OpenSSL library.
+            if self.cacert is None:
+                import ssl
+
+                logger.debug(
+                    "Using default system OpenSSL CA certificate directory to "
+                    "authenticate server"
+                )
+                connection.set_option(
+                    ldap.OPT_X_TLS_CACERTDIR,
+                    ssl.get_default_verify_paths().openssl_capath,
+                )
+            else:
+                logger.debug(
+                    "Using CA certification %s to authenticate server", self.cacert
+                )
+                connection.set_option(ldap.OPT_X_TLS_CACERTFILE, str(self.cacert))
+            # Force libldap to create a new SSL context
+            try:
+                connection.set_option(ldap.OPT_X_TLS_NEWCTX, 0)
+            except ValueError as err:
+                raise LDAPAuthenticationError(
+                    "LDAP connection option value error"
+                ) from err
+        if self.starttls:
+            try:
+                logger.debug("Using STARTTLS to initialize TLS connection")
+                connection.start_tls_s()
+            except ldap.CONNECT_ERROR as err:
+                raise LDAPAuthenticationError(
+                    f"Unable to connect to LDAP server with STARTTLS: {str(err)}"
+                ) from err
+            except ldap.SERVER_DOWN as err:
+                raise LDAPAuthenticationError(
+                    f"LDAP server {self.uri.geturl()} is unreachable"
+                ) from err
+        return connection
+
+    def _get_user_info(
+        self, connection: ldap.ldapobject.LDAPObject, user_dn: str
+    ) -> Tuple[str, int]:
+        """Return fullname and gidNumber from the provided user DN."""
+        search_filter = f"(objectClass={self.user_class})"
+        try:
+            results = connection.search_s(
+                user_dn,
+                ldap.SCOPE_BASE,
+                search_filter,
+                [self.user_fullname_attribute, "gidNumber"],
+            )
+        except ldap.NO_SUCH_OBJECT as err:
+            raise LDAPAuthenticationError(f"Unable to find user DN {user_dn}") from err
+        logger.debug(
+            "LDAP search base: %s, scope: base filter: %s, results: %s",
+            user_dn,
+            search_filter,
+            str(results),
+        )
+        if not len(results):
+            raise LDAPAuthenticationError(
+                f"User not found in LDAP with class {self.user_class}"
+            )
+        try:
+            fullname = results[0][1][self.user_fullname_attribute][0].decode()
+        except KeyError as err:
+            raise LDAPAuthenticationError(
+                f"Unable to extract user full name with {self.group_name_attribute} "
+                "attribute from user entries"
+            ) from err
+        try:
+            gidNumber = int(results[0][1]["gidNumber"][0])
+        except KeyError as err:
+            raise LDAPAuthenticationError(
+                "Unable to extract user primary group with gidNumber attribute from "
+                "user entries"
+            ) from err
+        return fullname, gidNumber
+
+    def _get_groups(
+        self,
+        connection: ldap.ldapobject.LDAPObject,
+        user_name: str,
+        user_dn: str,
+        gidNumber: int,
+    ) -> List[str]:
+        """Return the list of groups whose provided user is member, including its
+        gidNumber. This function supports both RFC 2307 (aka. NIS schema) and RFC 2307
+        bis schema."""
+        # Standard RFC 2307 (aka. NIS) schema has group entries with posixGroup
+        # structural class. Group members are declared with memberUid attributes (with
+        # user cn as values).
+        #
+        # RFC 2307 bis schema has group entries with generally at least groupOfNames
+        # class and group members are declared with member attributes (with full user dn
+        # as values).
+        #
+        # In both cases, user primary group declared with gidNumber attribute in user
+        # entry must not be forgiven.
+        search_filter = (
+            "(&"
+            "(|(objectClass=posixGroup)(objectClass=groupOfNames))"
+            f"(|(memberUid={user_name})(member={user_dn})(gidNumber={gidNumber})))"
+        )
+        try:
+            results = connection.search_s(
+                self.group_base,
+                ldap.SCOPE_SUBTREE,
+                search_filter,
+                [self.group_name_attribute],
+            )
+        except ldap.NO_SUCH_OBJECT as err:
+            raise LDAPAuthenticationError(
+                f"Unable to find group base {self.group_base}"
+            ) from err
+        logger.debug(
+            "LDAP search base: %s, scope: subtree, filter: %s, results: %s",
+            self.group_base,
+            search_filter,
+            str(results),
+        )
+        if not len(results):
+            logger.warning(
+                "Unable to find groups in LDAP for user %s or gidNumber %s",
+                user_name,
+                gidNumber,
+            )
+        try:
+            return [
+                result[1][self.group_name_attribute][0].decode() for result in results
+            ]
+        except KeyError as err:
+            raise LDAPAuthenticationError(
+                f"Unable to extract group name with {self.group_name_attribute} "
+                "attribute from group entries"
+            ) from err
+
+    def _in_restricted_groups(self, groups: List[str]):
+        """Return False if restricted groups are set and none of the groups in argument
+        matches the restricted groups. If either restricted groups are unset or any of
+        the groups in argument is in restricted group, True is returned."""
+        return not (
+            self.restricted_groups is not None
+            and len(self.restricted_groups)
+            and not any([group in self.restricted_groups for group in groups])
+        )
+
+    def login(self, user: str, password: str) -> AuthenticatedUser:
+        """Verify provided user/password are valid and return the corresponding
+        AuthenticatedUser. Raise LDAPAuthenticationError if restricted groups are set
+        and the user in not member of any of these groups."""
+        fullname = None
+        groups = None
+        connection = self.connection()
+        if user is None or password is None:
+            raise LDAPAuthenticationError("Invalid authentication request")
+        try:
+            # Try simple authentication with user/password on LDAP directory
+            user_dn = f"uid={user},{self.user_base}"
+            connection.simple_bind_s(user_dn, password)
+            fullname, gidNumber = self._get_user_info(connection, user_dn)
+            groups = self._get_groups(connection, user, user_dn, gidNumber)
+        except ldap.SERVER_DOWN as err:
+            raise LDAPAuthenticationError(
+                f"LDAP server {self.uri.geturl()} is unreachable"
+            ) from err
+        except ldap.INVALID_CREDENTIALS as err:
+            raise LDAPAuthenticationError("Invalid user or password") from err
+        except ldap.UNWILLING_TO_PERFORM as err:
+            raise LDAPAuthenticationError(
+                f"LDAP server is unwilling to perform: {str(err)}"
+            ) from err
+        finally:
+            connection.unbind_s()
+        if not self._in_restricted_groups(groups):
+            raise LDAPAuthenticationError(
+                f"User {user} is not member of restricted groups"
+            )
+        return AuthenticatedUser(login=user, fullname=fullname, groups=groups)
+
+    def _list_user_dn(self, connection):
+        """Return list of all users name/pairs pairs in LDAP directory."""
+        search_filter = f"(objectClass={self.user_class})"
+        try:
+            results = connection.search_s(
+                self.user_base,
+                ldap.SCOPE_SUBTREE,
+                search_filter,
+                ["uid"],
+            )
+        except ldap.NO_SUCH_OBJECT as err:
+            raise LDAPAuthenticationError(
+                f"Unable to find user base {self.user_base}"
+            ) from err
+        logger.debug(
+            "LDAP search base: %s, scope: subtree, filter: %s, results: %s",
+            self.group_base,
+            search_filter,
+            str(results),
+        )
+        if not len(results):
+            logger.warning(
+                "Unable to find users in LDAP in base %s subtree",
+                self.user_base,
+            )
+        try:
+            return [(result[1]["uid"][0].decode(), result[0]) for result in results]
+        except KeyError as err:
+            raise LDAPAuthenticationError(
+                "Unable to extract user uid from user entries"
+            ) from err
+
+    def users(self, with_groups: bool = False) -> List[AuthenticatedUser]:
+        """Return list of AuthenticatedUser available in LDAP directory. If with_groups
+        is True, the groups attribute of the AuthenticatedUsers is also initialized with
+        the list of their groups. If with_groups is True and restricted groups are set,
+        all users whose groups do not match any of the restricted groups are
+        discarded."""
+        result = []
+        connection = self.connection()
+
+        if self.bind_dn is not None:
+            logger.debug("Using DN %s to bind to LDAP directory", self.bind_dn)
+            try:
+                assert self.bind_password is not None
+            except AssertionError as err:
+                raise LDAPAuthenticationError(
+                    f"Password to authenticate with bind DN {self.bind_dn} is required"
+                ) from err
+            try:
+                connection.simple_bind_s(self.bind_dn, self.bind_password)
+            except ldap.INVALID_CREDENTIALS as err:
+                raise LDAPAuthenticationError("Invalid bind DN or password") from err
+
+        try:
+            for (user, user_dn) in self._list_user_dn(connection):
+                fullname, gidNumber = self._get_user_info(connection, user_dn)
+                groups = []
+                if with_groups:
+                    groups = self._get_groups(connection, user, user_dn, gidNumber)
+                    # Skip the user if not member of any of the restricted groups
+                    if not self._in_restricted_groups(groups):
+                        logger.debug(
+                            "Discarding user %s not member of restricted groups", user
+                        )
+                        continue
+                result.append(
+                    AuthenticatedUser(login=user, fullname=fullname, groups=groups)
+                )
+        except ldap.SERVER_DOWN as err:
+            raise LDAPAuthenticationError(
+                f"LDAP server {self.uri.geturl()} is unreachable"
+            ) from err
+        except ldap.UNWILLING_TO_PERFORM as err:
+            raise LDAPAuthenticationError(
+                f"LDAP server is unwilling to perform: {str(err)}"
+            ) from err
+        finally:
+            connection.unbind_s()
+        return result

rfl/authentication/user.py

@@ -0,0 +1,19 @@
+# Copyright (c) 2023 Rackslab
+#
+# This file is part of RFL.
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from typing import Union, List
+
+
+class AuthenticatedUser:
+    def __init__(
+        self, login: str, fullname: Union[str, None] = None, groups: List[str] = []
+    ):
+        self.login = login
+        self.fullname = fullname
+        self.groups = groups
+
+    def __str__(self) -> str:
+        return f"{self.login} ({self.fullname or '∅'}) [{', '.join(self.groups)}]"