feat: add --use-device-code flag to auth login

Add device code authentication flow for environments where browser
access is not available. Users can now authenticate by entering a code
at https://microsoft.com/devicelogin from any device with a browser.

Usage:
  fab auth login --use-device-code
  fab auth login --use-device-code --tenant <tenant_id>

The option is also available in the interactive authentication menu
as "Device code".

Implementation:
- Add --use-device-code argument to the auth login parser
- Add _acquire_token_by_device_code() using MSAL's initiate_device_flow
  and acquire_token_by_device_flow APIs
- Add device_code_flow_failed() error message
- Wrap device code flow in try/finally to ensure flag cleanup on failure
- Use silent refresh for subsequent scopes after initial device code auth

Assisted-by: GitHub Copilot:claude-opus-4.6

Author: iemejia

.changes/unreleased/added-20260630-223439.yaml

@@ -0,0 +1,6 @@
+kind: added
+body: Add ``--use-device-code`` flag to ``auth login`` for device code authentication flow
+time: 2026-06-30T22:34:39.210039642+02:00
+custom:
+    Author: iemejia
+    AuthorLink: https://github.com/iemejia

src/fabric_cli/commands/auth/fab_auth.py

@@ -16,6 +16,7 @@
 def init(args: Namespace) -> Any:
     auth_options = [
         "Interactive with a web browser",
+        "Device code",
         "Service principal authentication with secret",
         "Service principal authentication with certificate",
         "Service principal authentication with federated credential",
@@ -27,7 +28,15 @@ def init(args: Namespace) -> Any:
     # Clean up stale context files when logging in
     Context().cleanup_context_files(cleanup_all_stale=True, cleanup_current=False)
 
-    if args.identity:
+    if args.use_device_code:
+        FabAuth().set_access_mode("user", args.tenant)
+        with FabAuth().device_code_flow():
+            FabAuth().get_access_token(scope=fab_constant.SCOPE_FABRIC_DEFAULT)
+            FabAuth().get_access_token(scope=fab_constant.SCOPE_ONELAKE_DEFAULT)
+            FabAuth().get_access_token(scope=fab_constant.SCOPE_AZURE_DEFAULT)
+        Context().context = FabAuth().get_tenant()
+
+    elif args.identity:
         FabAuth().set_access_mode("managed_identity")
         FabAuth().set_managed_identity(args.username)
         FabAuth().get_access_token(scope=fab_constant.SCOPE_FABRIC_DEFAULT)
@@ -73,6 +82,13 @@ def init(args: Namespace) -> Any:
                 FabAuth().get_access_token(scope=fab_constant.SCOPE_ONELAKE_DEFAULT)
                 FabAuth().get_access_token(scope=fab_constant.SCOPE_AZURE_DEFAULT)
                 Context().context = FabAuth().get_tenant()
+            elif selected_auth == "Device code":
+                FabAuth().set_access_mode("user", args.tenant)
+                with FabAuth().device_code_flow():
+                    FabAuth().get_access_token(scope=fab_constant.SCOPE_FABRIC_DEFAULT)
+                    FabAuth().get_access_token(scope=fab_constant.SCOPE_ONELAKE_DEFAULT)
+                    FabAuth().get_access_token(scope=fab_constant.SCOPE_AZURE_DEFAULT)
+                Context().context = FabAuth().get_tenant()
             elif selected_auth.startswith("Service principal authentication"):
                 fab_logger.log_warning(
                     "Ensure tenant setting is enabled for Service Principal auth"

src/fabric_cli/core/fab_auth.py

@@ -5,6 +5,7 @@
 import os
 import uuid
 from binascii import hexlify
+from contextlib import contextmanager
 from typing import Any, NamedTuple, Optional
 
 import jwt
@@ -50,11 +51,30 @@ def __init__(self):
         # Reset the auth info
         self.app: msal.ClientApplication = None
         self._auth_info = {}
+        self._use_device_code = False
 
         # Load the auth info and environment variables
         self._load_auth()
         self._load_env()
 
+    @contextmanager
+    def device_code_flow(self):
+        """Context manager to enable device code authentication flow.
+
+        Temporarily enables device code flow for token acquisition within
+        the context block. Automatically resets the flag on exit, even if
+        an exception occurs.
+
+        Usage:
+            with FabAuth().device_code_flow():
+                FabAuth().get_access_token(scope=...)
+        """
+        self._use_device_code = True
+        try:
+            yield
+        finally:
+            self._use_device_code = False
+
     def _save_auth(self):
         from fabric_cli.utils.fab_secure_io import write_restricted_file
 
@@ -270,6 +290,52 @@ def _get_app(self) -> msal.ClientApplication:
                 )
         return self.app
 
+    def _acquire_token_by_device_code(self, scope: list[str]) -> dict:
+        """
+        Acquire a token using the device code flow.
+
+        This initiates a device code flow, prints the user code and verification
+        URL to the console, and waits for the user to complete authentication
+        on another device. If an account already exists in the cache (from a
+        prior device code flow in the same session), attempts a silent refresh
+        first to avoid prompting the user multiple times for different scopes.
+
+        Args:
+            scope: The scopes for which to request the token
+
+        Returns:
+            Full MSAL result dictionary containing access_token, expires_on, etc.
+
+        Raises:
+            FabricCLIError: When device code flow initiation or token acquisition fails
+        """
+        # If we already have an account from a prior device code auth in this
+        # session, try silent acquisition with force_refresh to use the refresh
+        # token for a different resource scope.
+        accounts = self._get_app().get_accounts()
+        if accounts:
+            token = self._get_app().acquire_token_silent(
+                scopes=scope, account=accounts[0], force_refresh=True
+            )
+            if token and token.get("access_token"):
+                return token
+
+        flow = self._get_app().initiate_device_flow(scopes=scope)
+        if "user_code" not in flow:
+            raise FabricCLIError(
+                ErrorMessages.Auth.device_code_flow_failed(
+                    flow.get("error_description", "Unknown error")
+                ),
+                con.ERROR_AUTHENTICATION_FAILED,
+            )
+
+        # Display the device code message to the user
+        utils_ui.print_grey(flow["message"])
+
+        # Wait for the user to authenticate
+        token = self._get_app().acquire_token_by_device_flow(flow)
+        return token
+
     def _get_access_token_from_env_vars_if_exist(self, scope):
         if "FAB_TOKEN" in os.environ and "FAB_TOKEN_ONELAKE" in os.environ:
             match scope:
@@ -494,12 +560,15 @@ def acquire_token(self, scope: list[str], interactive_renew=True) -> dict:
                     scopes=scope, account=account
                 )
 
