docs: clarify auth strategies and fix misleading security note

- README: restructure Authentication section to separate GitHub Actions
  OIDC path (no client secret) from local CLI / other CI (client secret,
  managed identity). Removes conflation of managed identity with the
  --client-secret flag path.
- identity-guide-service: replace "Rotate service principal credentials
  periodically" with an accurate note that OIDC has no stored credentials
  to rotate.

Agent-Logs-Url: https://github.com/Azure/apiops-cli/sessions/6c946379-655e-4831-a343-bbb3030e4fdb

Co-authored-by: petehauge <12090616+petehauge@users.noreply.github.com>

Author: Copilot

README.md

@@ -17,12 +17,21 @@ npm install -g apiops
 
 ## Authentication
 
-`apiops` uses [`@azure/identity`](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity) `DefaultAzureCredential` for authentication:
+`apiops` uses [`@azure/identity`](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/identity/identity) `DefaultAzureCredential` for authentication.
 
-- To use environment variables, set the following variables: `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`, and `AZURE_SUBSCRIPTION_ID`
-- To specify authentication in command, use the following flags: `--client-id`, `--client-secret`, `--tenant-id`, and `--subscription-id`
-- **CI/CD:** A service principal with the **API Management Service Contributor** role is recommended.
-- **Azure-hosted environments:** Managed Identity and Workload Identity are also supported.
+### Generated GitHub Actions workflows (`apiops init`)
+
+Workflows scaffolded by `apiops init` authenticate via **OIDC (workload identity federation)** — no client secret is stored or needed. Run `apiops init` and use the generated `identity-setup.prompt.md` to create an Azure AD application with federated credentials for your GitHub repository.
+
+Required repository secrets: `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`
+
+### Local CLI / other CI systems
+
+When running `apiops` outside a GitHub Actions OIDC context you can supply credentials explicitly:
+
+- **Environment variables:** `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`, `AZURE_SUBSCRIPTION_ID`
+- **CLI flags:** `--client-id`, `--client-secret`, `--tenant-id`, `--subscription-id`
+- **Managed Identity / Workload Identity:** Supported automatically via `DefaultAzureCredential` when running on Azure-hosted infrastructure (VMs, App Service, etc.) or in Azure Pipelines with workload identity federation configured.
 
 ## Commands
 

src/services/identity-guide-service.ts

@@ -128,8 +128,8 @@ Test the authentication by running a workflow manually or pushing to main branch
 
 ## Security Notes
 - Use GitHub Environments for production deployments with required reviewers
-- Rotate service principal credentials periodically
-- Review federated credential subjects regularly
+- Review federated credential subjects periodically (no secrets to rotate — OIDC authentication has no stored credentials)
+- Review RBAC role assignments regularly and remove any no longer needed
 - Use least-privilege RBAC assignments
 `;
   }