Setup permissions: replace oauth2PermissionGrants POST with unified /v2.0/adminconsent URL

[sellakumaran]

Summary

a365 setup all / setup permissions no longer calls the Microsoft Graph
oauth2PermissionGrants POST API to grant delegated consent on the agent
blueprint. Instead, the CLI builds a single /v2.0/adminconsent URL that
covers every delegated scope across all configured resources (Observability,
Power Platform, Messaging Bot, custom) and routes all delegated consent
through it.

Why

• oauth2PermissionGrants POST requires DelegatedPermissionGrant.ReadWrite.All
  on the caller's token — a high-privilege permission most setup operators
  don't have, leading to per-resource 403s and partial grants.
• The previous orchestration emitted one consent URL per resource, forcing
  the admin to click through several screens for what is logically one
  decision.
• The unified /v2.0/adminconsent URL works for both GA-and-non-GA callers,
  is the same flow the Entra portal uses, and lands all scopes atomically.

The legacy Phase 2b grant code path is removed entirely; ~280 lines of
orchestration and ~150 lines of associated tests are gone with it.

Also in this PR

• Fix: retry the blueprint application PATCH (identifier URI +
  access_agent_as_user OBO scope) on transient Request_ResourceNotFound.
  New blueprint apps have a Graph write replica that lags the read replica
  by several seconds, so the existing GET propagation check could succeed
  while the immediately following PATCH 404'd, silently leaving the
  blueprint incomplete. Retries are exhausted → SetupValidationException
  with a Re-run: a365 setup blueprint --agent-name <name> mitigation.
• UX: friendlier admin-consent polling when the caller's token lacks
  DelegatedPermissionGrant.Read.All. The CLI now polls Graph every 5s
  in case the read permission becomes available, prints a 30s progress
  update, and responds promptly to Enter or Ctrl+C. The jargon-heavy
  message about oauth2PermissionGrants is demoted to Debug.
• Refactor: extract shared helpers from NonDwBlueprintSetupOrchestrator
  into SetupHelpers; add Helpers/ConsoleHelper.ReadLineCancellable.

Validation

• Build clean (0 warn / 0 err)
• Tests: 1521 passed / 12 skipped / 0 failed, all under 1s
• Live a365 setup all --agent-name MCPPermissionsTest4:
  blueprint PATCH succeeded after replica catch-up, OBO scope added,
  unified consent URL surfaced, canary polling and Enter handling behaved
  as expected.

CHANGELOG.md [Unreleased] updated under ### Fixed and ### Changed.

Admin Consent and S2S Permission Flow — Verified End-to-End

What the CLI configures on the blueprint

An Agent 365 blueprint service principal carries two distinct layers of permissions, both verified in the live run below:

1. Delegated permissions — scopes the blueprint grants to end-user sessions via the Agent Identity inheritance mechanism. These cover what an agent instance can do on behalf of a signed-in user (read mail, send chat, write telemetry, etc.). Consent is tenant-wide and is granted by a GA or Application Administrator completing the browser consent screen that the CLI opens.

2. Application permissions (S2S) — app role assignments granted directly to the blueprint's service principal so it can call APIs as itself (no user in the loop). The Observability API Agent365.Observability.OtelWrite role is the only one configured in this profile. These require AppRoleAssignment.ReadWrite.All to assign via the Graph API.

---

Before this PR — what failed and why

Operation	API called	Required scope on CLI token	Result
Grant delegated consent	POST /v1.0/oauth2PermissionGrants	DelegatedPermissionGrant.ReadWrite.All	403 for any non-GA caller; GA needed it explicitly granted on their token
Assign S2S app role	POST /v1.0/servicePrincipals/{id}/appRoleAssignments	AppRoleAssignment.ReadWrite.All	403 for all callers; operator had to copy-paste and run the PowerShell script manually

Both operations were being attempted programmatically, requiring high-privilege Graph API scopes that the CLI's minimal 7-permission client app does not have and should not have.

---

After this PR — what happens now

Delegated consent: The CLI builds a single /v2.0/adminconsent?client_id=…&scope=… URL covering all required delegated scopes for all resources atomically and opens the browser. A GA or Application Administrator completes the standard Entra consent screen — the same flow the Entra portal uses. The CLI no longer needs DelegatedPermissionGrant.ReadWrite.All on its own token; the privilege is exercised by the human admin in the browser.

