Add Entra OBO token acquisition to the credential broker

[dbora-nv]

Problem Statement

OpenShell should support Entra On-Behalf-Of token acquisition at the gateway so user-principal identity can propagate to downstream APIs such as Microsoft Graph, SharePoint, and Outlook without placing the user access token inside the sandbox.
The current options are either service-account access, which loses user attribution and increases confused-deputy risk, or user-token exposure inside the sandbox, which weakens credential isolation. OBO at the gateway preserves both attribution and isolation.

Proposed Design

1. Accept a validated user-context assertion at the agent session boundary, with the original user token remaining gateway-side.
2. Allow policy to declare Entra resources, scopes, tenants, and client apps that each agent/tool/binary may request.
3. When an agent calls a brokered downstream host such as graph.microsoft.com, perform Entra OBO at the gateway and inject the downstream-scoped token on egress.
4. Cache, refresh, and revoke downstream tokens gateway-side; never expose token material through sandbox environment variables, files, /proc, process memory, or command-line arguments.
5. Return structured errors for consent missing, MFA required, scope denied, tenant mismatch, and token exchange failure so the agent can surface the right user action.

Acceptance criteria:

• An agent can call Microsoft Graph as the invoking user without readable token material inside the sandbox.
• Failed OBO returns a structured error that distinguishes consent, MFA, scope denial, tenant/client mismatch, and transient IdP failures.
• OBO exchanges log user_principal, agent_id, requested_scope, granted_scope, resource, outcome, and correlation ID.
• Token refresh and revocation do not require sandbox restart.
• Sandbox-supplied Authorization headers are rejected for hosts configured for gateway-brokered Entra tokens.

Alternatives Considered

• Use a service account for downstream APIs: simpler, but loses user attribution and broadens privilege.
• Pass the user token into the sandbox: preserves user attribution, but breaks credential isolation.
• Use per-tool local helpers such as gh or SDK credential caches: reduces custom gateway work, but still leaves tokens or refresh material reachable by the agent.
• Defer until a broader broker exists: delays the most concrete enterprise blocker.

Agent Investigation

• PR Feat microsoft provider v2 #1424 ("Feat microsoft provider v2", Draft, by @afourniernv) adds a microsoft-agent-s2s provider for Microsoft runtime-agent S2S identity with audience-specific short-lived bearer tokens. The PR's own Design Notes state: "Delegated / OBO user flows are intentionally out of scope for this PR and should likely live under a separate provider later." This issue is that separate provider.
• PR Feat microsoft provider v2 #1424 delivers credentials to the sandbox via environment variables (A365_TOKEN_PROVIDER_URL, OPENSHELL_MICROSOFT_AGENT_S2S_TOKEN_PROVIDER_URL, OPENSHELL_MICROSOFT_AGENT_S2S_TOKEN_URL). For app-S2S tokens this is acceptable. For user-context tokens it is not, since the user token must never be readable from inside the sandbox. The OBO broker therefore requires a non-env-var delivery contract.
• Providers v2 documents credential placeholder rewrites and runtime injection behavior, but not gateway-side Entra OBO exchange for user-principal downstream access.
• The inference.local model already demonstrates a gateway-mediated credential path for LLM providers; this issue asks for the analogous user-principal flow for Entra-backed APIs.

References:

• Microsoft OBO flow: https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-on-behalf-of-flow
• OpenShell PR Feat microsoft provider v2 #1424: Feat microsoft provider v2 #1424
• OpenShell architecture / inference.local: https://docs.nvidia.com/openshell/about/architecture
• OpenShell Providers v2: https://docs.nvidia.com/openshell/sandboxes/providers-v2

Checklist

• I've reviewed existing issues and the architecture docs
• This is a design proposal, not a "please build this" request

[slopp]

We could consider having OBO via Microsoft's concept of agent identity: https://learn.microsoft.com/en-us/entra/agent-id/agent-on-behalf-of-oauth-flow

The idea there would be:

• Gateway calls Agent ID SDK /AuthorizationHeader/Graph?... with a user token or agent identity context.
• SDK performs Entra OBO / agent-user / app-token acquisition.
• Gateway injects the returned Authorization header on egress.

So very similar but relying on the agent SDK for OBO

[krishicks]

📋 triage-agent

Removing state:triage-needed as workflow cleanup. Agent review of the issue's current state found substantive maintainer discussion, indicating that it is no longer awaiting initial triage. This label removal does not imply roadmap acceptance or implementation priority.