-                if token is None and interactive_renew:
-                    token = self._get_app().acquire_token_interactive(
-                        scopes=scope,
-                        prompt="select_account",
-                        parent_window_handle=msal.PublicClientApplication.CONSOLE_WINDOW_HANDLE,
-                    )
+                if (token is None or token.get("error")) and interactive_renew:
+                    if self._use_device_code:
+                        token = self._acquire_token_by_device_code(scope)
+                    else:
+                        token = self._get_app().acquire_token_interactive(
+                            scopes=scope,
+                            prompt="select_account",
+                            parent_window_handle=msal.PublicClientApplication.CONSOLE_WINDOW_HANDLE,
+                        )
                     if token is not None and "id_token_claims" in token:
                         self.set_tenant(token.get("id_token_claims")["tid"])
 

src/fabric_cli/errors/auth.py

@@ -119,3 +119,7 @@ def cert_read_failed(error: str) -> str:
     @staticmethod
     def only_supported_with_user_authentication() -> str:
         return "This operation is only supported with user authentication"
+
+    @staticmethod
+    def device_code_flow_failed(error_description: str) -> str:
+        return f"Failed to initiate device code flow: {error_description}"

src/fabric_cli/parsers/fab_auth_parser.py

@@ -30,6 +30,8 @@ def register_parser(subparsers: _SubParsersAction) -> None:
         "$ auth login\n",
         "# command_line mode",
         "$ fab auth login\n",
+        "# command_line mode using device code auth",
+        "$ fab auth login --use-device-code\n",
         "# command_line mode using service principal auth",
         "$ fab auth login -u <client_id> -p <client_secret> --tenant <tenant_id>\n",
         "# command_line mode using system assigned managed identity auth",
