feat(auth): add scope documentation

DIRACGrid · Oct 18, 2024 · 55bf0cd · 55bf0cd
1 parent 00665bd
commit 55bf0cd
Show file tree

Hide file tree

Showing 3 changed files with 47 additions and 6 deletions.
diff --git 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
@@ -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
@@ -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`