Tracking: generalize brokered credential delivery beyond inference.local and Microsoft S2S

[dbora-nv]

Problem Statement

OpenShell has a strong broker pattern for LLM provider credentials through inference.local, and PR #1424 adds a concrete Microsoft S2S step. The same pattern should become a general credential-delivery architecture for IdP-issued dynamic tokens, downstream API tokens, refresh token custody, and consent-driven flows.

Proposed Design

1. Expose a stable internal broker surface such as credentials.local, with provider aliases only where they improve compatibility.
2. Acquire downstream credentials through the appropriate flow: client credentials, OBO, RFC 8693 token exchange, refresh, or async consent where the IdP supports it.
3. Cache, rotate, and revoke credentials gateway-side; never return downstream tokens to the sandbox.
4. Inject credentials on egress only for policy-approved hosts and tools.
5. Reject or strip sandbox-supplied Authorization headers for hosts configured as brokered, so a local shell or attacker-supplied credential cannot bypass broker policy.
6. Key broker decisions on attested workload identity where available. Treat DPoP or mTLS proof-of-possession as provider-scoped enhancements, not universal acceptance criteria.

Acceptance criteria:

• At least one non-LLM downstream API can be called without token material readable from inside the sandbox.
• Credential rotation completes without sandbox restart.
• Gateway-side revocation blocks subsequent use within one policy reload or documented revocation interval.
• Sandbox-supplied Authorization on brokered hosts is rejected or stripped, with a structured policy error.
• Broker decisions log agent_id, session_id, user_principal where applicable, tool/binary identity, requested scope/resource, granted scope/resource, decision, and correlation ID.

Sub-issues:

• Add Entra OBO token acquisition to the credential broker #1754 Entra OBO token acquisition
• Add scope attenuation for broker-issued downstream tokens #1756 Scope attenuation for broker-issued downstream tokens
• Add an async user-consent broker for always-on agents #1757 Async user-consent broker for always-on agents
• Add OpenTelemetry trace correlation across gateway activity #1758 OpenTelemetry trace correlation across gateway activity

Alternatives Considered

• Continue adding one provider-specific shim at a time: fastest locally, but risks uneven semantics and audit gaps.
• Rely only on network allowlists: controls destination, but not token scope, issuer, custody, or attribution.
• Let every tool manage its own credential cache: compatible, but puts credential material back into the sandbox trust boundary.

Agent Investigation

Problem. OpenShell has a strong broker pattern for LLM provider credentials through inference.local, and PR #1424 adds a concrete Microsoft S2S step. The same pattern should become a general credential-delivery architecture for IdP-issued dynamic tokens, downstream API tokens, refresh token custody, and consent-driven flows. This is a tracking/design issue. The most concrete sub-issue (Entra OBO) should be filed first and linked here.

Investigation:

• The inference.local model already proves credential brokering works at the gateway: sandbox-supplied credentials are stripped, backend credentials are injected at the proxy, and the agent never sees the upstream secret. This issue asks for that pattern to become a general delivery architecture.
• PR Feat microsoft provider v2 #1424 (microsoft-agent-s2s) is the second concrete instance of the pattern — confirming the broker extends from LLM keys to dynamic IdP-issued app tokens.
• Providers v2 supports oauth2_client_credentials, oauth2_refresh_token, google_service_account_jwt, static, and external refresh strategies today. All are machine-credential or pre-acquired-token shaped; none initiate user-context exchange (OBO) or async user consent (CIBA).
• The Providers v2 Roadmap explicitly lists "Automatic credential scope extraction" and "Refresh telemetry as OCSF events" as future work, directly motivating the scope-attenuation and OTel-correlation sub-issues.
• Current Providers v2 credential delivery still uses environment-variable placeholders resolved at the proxy. Acceptable for app S2S; insufficient for user-context tokens, which must not be readable from inside the sandbox under any path. A non-env-var delivery contract is part of the ask.

Current Documented Capability Map:

Credential capability	Current documented state	Requested change
LLM provider keys	Brokered through inference.local; sandbox credentials are stripped and backend credentials are injected at the gateway.	Use this as the reference broker pattern.
Providers v2 service-account / client-credential profiles	Profile and policy composition with credential placeholders and runtime/provider integration.	Clarify and extend into a general broker model where tokens do not enter the sandbox.
Microsoft S2S	Draft PR #1424 adds Microsoft Agent S2S support.	Keep S2S as the first Microsoft provider step.
Entra OBO / user principal	Not covered by PR #1424 and not documented as brokered downstream access.	Add through the Entra OBO sub-issue (#1754 ).
Downstream API tokens: Graph, GitHub, Slack, Jira, Telegram	Tools can require credentials or app-specific tokens outside the inference.local path.	Broker and inject tokens for configured hosts/tools; reject sandbox-supplied Authorization for brokered hosts.
Refresh token custody	Not documented as a gateway custody feature for downstream user/API tokens.	Keep refresh material gateway-side with rotation and revocation.
Async user consent	No documented user-scoped async consent broker.	Add through the async consent sub-issue (#1757 ).
OTel trace correlation	OCSF JSON export exists; OTel trace export is not documented.	Add through the OTel tracing sub-issue (#1758 ).

References:

• OpenShell architecture / inference.local: https://docs.nvidia.com/openshell/about/architecture
• OpenShell Providers v2: https://docs.nvidia.com/openshell/sandboxes/providers-v2
• OpenShell policy schema: https://docs.nvidia.com/openshell/reference/policy-schema
• OpenShell PR Feat microsoft provider v2 #1424: Feat microsoft provider v2 #1424
• RFC 8693 (OAuth 2.0 Token Exchange): https://datatracker.ietf.org/doc/html/rfc8693

Checklist

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

[johntmyers]

I had similar feedback for #1424 as well, that we should have a .local endpoint which can be used as a general purpose way to do brokered authentication. Specific flows could be hosted under concrete paths i.e. credentials.local/microsoft-s2s. I would propose we update #1424 with this initial capability and start to add additional flows as they are needed. I'd like to understand if there are blocked workloads on this or if these are general purpose enterprise features that are "expected." This needs to be understood to drive priority of resources.

[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.