new cli features: oidc-agent auth, 'info' command

Author: BerndSchuller

CHANGES.md

@@ -3,6 +3,12 @@ Changelog for PyUNICORE
 
 Issue tracker: https://github.com/HumanBrainProject/pyunicore
 
+Version 1.3.0 (mmm dd, 2025)
+----------------------------
+ - new feature: CLI: implemented more authentication options
+   (oidc-agent, anonymous)
+ - new feature: CLI: 'info' command
+
 Version 1.2.0 (Nov 08, 2024)
 ----------------------------
 

docs/source/uftp.rst

@@ -39,13 +39,47 @@ Here is a basic example using username/password.
 The object returned by `connect()` is an `ftplib` `FTP` object.
 
 
+Mounting remote filesystems via UFTP and FUSE
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+PyUNICORE contains a FUSE driver based on `fusepy <https://pypi.org/project/fusepy>`_,
+allowing you to mount a remote filesystem via UFTP. Mounting is a two step process,
+
+  * authenticate to an Auth server, giving you the UFTPD host/port and one-time password
+  * run the FUSE driver
+
+The following code example gives you the basic idea:
+
+.. code:: python
+
+  import pyunicore.client as uc_client
+  import pyunicore.credentials as uc_credentials
+  import pyunicore.uftp as uc_uftp
+  import pyunicore.uftpfuse as uc_fuse
+
+  _auth = "https://localhost:9000/rest/auth/TEST"
+  _base_dir = "/opt/shared-data"
+  _local_mount_dir = "/tmp/mount"
+
+  # authenticate
+  cred = uc_credentials.UsernamePassword("demouser", "test123")
+  _host, _port, _password  = uc_uftp.UFTP().authenticate(cred, _auth, _base_dir)
+
+  # run the fuse driver
+  fuse = uc_fuse.FUSE(
+  uc_fuse.UFTPDriver(_host, _port, _password), _local_mount_dir, foreground=False, nothreads=True)
+
 
 Using UFTP for PyFilesystem
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-You can create a `PyFilesystem <https://github.com/PyFilesystem/pyfilesystem2>`_
-`FS` object either directly in code, or implicitely via a URL.
+`PyFilesystem <https://github.com/PyFilesystem/pyfilesystem2>`_ is a virtual filesystem
+for Python supporting a variety of protocols.
+
+PyUNICORE contains two "drivers" that leverage UFTP.
 
+The first one accesses data directly via UFTP. You can create a PyFilesystem `FS`
+object either directly in code, or implicitely via a URL.
 The convenient way is via URL:
 
 .. code:: python
@@ -70,34 +104,18 @@ The FS driver supports three types of authentication
     Specify the `password` if needed to load the private key
   * Bearer token - give the token value via the `token` parameter
 
+The `base-directory` parameter denotes the remote directory that is to be accessed.
 
+The second driver mounts the remote filesystem via FUSE, and then accesses
+data "locally". The URL format is
 
-Mounting remote filesystems via UFTP
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-PyUNICORE contains a FUSE driver based on `fusepy <https://pypi.org/project/fusepy>`_,
-allowing you to mount a remote filesystem via UFTP. Mounting is a two step process,
-
-  * authenticate to an Auth server, giving you the UFTPD host/port and one-time password
-  * run the FUSE driver
-
-The following code example gives you the basic idea:
-
-.. code:: python
+.. code:: console
 
-  import pyunicore.client as uc_client
-  import pyunicore.credentials as uc_credentials
-  import pyunicore.uftp as uc_uftp
-  import pyunicore.uftpfuse as uc_fuse
+    uftpmount://[username]:[password]@[auth-server-url]:[base-directory==mount-directory]?[token=...][identity=...]
 
-  _auth = "https://localhost:9000/rest/auth/TEST"
-  _base_dir = "/opt/shared-data"
-  _local_mount_dir = "/tmp/mount"
+with the same authentication options as before.
 
-  # authenticate
-  cred = uc_credentials.UsernamePassword("demouser", "test123")
-  _host, _port, _password  = uc_uftp.UFTP().authenticate(cred, _auth, _base_dir)
+The mount directory is given
 
-  # run the fuse driver
-  fuse = uc_fuse.FUSE(
-  uc_fuse.UFTPDriver(_host, _port, _password), _local_mount_dir, foreground=False, nothreads=True)
+The `base-directory==mount-directory` parameter denotes the remote directory that is to be accessed,
+as well as the local directory where it should be mounted.

pyunicore/cli/base.py

@@ -83,10 +83,15 @@ def get_group(self):
 
     def create_credential(self):
         auth_method = self.config.get("authentication-method", "USERNAME").upper()
-        if "USERNAME" == auth_method:
+        if "OIDC-AGENT" == auth_method:
+            account_name = self.config.get("oidc-agent.account")
+            self.credential = pyunicore.credentials.OIDCAgentToken(account_name)
+        elif "USERNAME" == auth_method:
             username = self.config["username"]
             password = self._get_password()