@@ -84,9 +86,15 @@ def register_parser(subparsers: _SubParsersAction) -> None:
         required=False,
         help="Federated token that can be used for OIDC token exchange. Optional, only for service principal auth",
     )
+    login_parser.add_argument(
+        "--use-device-code",
+        required=False,
+        action="store_true",
+        help="Use device code authentication flow. Useful when browser access is not available.",
+    )
 
     login_parser.usage = f"{utils_error_parser.get_usage_prog(login_parser)}"
-    login_parser.set_defaults(func=lazy_command(_auth_module_path, 'init'))
+    login_parser.set_defaults(func=lazy_command(_auth_module_path, "init"))
 
     # Subcommand for 'logout'
     logout_examples = [
@@ -104,7 +112,7 @@ def register_parser(subparsers: _SubParsersAction) -> None:
     )
 
     logout_parser.usage = f"{utils_error_parser.get_usage_prog(logout_parser)}"
-    logout_parser.set_defaults(func=lazy_command(_auth_module_path, 'logout'))
+    logout_parser.set_defaults(func=lazy_command(_auth_module_path, "logout"))
 
     # Subcommand for 'status'
     status_examples = [
@@ -121,7 +129,7 @@ def register_parser(subparsers: _SubParsersAction) -> None:
     )
 
     status_parser.usage = f"{utils_error_parser.get_usage_prog(status_parser)}"
-    status_parser.set_defaults(func=lazy_command(_auth_module_path, 'status'))
+    status_parser.set_defaults(func=lazy_command(_auth_module_path, "status"))
 
 
 def show_help(args: Namespace) -> None:

tests/test_commands/test_auth.py

@@ -811,6 +811,155 @@ def test_init_with_tenant_and_cert_args_auth(
             name="Unknown", id="mocked_tenant_id"
         )
 
