feat(auth): add non-interactive login helper and docs

Author: richardogundele

README.md

@@ -203,6 +203,10 @@ If you would like to get builds of arbitrary commit or PR, see:
 
 [Try new features before release](doc/try_new_features_before_release.md)
 
+### Non-interactive authentication for automation
+
+We've added a short guide and helper script for non-interactive authentication (service principal, managed identity, workload identity) used by CI/CD and headless servers. See `doc/non_interactive_auth.md` and `scripts/non_interactive_login.py` for examples and secure patterns.
+
 ## Developer setup
 
 If you would like to setup a development environment and contribute to the CLI, see:

doc/non_interactive_auth.md

@@ -0,0 +1,73 @@
+# Non-interactive authentication for Azure CLI
+
+This document explains recommended non-interactive authentication modes for automation (CI/CD, scripts, headless servers) and provides safe examples and a small helper script.
+
+Supported modes
+
+- Service Principal (client secret) — recommended for CI systems where a secret can be stored securely.
+- Managed Identity (MSI) — recommended when running inside Azure (VM, VMSS, App Service, Function) and you can assign a managed identity.
+- Device Code — useful for ad-hoc non-browser sign-ins when interactive approval is acceptable.
+- Workload Identity — recommended for Kubernetes-based workloads using federated credentials.
+
+Environment variables
+
+The helper scripts and CI examples below use the following environment variables (common conventions):
+
+- AZURE_AUTH_MODE: one of `service-principal`, `managed-identity`, `device-code`, `workload-identity` (optional; script will try to auto-detect)
+- AZURE_CLIENT_ID
+- AZURE_CLIENT_SECRET
+- AZURE_TENANT_ID
+- AZURE_FEDERATED_TOKEN_FILE (for workload identity / token file)
+
+Security guidance
+
+- Store secrets in your CI secret store (GitHub Secrets, Azure DevOps variable groups, etc.).
+- Prefer managed identities or workload identity federation where possible to avoid long-lived secrets.
+- Limit permissions using least-privilege service principals.
+
+Examples
+
+Service principal (GitHub Actions)
+
+```yaml
+# GitHub Actions snippet
+env:
+  AZURE_CLIENT_ID: ${{ secrets.AZURE_CLIENT_ID }}
+  AZURE_CLIENT_SECRET: ${{ secrets.AZURE_CLIENT_SECRET }}
+  AZURE_TENANT_ID: ${{ secrets.AZURE_TENANT_ID }}
+
+steps:
+- name: Install Azure CLI
+  uses: azure/CLI@v1
+
+- name: Login with service principal
+  run: az login --service-principal -u "$AZURE_CLIENT_ID" -p "$AZURE_CLIENT_SECRET" --tenant "$AZURE_TENANT_ID"
+```
+
+Managed Identity (Azure VM / App Service)
+
+On an Azure VM with a system-assigned or user-assigned managed identity you can run:
+
+```bash
+az login --identity
+```
+
+Device code (interactive)
+
+```bash
+az login --use-device-code
+```
+
+Workload identity (Kubernetes with federated credentials)
+
+Use Azure AD Workload Identity or federated credential to obtain a token and then use `az account get-access-token` or configure the environment according to your runtime. For CI that provides a token file, a short helper can run `az login --federated-token` style workflows; see the example helper script in `scripts/non_interactive_login.py`.
+
+Helper script
+
+A small helper script `scripts/non_interactive_login.py` is included that demonstrates safe detection of environment variables and returns the recommended `az login` command for common automation scenarios. The script is intentionally conservative and does not run `az` by default in unit tests.
+
+Further reading
+
+- https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal
+- https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview
+- https://learn.microsoft.com/azure/aks/workload-identity-overview