Note: Because the CLI client app does not have DelegatedPermissionGrant.Read.All, it cannot programmatically verify that consent was applied after the admin completes the screen. The CLI waits for the operator to press Enter, then continues. Post-setup verification is done via a365 query-entra blueprint-scopes (see output below).

S2S app role assignment: The CLI first tries the Graph API (fast path). On 403, it automatically runs the assignment script via the Microsoft Graph PowerShell SDK (Connect-MgGraph -Scopes 'AppRoleAssignment.ReadWrite.All','Directory.Read.All'). The SDK authenticates via its own well-known app registration ("Microsoft Graph Command Line Tools") and — if those scopes have not already been consented to in the tenant — prompts the operator via device code flow at that point. No manual script copy-paste required.

---

Verified run — 2026-05-21

Command: a365 setup all --agent-name MCPPermissionsTest4
Operator: sellak@agent365002.onmicrosoft.com (Global Administrator)
CLI version: 1.1.188+781b997
Tenant: bc51ddf2-9c8b-45e7-8e08-c7ac238f6520 (agent365002.onmicrosoft.com)

Token scopes used by the CLI

From the scp claim logged at DEBUG level during the run:

AgentIdentity.DeleteRestore.All  AgentIdentity.Read.All
AgentIdentityBlueprint.ReadWrite.All  AgentIdentityBlueprintPrincipal.Create
AgentRegistration.ReadWrite.All  Application.Read.All  User.Read

DelegatedPermissionGrant.ReadWrite.All — absent.
AppRoleAssignment.ReadWrite.All — absent.
The CLI operated entirely within its minimal 7-permission set.

Key log events

Time	Event
12:58:17–19	Blueprint created — MCPPermissionsTest4 Blueprint (ID: 1f6607fc-c27b-4d85-9ea1-f45b5b203b7f)
12:58:25–34	Identifier URI PATCH — attempts 1 and 2 returned 404 (write-replica lag); succeeded on attempt 3
12:58:37–40	Inheritable permissions configured on 4 resources (Microsoft Graph, Work IQ Tools, Observability API, Power Platform API)
12:58:40–55	S2S app role assignment via Graph API — 3 retries on 404 (SP propagation), then 403 (expected — AppRoleAssignment.ReadWrite.All not on CLI token)
12:58:55	PowerShell fallback triggered automatically — device code issued (AYPJDCWVU)
12:59:52	pwsh exited 0 — A365-S2S-OK confirmed — Observability API app role assigned
12:59:52	Browser opened for unified delegated consent URL (all 14 scopes in one request)
13:00:21	Operator confirmed browser consent; CLI continued (consent not auto-verifiable — CLI lacks DelegatedPermissionGrant.Read.All)
13:00:24	Agent identity created, agent registered
13:00:24	Setup completed successfully — all 7 steps

---

Blueprint permissions confirmed via a365 query-entra blueprint-scopes

Run post-setup to confirm consent was applied and app role assignment is in place:

Agent Blueprint ID: 1f6607fc-c27b-4d85-9ea1-f45b5b203b7f

Resource: Microsoft Graph (00000003-0000-0000-c000-000000000000)
  Delegated permissions (8): ChannelMessage.Read.All, ChannelMessage.Send, Chat.ReadWrite,
                              Files.ReadWrite.All, Mail.ReadWrite, Mail.Send,
                              Sites.Read.All, User.Read.All
  Application permissions (0): (none)

Resource: Work IQ Tools (ea9ffc3e-8a23-4a7d-836d-234d7c7565c1)
  Delegated permissions (4): McpServers.Calendar.All, McpServers.Mail.All,
                              McpServers.Teams.All, McpServersMetadata.Read.All
  Application permissions (0): (none)

Resource: Observability API (9b975845-388f-4429-889e-eab1ef63949c)
  Delegated permissions (1): Agent365.Observability.OtelWrite
  Application permissions (1): Agent365.Observability.OtelWrite   <-- assigned via PowerShell fallback

Resource: Power Platform API (8578e004-a5c6-46e7-913e-12f58912df43)
  Delegated permissions (1): Connectivity.Connections.Read
  Application permissions (0): (none)

Summary: 4 of 4 resource(s) have at least one granted permission on the blueprint SP.
Total delegated: 14.  Total application: 1.

Observability API has both delegated and application (S2S) permissions — confirming the PowerShell fallback completed the app role assignment that the Graph API path could not.

---

CLI client app permission set (for reference)

The 7 delegated permissions required on the custom client app registration — no high-privilege admin scopes:

Permission	Purpose
AgentIdentityBlueprint.ReadWrite.All	Blueprint CRUD, client secret, identifier URI, FIC ops
AgentIdentityBlueprintPrincipal.Create	Create the blueprint service principal
AgentIdentity.Read.All	Idempotency check, identity lookup
AgentIdentity.DeleteRestore.All	Cleanup
AgentRegistration.ReadWrite.All	Agent registration
Application.Read.All	Service principal lookup by appId
User.Read	Current user identity for owner/sponsor assignment

[github-actions]

⚠️ Deprecation Warning: The deny-licenses option is deprecated for possible removal in the next major release. For more information, see issue 997.

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[Copilot]

Pull request overview

This PR refactors Agent365 CLI setup permission flows to stop using Graph POST /oauth2PermissionGrants for delegated consent and instead build a unified Entra /v2.0/adminconsent URL covering delegated scopes across all configured resources, while also improving reliability around newly-created blueprint app PATCH propagation.

Changes:

• Replace per-resource delegated consent orchestration (and its PowerShell snippets) with a single combined /v2.0/adminconsent URL for Graph + non-Graph resources.
• Add retry/backoff for blueprint application PATCH operations that can 404 due to write-replica lag, and improve cancellation handling in Graph/auth flows.
• Introduce test hooks to suppress real browser launches/long consent polling, plus a cancellable console input helper used by setup prompts.

Reviewed changes

Copilot reviewed 16 out of 17 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/Tests/Microsoft.Agents.A365.DevTools.Cli.Tests/Helpers/SetupHelpersLogPermissionsActionRequiredTests.cs	New unit tests for the Action Required block output for consent URL + S2S PowerShell.
src/Tests/Microsoft.Agents.A365.DevTools.Cli.Tests/Commands/PermissionsSubcommandTests.cs	Suppresses browser/polling in tests via overrides; adds IDisposable cleanup.
src/Tests/Microsoft.Agents.A365.DevTools.Cli.Tests/Commands/NonDwBlueprintSetupOrchestratorExecuteTests.cs	Removes tests for the retired per-identity oauth2PermissionGrants path.
src/Tests/Microsoft.Agents.A365.DevTools.Cli.Tests/Commands/BatchPermissionsOrchestratorTests.cs	Updates tests for unified consent URL behavior; suppresses browser/polling in tests.
src/Microsoft.Agents.A365.DevTools.Cli/Services/Helpers/AdminConsentHelper.cs	Adds canary-based polling behavior and a test bypass hook; improves UX around lacking grant-read permission.
src/Microsoft.Agents.A365.DevTools.Cli/Services/GraphApiService.cs	Ensures OperationCanceledException is not swallowed during token acquisition.
src/Microsoft.Agents.A365.DevTools.Cli/Services/AuthenticationService.cs	Ensures OperationCanceledException is not wrapped as authentication failure.
src/Microsoft.Agents.A365.DevTools.Cli/Helpers/ConsoleHelper.cs	Adds cancellable Console.ReadLine helper with a test override hook.
src/Microsoft.Agents.A365.DevTools.Cli/Helpers/BrowserHelper.cs	Adds AsyncLocal test override to avoid launching real browsers in tests.
src/Microsoft.Agents.A365.DevTools.Cli/Commands/SetupSubcommands/SetupHelpers.cs	Uses cancellable console input; updates summary logic; adds unified resource identifier/scope helpers; adds LogPermissionsActionRequired helper.
src/Microsoft.Agents.A365.DevTools.Cli/Commands/SetupSubcommands/PermissionsSubcommand.cs	Updates help text; ensures Action Required output includes tenant/blueprint context for standalone subcommands.
src/Microsoft.Agents.A365.DevTools.Cli/Commands/SetupSubcommands/NonDwBlueprintSetupOrchestrator.cs	Removes per-agent-identity delegated grant POST path; relies on blueprint inheritance + admin consent.
src/Microsoft.Agents.A365.DevTools.Cli/Commands/SetupSubcommands/BlueprintSubcommand.cs	Adds retry/backoff around blueprint PATCH operations; throws SetupValidationException after exhaustion.
src/Microsoft.Agents.A365.DevTools.Cli/Commands/SetupSubcommands/BatchPermissionsOrchestrator.cs	Removes oauth2PermissionGrants POST orchestration; builds unified consent URL and uses browser+polling for admins.
src/Microsoft.Agents.A365.DevTools.Cli/Commands/SetupCommand.cs	Refreshes CLI help text to emphasize setup all and clarify role requirements.
CHANGELOG.md	Documents unified consent URL flow and blueprint PATCH retry behavior.
.gitignore	Adds Other/ ignore entry.

