setup blueprint: redundant OAuth2 grant POST fails after successful browser consent, silently skipping inheritable permissions configuration

[Jose-BV]

Description

Summary

When running a365 setup blueprint for a new blueprint, the command successfully opens the browser for admin consent and confirms the grant was created. However, it then attempts a redundant programmatic POST /v1.0/oauth2PermissionGrants for the same grant, which fails with 403 Authorization_RequestDenied. This failure prevents the inheritable permissions manifest from ever being written to the blueprint application, leaving agent instances unable to inherit Microsoft Graph permissions at runtime.

Root Cause

The flow through EnsureAdminConsentAsync (BlueprintSubcommand.cs:1844) for a new blueprint is:

1. Browser consent — BuildAdminConsentUrl() + BrowserHelper.TryOpenUrl() opens /v2.0/adminconsent. Azure creates the oauth2PermissionGrant record when the admin accepts. The CLI polls and confirms success (BlueprintSubcommand.cs:1989–2002).

2. Redundant programmatic grant — EnsureResourcePermissionsAsync is called (BlueprintSubcommand.cs:2023). Inside, Step 2 (SetupHelpers.cs:1557–1580) unconditionally issues POST /v1.0/oauth2PermissionGrants with consentType: AllPrincipals via GraphApiService.CreateOrUpdateOauth2PermissionGrantWithDetailsAsync. The Graph API returns 403 Authorization_RequestDenied because creating AllPrincipals grants programmatically requires Global Administrator backing on the CLI's delegated token, even though the same grant was just established interactively by the admin in the browser (GraphApiService.cs:909–913). A SetupValidationException is thrown at SetupHelpers.cs:1576.

3. Inheritable permissions never reached — Step 3 (SetupHelpers.cs:1587), which calls AgentBlueprintService.SetInheritablePermissionsAsync, is never executed. This step writes an allAllowed inheritable permissions manifest entry to the blueprint application object via POST /beta/applications/microsoft.graph.agentIdentityBlueprint/{objectId}/inheritablePermissions (AgentBlueprintService.cs:451–472). Without it, the Agent Identity platform has no declaration of which scopes agent instances may inherit from the blueprint, so instances cannot use the consented Graph permissions at runtime.

Misleading Error Message

The outer catch at BlueprintSubcommand.cs:1956–1961 logs the failure as "Failed to configure Microsoft Graph inheritable permissions". This is inaccurate — the inheritable permissions API was never called. The actual failure is in the OAuth2 grant POST (Step 2). This makes the error harder to diagnose, since it implies the AgentIdentityBlueprint.ReadWrite.All scope is the issue, when the real cause is the redundant AllPrincipals grant attempt.

Expected behavior

After a successful browser admin consent, EnsureResourcePermissionsAsync should skip the POST /v1.0/oauth2PermissionGrants step (or treat the existing grant as sufficient) and proceed directly to Step 3 to write the inheritable permissions manifest on the blueprint application object.

SDK Version

1.1.206

Language/Runtime

.NET 10.0.300

OS

macOS

How to Reproduce

Steps to Reproduce

1. Run:

a365 setup blueprint --agent-name <name> --tenant-id <tenant>

2. Grant consent in the browser when prompted. Observe the output:

--> Consent granted (Graph API Scopes). 
--> Graph API admin consent granted successfully!
--> Configuring inheritable permissions for Microsoft Graph...  
--> OAuth2 permission grant failed (non-transient) for resource <resource-id> with scopes [...]. Graph response: {"error":{"code":"Authorization_RequestDenied",...}} 
--> Failed to configure Microsoft Graph inheritable permissions: [SETUP_VALIDATION_FAILED] Failed to create/update OAuth2 permission grant from blueprint <id> to Microsoft Graph 00000003-0000-0000-c000-000000000000. This may be due to insufficient permissions. Ensure you have AgentIdentityBlueprint.ReadWrite.All permission consented on your client app.    
--> Agent instances may not be able to access Microsoft Graph resources

Output

Agent % a365 setup blueprint --agent-name AgentV2 --tenant-id

