From e36c06bff8c9484cd733e55b585b417f0c0614d1 Mon Sep 17 00:00:00 2001
From: aldbr <aldbr@outlook.com>
Date: Thu, 17 Oct 2024 10:56:03 +0200
Subject: [PATCH] feat(auth): add scope documentation

---
 diracx-cli/src/diracx/cli/__init__.py         | 28 +++++++++++++++++--
 .../routers/auth/authorize_code_flow.py       | 11 ++++++++
 .../src/diracx/routers/auth/device_flow.py    | 14 ++++++++--
 3 files changed, 47 insertions(+), 6 deletions(-)

diff --git a/diracx-cli/src/diracx/cli/__init__.py b/diracx-cli/src/diracx/cli/__init__.py
index 9f2a04f9..edf36abe 100644
--- a/diracx-cli/src/diracx/cli/__init__.py
+++ b/diracx-cli/src/diracx/cli/__init__.py
@@ -38,12 +38,34 @@ def vo_callback(vo: str | None) -> str:
 
 @app.async_command()
 async def login(
-    vo: Annotated[Optional[str], typer.Argument(callback=vo_callback)] = None,
-    group: Optional[str] = None,
+    vo: Annotated[
+        Optional[str],
+        typer.Argument(callback=vo_callback, help="Virtual Organization name"),
+    ] = None,
+    group: Optional[str] = typer.Option(
+        None,
+        help="Group name within the VO. If not provided, the default group for the VO will be used.",
+    ),
     property: Optional[list[str]] = typer.Option(
-        None, help="Override the default(s) with one or more properties"
+        None,
+        help=(
+            "List of properties to add to the default properties of the group. "
+            "If not provided, default properties of the group will be used."
+        ),
     ),
 ):
+    """Login to the DIRAC system using the device flow.
+
+    - If only VO is provided: Uses the default group and its properties for the VO.
+
+    - If VO and group are provided: Uses the specified group and its properties for the VO.
+
+    - If VO and properties are provided: Uses the default group and combines its properties with the
+      provided properties.
+
+    - If VO, group, and properties are provided: Uses the specified group and combines its properties with the
+      provided properties.
+    """
     scopes = [f"vo:{vo}"]
     if group:
         scopes.append(f"group:{group}")
diff --git a/diracx-routers/src/diracx/routers/auth/authorize_code_flow.py b/diracx-routers/src/diracx/routers/auth/authorize_code_flow.py
index 7ee4e602..f57aaa43 100644
--- a/diracx-routers/src/diracx/routers/auth/authorize_code_flow.py
+++ b/diracx-routers/src/diracx/routers/auth/authorize_code_flow.py
@@ -78,6 +78,17 @@ async def authorization_flow(
     It will redirect to the actual OpenID server (IAM, CheckIn) to
     perform a authorization code flow.
 
+    Scope details:
+    - If only VO is provided: Uses the default group and its properties for the VO.
+
+    - If VO and group are provided: Uses the specified group and its properties for the VO.
+
+    - If VO and properties are provided: Uses the default group and combines its properties with the
+      provided properties.
+
+    - If VO, group, and properties are provided: Uses the specified group and combines its properties with the
+      provided properties.
+
     We set the user details obtained from the user authorize flow in a cookie
     to be able to map the authorization flow with the corresponding
     user authorize flow.
diff --git a/diracx-routers/src/diracx/routers/auth/device_flow.py b/diracx-routers/src/diracx/routers/auth/device_flow.py
index 799a5e3a..3fa47bf6 100644
--- a/diracx-routers/src/diracx/routers/auth/device_flow.py
+++ b/diracx-routers/src/diracx/routers/auth/device_flow.py
@@ -101,9 +101,17 @@ async def initiate_device_flow(
     settings: AuthSettings,
 ) -> InitiateDeviceFlowResponse:
     """Initiate the device flow against DIRAC authorization Server.
-    Scope must have exactly up to one `group` (otherwise default) and
-    one or more `property` scope.
-    If no property, then get default one.
+
+    Scope details:
+    - If only VO is provided: Uses the default group and its properties for the VO.
+
+    - If VO and group are provided: Uses the specified group and its properties for the VO.
+
+    - If VO and properties are provided: Uses the default group and combines its properties with the
+      provided properties.
+
+    - If VO, group, and properties are provided: Uses the specified group and combines its properties with the
+      provided properties.
 
     Offers the user to go with the browser to
     `auth/<vo>/device?user_code=XYZ`