+    def test_init_with_device_code_auth_command_line(
+        self, mock_fab_auth, mock_fab_context
+    ):
+        # Arrange
+        args = prepare_auth_args({"use_device_code": True})
+
+        # Act
+        result = fab_auth.init(args)
+
+        # Assert
+        mock_fab_auth_instance = mock_fab_auth.get("instance")
+        mock_fab_auth_instance.set_access_mode.assert_called_with("user", None)
+        assert_get_access_token(mock_fab_auth_instance)
+        assert result is True
+
+        assert_fab_context(mock_fab_context)
+
+    def test_init_with_device_code_auth_command_line_with_tenant(
+        self, mock_fab_auth, mock_fab_context
+    ):
+        # Arrange
+        args = prepare_auth_args({"use_device_code": True, "tenant": "mock_tenant"})
+
+        # Act
+        result = fab_auth.init(args)
+
+        # Assert
+        mock_fab_auth_instance = mock_fab_auth.get("instance")
+        mock_fab_auth_instance.set_access_mode.assert_called_with("user", "mock_tenant")
+        assert_get_access_token(mock_fab_auth_instance)
+        assert result is True
+
+        assert_fab_context(mock_fab_context)
+
+    def test_init_with_device_code_auth_interactive(
+        self, mock_fab_auth, mock_fab_context
+    ):
+        # Arrange
+        with patch(
+            "fabric_cli.utils.fab_ui.prompt_select_item",
+            return_value="Device code",
+        ):
+            args = prepare_auth_args()
+
+            # Act
+            result = fab_auth.init(args)
+
+            # Assert
+            mock_fab_auth_instance = mock_fab_auth.get("instance")
+            mock_fab_auth_instance.set_access_mode.assert_called_with("user", None)
+            assert_get_access_token(mock_fab_auth_instance)
+            assert result is True
+
+            assert_fab_context(mock_fab_context)
+
+    def test_init_with_device_code_takes_precedence_over_identity(
+        self, mock_fab_auth, mock_fab_context
+    ):
+        """When both --use-device-code and --identity are passed, device code wins."""
+        # Arrange
+        args = prepare_auth_args({"use_device_code": True, "identity": True})
+
+        # Act
+        result = fab_auth.init(args)
+
+        # Assert: device code path was taken (set_access_mode("user")), not managed identity
+        mock_fab_auth_instance = mock_fab_auth.get("instance")
+        mock_fab_auth_instance.set_access_mode.assert_called_with("user", None)
+        mock_fab_auth_instance.set_managed_identity.assert_not_called()
+        assert_get_access_token(mock_fab_auth_instance)
+        assert result is True
+
+        assert_fab_context(mock_fab_context)
+
+    def test_init_with_device_code_takes_precedence_over_spn_args(
+        self, mock_fab_auth, mock_fab_context
+    ):
+        """When --use-device-code is passed alongside -u/-p, device code wins."""
+        # Arrange
+        args = prepare_auth_args(
+            {
+                "use_device_code": True,
+                "username": "some_client_id",
+                "password": "some_secret",
+                "tenant": "some_tenant",
+            }
+        )
+
+        # Act
+        result = fab_auth.init(args)
+
+        # Assert: device code path was taken, not SPN
+        mock_fab_auth_instance = mock_fab_auth.get("instance")
+        mock_fab_auth_instance.set_access_mode.assert_called_with("user", "some_tenant")
+        mock_fab_auth_instance.set_spn.assert_not_called()
+        assert_get_access_token(mock_fab_auth_instance)
+        assert result is True
+
+        assert_fab_context(mock_fab_context)
+
+    def test_init_with_device_code_resets_flag_on_success(
+        self, mock_fab_auth, mock_fab_context
+    ):
+        """Verify _use_device_code flag is reset to False after successful login."""
+        # Arrange
+        args = prepare_auth_args({"use_device_code": True})
+
+        # Act
+        fab_auth.init(args)
+
+        # Assert: flag should be reset
+        mock_fab_auth_instance = mock_fab_auth.get("instance")
+        assert mock_fab_auth_instance._use_device_code is False
+
+    def test_init_with_device_code_resets_flag_on_exception(self, mock_fab_auth):
+        """Verify _use_device_code flag is reset even when get_access_token raises."""
+        # Arrange
+        mock_fab_auth_instance = mock_fab_auth.get("instance")
+        mock_fab_auth_instance.get_access_token.side_effect = FabricCLIError(
+            "Token acquisition failed",
+            fab_constant.ERROR_AUTHENTICATION_FAILED,
+        )
+        args = prepare_auth_args({"use_device_code": True})
+
+        # Act
+        with pytest.raises(FabricCLIError):
+            fab_auth.init(args)
+
+        # Assert: flag should be reset thanks to try/finally
+        assert mock_fab_auth_instance._use_device_code is False
+
+    def test_init_with_device_code_interactive_resets_flag_on_success(
+        self, mock_fab_auth, mock_fab_context
+    ):
+        """Verify _use_device_code flag is reset after interactive device code login."""
+        # Arrange
+        with patch(
+            "fabric_cli.utils.fab_ui.prompt_select_item",
+            return_value="Device code",
+        ):
+            args = prepare_auth_args()
+
+            # Act
+            fab_auth.init(args)
+
+            # Assert: flag should be reset
+            mock_fab_auth_instance = mock_fab_auth.get("instance")
+            assert mock_fab_auth_instance._use_device_code is False
+
     def test_init_with_args_auth_missing_arg_raise_exception(self):
         # Test without tenant
         # Arrange
@@ -821,6 +970,7 @@ def test_init_with_args_auth_missing_arg_raise_exception(self):
             identity=None,
             certificate=None,
             federated_token=None,
+            use_device_code=None,
         )
 
         # Act
@@ -837,6 +987,7 @@ def test_init_with_args_auth_missing_arg_raise_exception(self):
             identity=None,
             certificate=None,
             federated_token=None,
+            use_device_code=None,
         )
 
         # Act
@@ -853,6 +1004,7 @@ def test_init_with_args_auth_missing_arg_raise_exception(self):
             identity=None,
             certificate=None,
             federated_token=None,
+            use_device_code=None,
         )
 
         # Act
@@ -971,6 +1123,7 @@ def prepare_auth_args(args=None):
                 "identity",
                 "certificate",
                 "federated_token",
+                "use_device_code",
             ]
         }
     )