refactor(auth): improve code quality and add missing tests

- Replace deprecated datetime.utcnow() with datetime.now(timezone.utc)
- Add case-insensitive username matching in session resolution
- Cache MSAL app per tenant in list_accounts to avoid redundant creation
- Log TypeError instead of silently swallowing in _get_matching_account
- Add clarifying comments on acquire_token branching logic
- Only reset MSAL app when tenant actually changes (set_tenant, _sync)
- Expand docs with parameter descriptions and behavior details
- Add edge case tests: env var block, case-insensitive switch, 3+ account
  prompt, cancelled prompt, empty list, app preservation on tenant match

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Mathieu Turcotte

docs/commands/auth/index.md

@@ -40,19 +40,27 @@ fab auth login [-u <client_id>] [-p <client_secret>] [--federated-token <token>]
 
 ### logout
 
-End the current authentication session.
+End the current authentication session. When multiple user sessions are stored you can target a specific session by account name and/or tenant.
 
 **Usage:**
 
 ```
 fab auth logout [-u <account_name>] [-t <tenant_id>] [--all]
 ```
 
+**Parameters:**
+
+- `-u, --username`: Account name of the session to log out. Case-insensitive. Optional.
+- `-t, --tenant`: Tenant ID to disambiguate when the same account exists in multiple tenants. Optional.
+- `--all`: Clear all stored authentication sessions. Optional.
+
+When neither `-u` nor `--all` is provided, the CLI removes the current active session. If other sessions remain, the next most recently used session becomes active.
+
 ---
 
 ### list
 
-List stored user authentication sessions.
+List stored user authentication sessions. Each row shows whether the session is active, the account name, tenant, token validity, and the last used timestamp.
 
 **Usage:**
 
@@ -76,14 +84,25 @@ fab auth status
 
 ### switch
 
-Switch the active stored user authentication session.
+Switch the active stored user authentication session. You can specify the target account directly to avoid interactive selection.
 
 **Usage:**
 
 ```
 fab auth switch [-u <account_name>] [-t <tenant_id>]
 ```
 
+**Parameters:**
+
+- `-u, --username`: Account name to switch to. Case-insensitive. Optional.
+- `-t, --tenant`: Tenant ID to disambiguate when the same account exists in multiple tenants. Optional.
+
+**Behavior:**
+
+- With `-u` (and optionally `-t`): switches directly to the matching session.
+- With two stored sessions and no flags: automatically toggles to the other session.
+- With three or more sessions and no flags: presents an interactive prompt.
+
 ---
 
 For more examples and detailed scenarios, see [Authentication Examples](../../examples/auth_examples.md).

docs/examples/auth_examples.md

@@ -131,16 +131,40 @@ fab auth list
 
 ### Switch to another stored user session
 
+When two sessions are stored, `switch` automatically toggles to the other account:
+
 ```
 fab auth switch
 ```
 
+With three or more sessions and no flags, an interactive prompt is shown.
+
+### Switch directly to a specific stored account
+
+Account name matching is case-insensitive:
+
+```
+fab auth switch -u alice@example.com
+```
+
 ### Switch directly to a specific stored account and tenant
 
 ```
 fab auth switch -u <account_name> -t <tenant_id>
 ```
 
+### Log out a specific stored session
+
+```
+fab auth logout -u alice@example.com
+```
+
+### Log out all stored sessions
+
+```
+fab auth logout --all
+```
+
 
 ## Authentication Status
 

src/fabric_cli/commands/auth/fab_auth.py

@@ -356,14 +356,21 @@ def list_accounts(args: Namespace) -> None:
     active_session = auth.get_active_user_session()
     active_session_id = active_session.get("session_id") if active_session else None
 
+    # Cache one MSAL app per tenant to avoid redundant app creation during validation.
+    tenant_apps: dict[str, Any] = {}
     rows = []
     for session in sessions:
+        tid = session.get("tenant_id")
+        if tid not in tenant_apps:
+            tenant_apps[tid] = auth._create_user_app(tid)
         rows.append(
             {
                 "active": str(session.get("session_id") == active_session_id).lower(),
                 "account": session.get("account_name", "Unknown"),
                 "tenant_id": session.get("tenant_id", "Unknown"),
-                "valid": str(auth.is_user_session_valid(session)).lower(),
+                "valid": str(
+                    auth.is_user_session_valid(session, app=tenant_apps[tid])
+                ).lower(),
                 "last_used_at": session.get("last_used_at", ""),
             }
         )