scripts/non_interactive_login.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""
+Helper for non-interactive Azure CLI login in CI and automation.
+This script prints the recommended `az login` command for the detected environment.
+It does not execute commands by default to keep unit testing simple and safe.
+"""
+import os
+import sys
+import argparse
+
+
+def detect_mode(env=os.environ):
+    if env.get("AZURE_CLIENT_ID") and env.get("AZURE_CLIENT_SECRET") and env.get("AZURE_TENANT_ID"):
+        return "service-principal"
+    if env.get("AZURE_FEDERATED_TOKEN_FILE"):
+        return "workload-identity"
+    if env.get("AZURE_CLIENT_ID") and env.get("AZURE_FEDERATED_TOKEN_FILE"):
+        return "workload-identity"
+    if env.get("AZURE_USE_MANAGED_IDENTITY") == "true" or env.get("MSI_ENDPOINT"):
+        return "managed-identity"
+    return "unknown"
+
+
+def build_command(mode, env=os.environ):
+    if mode == "service-principal":
+        return (
+            f"az login --service-principal -u \"{env.get('AZURE_CLIENT_ID')}\" -p \"{env.get('AZURE_CLIENT_SECRET')}\" --tenant \"{env.get('AZURE_TENANT_ID')}\""
+        )
+    if mode == "workload-identity":
+        # Assumes federated token file path in AZURE_FEDERATED_TOKEN_FILE
+        token_file = env.get("AZURE_FEDERATED_TOKEN_FILE")
+        if token_file:
+            return f"az login --federated-token @\"{token_file}\" --allow-no-subscriptions"
+        return "# workload-identity detected but AZURE_FEDERATED_TOKEN_FILE not set"
+    if mode == "managed-identity":
+        return "az login --identity"
+    return "# Unable to detect non-interactive auth mode. Use 'az login --help'"
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Detect environment and print recommended az login command.")
+    parser.add_argument("--run", action="store_true", help="Execute the suggested az login command")
+    args = parser.parse_args()
+
+    mode = detect_mode()
+    cmd = build_command(mode)
+    print(f"Detected mode: {mode}")
+    print(cmd)
+
+    if args.run:
+        print("Execution requested. Running the command...")
+        rc = os.system(cmd)
+        sys.exit(rc)
+
+
+if __name__ == "__main__":
+    main()

src/tests/test_non_interactive_login.py

@@ -0,0 +1,45 @@
+import os
+import tempfile
+import pytest
+from scripts import non_interactive_login as nil
+
+
+def test_detect_service_principal(monkeypatch):
+    monkeypatch.setenv("AZURE_CLIENT_ID", "cid")
+    monkeypatch.setenv("AZURE_CLIENT_SECRET", "secret")
+    monkeypatch.setenv("AZURE_TENANT_ID", "tid")
+    assert nil.detect_mode() == "service-principal"
+
+
+def test_detect_workload_identity(monkeypatch, tmp_path):
+    token_file = tmp_path / "token.txt"
+    token_file.write_text("token")
+    monkeypatch.setenv("AZURE_FEDERATED_TOKEN_FILE", str(token_file))
+    assert nil.detect_mode() == "workload-identity"
+
+
+def test_detect_managed_identity(monkeypatch):
+    monkeypatch.setenv("AZURE_USE_MANAGED_IDENTITY", "true")
+    assert nil.detect_mode() == "managed-identity"
+
+
+def test_build_command_service_principal(monkeypatch):
+    monkeypatch.setenv("AZURE_CLIENT_ID", "cid")
+    monkeypatch.setenv("AZURE_CLIENT_SECRET", "secret")
+    monkeypatch.setenv("AZURE_TENANT_ID", "tid")
+    cmd = nil.build_command("service-principal")
+    assert "az login --service-principal" in cmd
+    assert "cid" in cmd
+
+
+def test_build_command_workload_identity(monkeypatch, tmp_path):
+    token_file = tmp_path / "token.txt"
+    token_file.write_text("token")
+    monkeypatch.setenv("AZURE_FEDERATED_TOKEN_FILE", str(token_file))
+    cmd = nil.build_command("workload-identity")
+    assert "--federated-token" in cmd
+
+
+def test_build_command_managed_identity():
+    cmd = nil.build_command("managed-identity")
+    assert cmd == "az login --identity"