-        self.credential = pyunicore.credentials.create_credential(username, password)
+            self.credential = pyunicore.credentials.create_credential(username, password)
+        elif "ANONYMOUS" == auth_method:
+            self.credential = pyunicore.credentials.Anonymous()
 
     def _get_password(self, key="password") -> str:
         password = self.config.get(key)

pyunicore/cli/info.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from pyunicore.cli.base import Base
+from pyunicore.client import Resource
+
+
+class Info(Base):
+    def add_command_args(self):
+        self.parser.prog = "unicore system-info"
+        self.parser.description = self.get_synopsis()
+        self.parser.add_argument("URL", help="Endpoint URL(s)", nargs="*")
+        self.parser.add_argument(
+            "-p",
+            "--pattern",
+            required=False,
+            type=str,
+            help="Only show info for endpoints matching the given regexp",
+        )
+        self.parser.add_argument(
+            "-l", "--long", required=False, action="store_true", help="Show detailed info"
+        )
+
+    def get_synopsis(self):
+        return """Show information about endpoint(s). If no explicit endpoints are given,
+        the endpoints in the registry are used. The optional pattern allows to limit which
+        endpoints are listed."""
+
+    def get_description(self):
+        return "show info on available services"
+
+    def get_group(self):
+        return "Utilities"
+
+    def run(self, args):
+        super().setup(args)
+        endpoints = self.registry.site_urls.values()
+
+        if self.args.URL:
+            endpoints = self.args.URL
+
+        for url in endpoints:
+            c = Resource(self.credential, resource_url=url)
+            self.show_endpoint_details(c)
+
+    def show_endpoint_details(self, ep: Resource):
+        print(ep.resource_url)
+        if "/rest/core" in ep.resource_url:
+            self._show_details_core(ep)
+        else:
+            print(" * no further details available.")
+
+    def _show_details_core(self, ep: Resource):
+        props = ep.properties
+        print(f" * server v{props['server']['version']}")
+        xlogin = props["client"]["xlogin"]
+        role = props["client"]["role"]["selected"]
+        uid = xlogin.get("UID", "n/a")
+        print(f" * authenticated as: '{props['client']['dn']}' role='{role}' uid='{uid}'")
+        grps = xlogin.get("availableGroups", [])
+        uids = xlogin.get("availableUIDs", [])
+        if len(uids) > 0:
+            print(f" * available UIDs: {uids}")
+        if len(grps) > 0:
+            print(f" * available groups: {grps}")
+        roles = props["client"]["role"].get("availableRoles", [])
+        if len(roles) > 0:
+            print(f" * available roles: {roles}")

pyunicore/cli/main.py

@@ -5,13 +5,15 @@
 
 import pyunicore.cli.base
 import pyunicore.cli.exec
+import pyunicore.cli.info
 import pyunicore.cli.io
 
 _commands = {
     "cancel-job": pyunicore.cli.exec.CancelJob,
     "cat": pyunicore.cli.io.Cat,
     "cp": pyunicore.cli.io.CP,
     "exec": pyunicore.cli.exec.Exec,
+    "info": pyunicore.cli.info.Info,
     "issue-token": pyunicore.cli.base.IssueToken,
     "job-status": pyunicore.cli.exec.GetJobStatus,
     "list-jobs": pyunicore.cli.exec.ListJobs,

pyunicore/credentials.py

@@ -10,9 +10,12 @@
     pass
 
 import datetime
+import json
+import socket
 from abc import ABCMeta
 from abc import abstractmethod
 from base64 import b64encode
+from os import environ
 from os import getenv
 from os.path import isabs
 
@@ -202,6 +205,44 @@ def get_auth_header(self):
         return "Bearer " + self.create_token()
 
 
+class OIDCAgentToken(OIDCToken):
+    """
+    Produces a header value "Bearer <auth_token>"
+
+    Args:
+        token: the value of the auth token
+        refresh_handler: optional refresh handler that provides a get_token() method which
+                         will be invoked to refresh the bearer token
+    """
+
+    def __init__(self, account_name):
+        super().__init__(token=None, refresh_handler=None)
+        self.account = account_name
+        self.token = self.get_token()
+
+    def get_token(self) -> str:
+        params = {}
+        params["account"] = self.account
+        params["request"] = "access_token"
+        # TODO: params["scope"] = ...
+        try:
+            socket_path = environ.get("OIDC_SOCK")
+        except KeyError:
+            raise OSError("OIDC Agent not running (environment variable OIDC_SOCK not found)")
+        with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as sock:
+            sock.connect(socket_path)
+            sock.sendall(json.dumps(params).encode("utf-8"))
+            res = b""
+            while True:
+                part = sock.recv(4096)
+                res += part
+                if len(part) < 4096:
+                    break
+            reply = json.loads(res.decode("utf-8"))
+            if "success" == reply.get("status", None):
+                return reply["access_token"]
+
+
 def create_credential(username=None, password=None, token=None, identity=None):
     """Helper to create the most common types of credentials