Comments suppressed due to low confidence (1)

src/Tests/Microsoft.Agents.A365.DevTools.Cli.Tests/Commands/PermissionsSubcommandTests.cs:70

• Dispose() currently sets up NSubstitute return values on _mockGraphApiService. Stubbing in Dispose is unexpected and ineffective for the tests that just ran, and it makes cleanup code harder to reason about. Move these default Returns(...) calls into the constructor (or remove them if unused) and keep Dispose limited to resetting the test overrides.

    public void Dispose()
    {
        BrowserHelper.OpenUrlOverrideForTests = null;
        AdminConsentHelper.BypassConsentChecksForTests = false;
        GC.SuppressFinalize(this);
        _mockGraphApiService.IsCurrentUserAdminAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns(Microsoft.Agents.A365.DevTools.Cli.Models.RoleCheckResult.Unknown);
        _mockGraphApiService.IsCurrentUserAgentIdAdminAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns(Microsoft.Agents.A365.DevTools.Cli.Models.RoleCheckResult.Unknown);
    }

[Copilot]

Pull request overview

Copilot reviewed 22 out of 23 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

src/Tests/Microsoft.Agents.A365.DevTools.Cli.Tests/Commands/PermissionsSubcommandTests.cs:70

• The stubs for IsCurrentUserAdminAsync / IsCurrentUserAgentIdAdminAsync are currently inside Dispose(), so they run after each test instead of before. Because _mockGraphApiService is a partial substitute, leaving these unstubbed during the test can call the real implementation and trigger auth/Graph calls (or hang CI). Move these .Returns(...) setups into the constructor (or into each test) and keep Dispose() only for resetting AsyncLocal test overrides.

        _mockGraphApiService.IsCurrentUserAdminAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns(Microsoft.Agents.A365.DevTools.Cli.Models.RoleCheckResult.Unknown);
        _mockGraphApiService.IsCurrentUserAgentIdAdminAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns(Microsoft.Agents.A365.DevTools.Cli.Models.RoleCheckResult.Unknown);
    }

[Copilot]

Pull request overview

Copilot reviewed 22 out of 23 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 25 changed files in this pull request and generated 7 comments.

[Copilot]

Pull request overview

Copilot reviewed 24 out of 25 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (2)

src/Microsoft.Agents.A365.DevTools.Cli/Commands/SetupSubcommands/BatchPermissionsOrchestrator.cs:88

• ConfigureAllPermissionsAsync filters out any spec with Scopes.Length == 0 and then uses the filtered list for all phases. That made sense when Phase 2b created OAuth2 grants, but now Phase 2b is S2S app-role assignment; S2S-only specs (empty delegated scopes but non-empty AppRoleScopes) would be dropped and never assigned (or surfaced as Action Required). The filter should keep specs that have delegated scopes OR app-role scopes (and possibly keep inheritable-only specs if those are valid).

        if (specs.Count == 0)
        {
            logger.LogInformation("No permission specs provided — skipping batch permissions configuration.");
            return (true, true, true, null);
        }

        // Filter out specs with no scopes — they would produce empty OAuth2 grants (HTTP 400).
        // This can happen when the MCP manifest is missing or contains no required scopes.
        var effectiveSpecs = specs.Where(s => s.Scopes.Length > 0).ToList();
        if (effectiveSpecs.Count < specs.Count)

src/Tests/Microsoft.Agents.A365.DevTools.Cli.Tests/Commands/PermissionsSubcommandTests.cs:70

• Dispose() sets up new Returns(...) stubs on _mockGraphApiService (IsCurrentUserAdminAsync / IsCurrentUserAgentIdAdminAsync). This has no practical effect (the substitute instance is about to be discarded) and makes it harder to see what the test setup actually is. These stubs should either be removed or moved into the constructor if they are required for the tests.

    public void Dispose()
    {
        BrowserHelper.OpenUrlOverrideForTests = null;
        AdminConsentHelper.BypassConsentChecksForTests = false;
        GC.SuppressFinalize(this);
        _mockGraphApiService.IsCurrentUserAdminAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns(Microsoft.Agents.A365.DevTools.Cli.Models.RoleCheckResult.Unknown);
        _mockGraphApiService.IsCurrentUserAgentIdAdminAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
            .Returns(Microsoft.Agents.A365.DevTools.Cli.Models.RoleCheckResult.Unknown);
    }