Resolving client app by display name "Agent 365 CLI"...
Checking requirements...
Pass: Azure Authentication
Warn: Frontier Preview Program - Tenant enrollment cannot be verified automatically - Ensure your tenant is enrolled before proceeding. See: https://adoption.microsoft.com/copilot/frontier-program/
Pass: PowerShell Modules (Microsoft.Graph.Authentication, Microsoft.Graph.Applications)
Pass: Client App Configuration ()
Pass: Client App 'wids' Optional Claim ('wids' is present on accessToken optionalClaims for )

Requirements: 4 passed, 1 warnings, 0 failed

Starting blueprint setup... (TraceId: )

Creating agent blueprint...
Verifying consent for agent blueprint operations...
Successfully ensured delegated application consent
Creating blueprint application...
Sign in to Microsoft Graph to continue...
Authenticating to Microsoft Graph...
Successfully authenticated to Microsoft Graph!
Current user: <>
Display Name: AgentV2 Blueprint
Sponsor and Owner: User ID
Blueprint application created successfully
Blueprint ID:
Waiting for application to propagate in directory...

Creating blueprint service principal...
    Blueprint service principal ID: <BLUEPRINT-SP-ID>

Adding access_agent_as_user scope to blueprint...
access_agent_as_user scope added to blueprint
Requesting admin consent for application
Opening browser for Graph API admin consent...
If the browser does not open automatically, navigate to this URL to grant consent: https://login.microsoftonline.com/<TENANT-ID>/v2.0/adminconsent?client_id=<BLUEPRINT-APP-ID>&scope=.....
Sign in and Accept the permission(s). If the tab shows an error after Accept, consent likely succeeded — the CLI will still detect it (timeout: 180s).
Consent granted (Graph API Scopes).
Graph API admin consent granted successfully!
Configuring inheritable permissions for Microsoft Graph...

OAuth2 permission grant failed (non-transient) for resource <GRAPH-SP-OBJECT-ID> with scopes [Mail.ReadWrite Mail.Send Chat.ReadWrite User.Read.All Sites.Read.AllFiles.ReadWrite.All ChannelMessage.Read.All ChannelMessage.Send]. Graph response: {"error":{"code":"Authorization_RequestDenied","message":"Insufficient privileges to complete the operation.","innerError":{"date":"2026-06-10T12:30:17","request-id":"<REQUEST-ID>","client-request-id":"<CLIENT-REQUEST-ID>"}}}

Failed to configure Microsoft Graph inheritable permissions: [SETUP_VALIDATION_FAILED] Failed to create/update OAuth2 permission grant from blueprint <BLUEPRINT-APP-ID> to Microsoft Graph 00000003-0000-0000-c000-000000000000. This may be due to insufficient permissions. Ensure you have AgentIdentityBlueprint.ReadWrite.All permission consented on your client app.
Agent instances may not be able to access Microsoft Graph resources
You can configure these manually later with: a365 setup blueprint

Creating blueprint client secret...
    DPAPI encryption not available on this platform. Secret will be stored in plaintext.
    Client secret created successfully!
    Blueprint client secret: <REDACTED-SECRET>
    Copy this value now — it will not be shown again automatically.
    To retrieve it later, run 'a365 setup blueprint --show-secret' from the same folder.

    Keep your credentials secure and do not commit them to source control!

Verification URLs:
Entra ID Application: https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationMenuBlade/~/Overview/appId/

Configuring custom blueprint permissions...

No custom blueprint permissions specified in config. Skipping.
Next steps:
1. Run 'a365 setup permissions mcp' to configure MCP permissions
2. Run 'a365 setup permissions bot' to configure Bot API permissions

Screenshots

No response

Code of Conduct

• I agree to follow the Microsoft Open Source Code of Conduct.

[github-actions]

[AUTO-TRIAGE] Team Assistant Triage

This issue has been automatically analyzed and triaged.

