SSHAuthenticationUtils: expanded password to optional capture ssh output

some test cases will need to check the ssh output

sssd_test_framework/utils/authentication.py

@@ -192,14 +192,13 @@ def password(self, username: str, password: str) -> bool:
         """
         Call ``su - $username`` and authenticate the user with password.
 
-        :param name: User name.
-        :type name: str
+        :param username: Username.
+        :type username: str
         :param password: User password.
         :type password: str
         :return: True if authentication was successful, False otherwise.
         :rtype: bool
         """
-
         result = self.host.ssh.expect_nobody(
             rf"""
             # It takes some time to get authentication failure
@@ -236,8 +235,8 @@ def password_expired(self, username: str, password: str, new_password: str) -> b
         Call ``su - $username`` and authenticate the user with password, expect
         that the password is expired and change it to the new password.
 
-        :param username: User name.
-        :type name: str
+        :param username: Username.
+        :type username: str
         :param password: Old, expired user password.
         :type password: str
         :param new_password: New user password.
@@ -305,7 +304,7 @@ def passkey(self, username: str, *, pin: str | int, device: str, ioctl: str, scr
         """
         Call ``su - $username`` and authenticate the user with passkey.
 
-        :param username: User name
+        :param username: Username
         :type username: str
         :param pin: Passkey PIN.
         :type pin: str | int
@@ -413,23 +412,29 @@ def __init__(self, host: MultihostHost) -> None:
         self.opts = "-o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no"
         """SSH CLI options."""
 
-    def password(self, username: str, password: str) -> bool:
+    def password(self, username: str, password: str, output: bool = False) -> bool | str:
         """
         SSH to the remote host and authenticate the user with password.
 
-        :param name: User name.
-        :type name: str
+        :param username: Username.
+        :type username: str
         :param password: User password.
         :type password: str
-        :return: True if authentication was successful, False otherwise.
-        :rtype: bool
+        :param output: Log output.
+        :type output: bool
+        :return: True if authentication was successful, False otherwise. If output is true, return output.
+        :rtype: bool | str
         """
+        log = "0"
+        if output is True:
+            log = "1"
 
         result = self.host.ssh.expect_nobody(
             rf"""
             # It takes some time to get authentication failure
             set timeout {DEFAULT_AUTHENTICATION_TIMEOUT}
             set prompt "\n.*\[#\$>\] $"
+            log_user {log}
 
             spawn ssh {self.opts} \
                 -o PreferredAuthentications=password \
@@ -458,15 +463,18 @@ def password(self, username: str, password: str) -> bool:
         if result.rc > 200:
             raise ExpectScriptError(result.rc)
 
+        if output is True:
+            return result.stdout
+
         return result.rc == 0
 
     def password_expired(self, username: str, password: str, new_password: str) -> bool:
         """
         SSH to the remote host and authenticate the user with password, expect
         that the password is expired and change it to the new password.
 
-        :param username: User name.
-        :type name: str
+        :param username: Username.
+        :type username: str
         :param password: Old, expired user password.
         :type password: str
         :param new_password: New user password.
@@ -539,6 +547,54 @@ def password_expired(self, username: str, password: str, new_password: str) -> b
         return result.rc == 0
 
 
+    def password_log(self, username: str, password: str) -> str:
+        """
+        SSH to the remote host and authenticate the user with password returning the session log.
+
+        :param username: Username.
+        :type username: str
+        :param password: User password.
+        :type password: str
+        :return: Session log.
+        :rtype: str
+        """
+        result = self.host.ssh.expect_nobody(
+            rf"""
+            # It takes some time to get authentication failure
+            set timeout {DEFAULT_AUTHENTICATION_TIMEOUT}
+            set prompt "\n.*\[#\$>\] $"
+            log_user 1
+
+            spawn ssh {self.opts} \
+                -o PreferredAuthentications=password \
+                -o NumberOfPasswordPrompts=1 \
+                -l "{username}" localhost
+
+            expect {{
+                "password:" {{send "{password}\n"}}
+                timeout {{puts "expect result: Unexpected output"; exit 201}}
+                eof {{puts "expect result: Unexpected end of file"; exit 202}}
+            }}
+
+            expect {{
+                -re $prompt {{puts "expect result: Password authentication successful"; exit 0}}
+                "{username}@localhost: Permission denied" {{puts "expect result: Authentication failure"; exit 1}}
+                "Connection closed by UNKNOWN port 65535" {{puts "expect result: Connection closed"; exit 2}}
+                timeout {{puts "expect result: Unexpected output"; exit 201}}
+                eof {{puts "expect result: Unexpected end of file"; exit 202}}
+            }}
+
+            puts "expect result: Unexpected code path"
+            exit 203
+        """
+        )
+
+        if result.rc > 200:
+            raise ExpectScriptError(result.rc)
+
+        return result.stdout
+
+
 class SudoAuthenticationUtils(MultihostUtility[MultihostHost]):
     """
     Methods for testing authentication and authorization via sudo.