@@ -428,8 +435,9 @@ def _resolve_user_session(
     active_session_id = active_session.get("session_id") if active_session else None
 
     candidates = []
+    username_lower = username.lower() if username else None
     for session in sessions:
-        if username and session.get("account_name") != username:
+        if username_lower and (session.get("account_name") or "").lower() != username_lower:
             continue
         if tenant_id and session.get("tenant_id") != tenant_id:
             continue

src/fabric_cli/core/fab_auth.py

@@ -5,7 +5,7 @@
 import os
 import uuid
 from binascii import hexlify
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import Any, NamedTuple, Optional
 
 import jwt
@@ -263,7 +263,9 @@ def _get_matching_account(
             accounts = (
                 app.get_accounts(account_name) if account_name else app.get_accounts()
             )
-        except TypeError:
+        except TypeError as e:
+            # MSAL may not accept a username filter in all broker configurations.
+            fab_logger.log_debug(f"Filtered get_accounts failed, retrying unfiltered: {e}")
             accounts = app.get_accounts()
 
         if not isinstance(accounts, list):
@@ -295,7 +297,8 @@ def _get_matching_account(
         if tenant_id:
             try:
                 all_accounts = app.get_accounts()
-            except TypeError:
+            except TypeError as e:
+                fab_logger.log_debug(f"get_accounts failed during tenant fallback: {e}")
                 all_accounts = []
 
             if not isinstance(all_accounts, list):
@@ -361,7 +364,12 @@ def _build_current_user_session_from_cache(self) -> Optional[dict[str, Any]]:
 
     @staticmethod
     def _utc_now() -> str:
-        return datetime.utcnow().replace(microsecond=0).isoformat() + "Z"
+        return (
+            datetime.now(timezone.utc)
+            .replace(microsecond=0)
+            .isoformat()
+            .replace("+00:00", "Z")
+        )
 
     def _build_user_session(
         self,
@@ -465,9 +473,13 @@ def _sync_active_user_session(self, save: bool = True) -> Optional[dict[str, Any
                 self._save_auth()
             return None
 
-        self.app = None
+        # Only reset the MSAL app when the tenant changes so that the active
+        # WAM broker session is preserved during the login flow.
+        new_tenant = session.get("tenant_id")
+        if self._auth_info.get(con.FAB_TENANT_ID) != new_tenant:
+            self.app = None
         self._auth_info[con.IDENTITY_TYPE] = "user"
-        self._auth_info[con.FAB_TENANT_ID] = session.get("tenant_id")
+        self._auth_info[con.FAB_TENANT_ID] = new_tenant
         self._auth_info[ACTIVE_USER_ACCOUNT_NAME_KEY] = session.get("account_name")
 
         if session.get("home_account_id"):
@@ -619,9 +631,14 @@ def remove_user_session(self, session_id: str) -> Optional[dict[str, Any]]:
         self._save_auth()
         return self._find_user_session()
 
-    def is_user_session_valid(self, session: dict[str, Any]) -> bool:
+    def is_user_session_valid(
+        self,
+        session: dict[str, Any],
+        app: Optional[msal.PublicClientApplication] = None,
+    ) -> bool:
         try:
-            app = self._create_user_app(session.get("tenant_id"))
+            if app is None:
+                app = self._create_user_app(session.get("tenant_id"))
             account = self._get_matching_account(app, session)
             if account is None:
                 return False
@@ -782,7 +799,11 @@ def set_access_mode(self, mode, tenant_id=None):
     def set_tenant(self, tenant_id):
         if tenant_id is not None:
             if self.get_identity_type() == "user":
-                self.app = None
+                # Only reset the MSAL app when the tenant actually changes so
+                # that the active WAM broker session is preserved across scope
+                # requests during login.
+                if self.get_tenant_id() != tenant_id:
+                    self.app = None
                 self._set_auth_properties(
                     {
                         con.FAB_TENANT_ID: tenant_id,
@@ -959,6 +980,8 @@ def acquire_token(
                     scopes=scope, account=account
                 )
 
+            # When force_interactive=True the silent block above is skipped so token
+            # remains None, falling through here to trigger the interactive prompt.
             if token is None and interactive_renew and identity_type == "user":
                 token = self._get_app().acquire_token_interactive(
                     scopes=scope,
@@ -975,6 +998,7 @@ def acquire_token(
                     if session is not None:
                         self._persist_user_session(session)
             elif token and active_session is not None and not force_interactive:
+                # Silent acquisition succeeded — update the session timestamp.
                 self._persist_user_session(active_session)
 
         if token and token.get("error"):

tests/test_commands/test_auth.py

@@ -1044,6 +1044,149 @@ def test_auth_logout_user_session(self, mock_fab_auth, mock_fab_context):
         mock_fab_context_instance.reset_context.assert_called_once()
         mock_print.assert_called_once()
 
+    def test_auth_list_no_sessions(self, mock_fab_auth):
+        args = argparse.Namespace(command="auth", output_format=None)
+        mock_fab_auth_instance = mock_fab_auth.get("instance")
+        mock_fab_auth_instance.get_user_sessions.return_value = []
+
+        with patch(
+            "fabric_cli.commands.auth.fab_auth.fab_ui.print_output_format"
+        ) as mock_print:
+            fab_auth.list_accounts(args)
+
+        mock_print.assert_called_once()
+        assert "message" in mock_print.call_args.kwargs
+
+    def test_auth_switch_env_vars_blocks(self, mock_fab_auth):
+        args = argparse.Namespace(
+            command="auth",
+            output_format=None,
+            username=None,
+            tenant=None,
+        )
+        with patch.dict(os.environ, {"FAB_TOKEN": "some-token"}):
+            with pytest.raises(FabricCLIError) as exc_info:
+                fab_auth.switch(args)
+            assert exc_info.value.status_code == fab_constant.ERROR_INVALID_OPERATION
+
+    def test_auth_switch_case_insensitive_username(self, mock_fab_auth, mock_fab_context):
+        args = argparse.Namespace(
+            command="auth",
+            output_format=None,
+            username="ALICE@EXAMPLE.COM",
+            tenant=None,
+        )
+        mock_fab_auth_instance = mock_fab_auth.get("instance")
+        mock_fab_auth_instance.get_user_sessions.return_value = [
+            {
+                "session_id": "session-a",
+                "account_name": "alice@example.com",
+                "tenant_id": "tenant-a",
+                "last_used_at": "2026-04-07T12:00:00Z",
+            }
+        ]
+        mock_fab_auth_instance.get_active_user_session.return_value = {
+            "session_id": "session-a"
+        }
+
+        with patch(
+            "fabric_cli.commands.auth.fab_auth.fab_ui.print_output_format"
+        ):
+            fab_auth.switch(args)
+
+        mock_fab_auth_instance.activate_user_session.assert_called_once_with(
+            "session-a"
+        )
+
+    def test_auth_switch_interactive_prompt_with_three_accounts(
+        self, mock_fab_auth, mock_fab_context
+    ):
+        args = argparse.Namespace(
+            command="auth",
+            output_format=None,
+            username=None,
+            tenant=None,
+        )
+        mock_fab_auth_instance = mock_fab_auth.get("instance")
+        mock_fab_auth_instance.get_user_sessions.return_value = [
+            {
+                "session_id": "session-a",
+                "account_name": "alice@example.com",
+                "tenant_id": "tenant-a",
+                "last_used_at": "2026-04-07T12:00:00Z",
+            },
+            {
+                "session_id": "session-b",
+                "account_name": "bob@example.com",
+                "tenant_id": "tenant-b",
+                "last_used_at": "2026-04-06T12:00:00Z",
+            },
+            {
+                "session_id": "session-c",
+                "account_name": "carol@example.com",
+                "tenant_id": "tenant-c",
+                "last_used_at": "2026-04-05T12:00:00Z",
+            },
+        ]
+        mock_fab_auth_instance.get_active_user_session.return_value = {
+            "session_id": "session-a"
+        }
+
+        with (
+            patch(
+                "fabric_cli.commands.auth.fab_auth.fab_ui.prompt_select_item",
+                return_value="bob@example.com (tenant-b)",
+            ),
+            patch(
+                "fabric_cli.commands.auth.fab_auth.fab_ui.print_output_format"
+            ),
+        ):
+            fab_auth.switch(args)
+
+        mock_fab_auth_instance.activate_user_session.assert_called_once_with(
+            "session-b"
+        )
+
+    def test_auth_switch_cancelled_prompt(self, mock_fab_auth):
+        args = argparse.Namespace(
+            command="auth",
+            output_format=None,
+            username=None,
+            tenant=None,
+        )
+        mock_fab_auth_instance = mock_fab_auth.get("instance")
+        mock_fab_auth_instance.get_user_sessions.return_value = [
+            {
+                "session_id": "session-a",
+                "account_name": "alice@example.com",
+                "tenant_id": "tenant-a",
+                "last_used_at": "2026-04-07T12:00:00Z",
+            },
+            {
+                "session_id": "session-b",
+                "account_name": "bob@example.com",
+                "tenant_id": "tenant-b",
+                "last_used_at": "2026-04-06T12:00:00Z",
+            },
+            {
+                "session_id": "session-c",
+                "account_name": "carol@example.com",
+                "tenant_id": "tenant-c",
+                "last_used_at": "2026-04-05T12:00:00Z",
+            },
+        ]
+        mock_fab_auth_instance.get_active_user_session.return_value = {
+            "session_id": "session-a"
+        }
+
+        with patch(
+            "fabric_cli.commands.auth.fab_auth.fab_ui.prompt_select_item",
+            return_value=None,
+        ):
+            with pytest.raises(FabricCLIError) as exc_info:
+                fab_auth.switch(args)
+            assert exc_info.value.status_code == fab_constant.ERROR_OPERATION_CANCELLED
+
     def test_init_when_user_cancels_the_prompt(
         self, mock_fab_auth, mock_fab_context, mock_fab_logger_log_warning, capsys
     ):