AI Decision Reasoning: Type: Classified as 'bug' because the issue describes a failure in the OAuth2 grant flow that prevents inheritable permissions from being configured, breaking critical functionality.
Priority: Assigned P1 because the issue directly impacts runtime behavior of agent instances and prevents essential permissions setup, making it a critical blocker. [Security issue detected: The issue describes a problem where inheritable permissions are not configured due to a failed programmatic OAuth2 grant request, which could leave agent instances unable to inherit necessary Microsoft Graph permissions. This creates a potential security vulnerability as it might lead to improper permission handling or unauthorized access at runtime.]
Copilot: Security issues require human review and should not be auto-fixed
Assignment: Security issue assigned to security lead. The issue describes a problem where inheritable permissions are not configured due to a failed programmatic OAuth2 grant request, which could leave agent instances unable to inherit necessary Microsoft Graph permissions. This creates a potential security vulnerability as it might lead to improper permission handling or unauthorized access at runtime.
Labels: Applied labels bug, P1, security based on issue type and priority

Labels and assignee have been applied based on this analysis.

[github-actions]

[AUTO-TRIAGE] Results

Classification: bug
Priority: P1
Confidence: 95.0%

Recommended Assignee: Sellakumaran Kanagarathnam (@sellakumaran)

Analysis:
type rationale: Classified as 'bug' because the issue describes a failure in the OAuth2 grant flow that prevents inheritable permissions from being configured, breaking critical functionality.

priority rationale: Assigned P1 because the issue directly impacts runtime behavior of agent instances and prevents essential permissions setup, making it a critical blocker. [Security issue detected: The issue describes a problem where inheritable permissions are not configured due to a failed programmatic OAuth2 grant request, which could leave agent instances unable to inherit necessary Microsoft Graph permissions. This creates a potential security vulnerability as it might lead to improper permission handling or unauthorized access at runtime.]

copilot rationale: Security issues require human review and should not be auto-fixed

assignment rationale: Security issue assigned to security lead. The issue describes a problem where inheritable permissions are not configured due to a failed programmatic OAuth2 grant request, which could leave agent instances unable to inherit necessary Microsoft Graph permissions. This creates a potential security vulnerability as it might lead to improper permission handling or unauthorized access at runtime.

labels rationale: Applied labels bug, P1, security based on issue type and priority

[SUGGESTION] Suggested Approach

1. 1. **Add a conditional check to skip redundant POST requests:** Modify `EnsureResourcePermissionsAsync` in `SetupHelpers.cs` (lines 1557–1580) to first check if the `oauth2PermissionGrant` already exists for the given application. Use the Graph API's GET `/v1.0/oauth2PermissionGrants` endpoint to verify existing grants before attempting a POST request.
2. 2. **Refactor `EnsureAdminConsentAsync` to handle 403 errors gracefully:** Update `BlueprintSubcommand.cs` (lines 2023 and 1844) to catch the `403 Authorization_RequestDenied` exception from `GraphApiService.CreateOrUpdateOauth2PermissionGrantWithDetailsAsync`. Log a warning instead of throwing an exception, and proceed to Step 3 (`AgentBlueprintService.SetInheritablePermissionsAsync`) to ensure inheritable permissions are configured.
3. 3. **Introduce a flag to bypass redundant programmatic grants:** Add a configuration flag (e.g., `--skip-programmatic-grant`) to the `a365 setup blueprint` command. Update `EnsureResourcePermissionsAsync` in `SetupHelpers.cs` to respect this flag and skip the redundant POST request if the admin consent was already confirmed interactively.
4. 4. **Enhance test coverage for the setup flow:** Add unit tests in `src/Tests/Microsoft.Agents.A365.DevTools.Cli.Tests/Commands` to validate the behavior of `EnsureAdminConsentAsync` and `EnsureResourcePermissionsAsync`. Specifically, test scenarios where the programmatic POST fails with a 403 and ensure that inheritable permissions are still configured correctly.
5. 5. **Update documentation to clarify admin consent requirements:** In the `docs` directory, add a section to explain the admin consent flow and the limitations of programmatic grants requiring Global Administrator privileges. Include troubleshooting steps for resolving 403 errors and emphasize the importance of browser-based admin consent.

---

Generated by TeamAssistant Auto-Triage powered by GitHub Models