Repository navigation
Description
Problem Statement
OpenShell experiments for Okta gateway login, runtime provider refresh, RFC 8693 token exchange, and Cross App Access established useful agent identity flows, but landing vendor-specific implementations directly in OpenShell would make the runtime own integration policy, deployment, and lifecycle for every identity provider.
NemoClaw is the opinionated blueprint layer that already composes OpenShell provider profiles, policy, credentials, sandbox lifecycle, and agent packaging. It should provide the supported reference architecture for agent identity instead. Today it has bundled static provider profiles and robust provider lifecycle handling, but no complete reference that separates and composes:
- application-user authentication and consent;
- OpenShell gateway administrator or automation authentication;
- backend service identity for sandbox and provider management;
- sandbox workload identity;
- delegated user credentials for an agent calling an approved API on behalf of that user.
Without a reference, integrations tend to reuse the gateway login token as the delegated subject, put OAuth custody in an ad hoc sidecar, or expose bearer material to the agent. The existing ID.me beta and NemoClaw Community Entra/Graph example demonstrate the desired identity boundaries, but they use standalone deployment and token-manager machinery that should become a repeatable NemoClaw shape.
Desired Behavior
NemoClaw core owns a versioned, provider-neutral agent identity reference contract. Okta and Microsoft Entra are its first product-owned conformance implementations, not an exclusive support boundary. ID.me, Ping, Palo Alto Networks, XAA.dev, and other standards-based providers are eligible for core when they satisfy the same product scope, ownership, lifecycle, compatibility, security, validation, and conformance requirements. NemoClaw Community remains an optional incubation path rather than the default destination for providers outside the first two implementations.
An operator can select a conforming reference and obtain a complete, inspectable deployment that uses OpenShell primitives for provider custody, policy-derived egress, credential injection, and middleware enforcement.
Each reference must keep these principals separate:
- The application user authenticates with the IdP and consents to a bounded downstream API scope.
- The application backend authenticates to the OpenShell control plane with its own service identity and manages only its authorized providers and sandboxes.
- OpenShell administrators authenticate to the gateway through a separate OIDC client and role/scope mapping. Gateway login is optional for the delegated runtime flow and is never used implicitly as the application's subject token.
- The sandbox supervisor uses its OpenShell-issued sandbox identity.
- The agent receives only an OpenShell placeholder. It never receives an access token, refresh token, ID token, client secret, private key, or gateway administrator token.
For each of Okta and Entra, the reference should provide one concrete end-to-end workflow:
- configure generic OpenShell gateway OIDC claim mapping for the provider;
- complete an application-user authorization flow outside the sandbox;
- transfer the current access token, expiry, and refresh/delegation material into an explicitly user-scoped OpenShell provider;
- import a bundled Providers v2 profile that owns the exact API endpoints, L7 rules, allowed binaries, credential placement, and refresh/token-grant metadata;
- attach the provider to one sandbox through NemoClaw lifecycle state;
- call an approved downstream API through the OpenShell proxy with the current delegated credential injected after middleware;
- rotate or exchange the credential without changing the agent-visible placeholder;
- revoke and delete the user-scoped provider on logout, consent withdrawal, timeout, ownership change, or sandbox removal;
- expose secret-safe provider refresh status, middleware findings, and OpenShell OCSF audit evidence.
The references should use the supervisor middleware contract from NVIDIA/OpenShell#2027 in substantially its current shape:
- middleware runs after network/L7 admission and before provider credential injection;
- it receives request, sandbox, and originating-process context but not OpenShell-managed credentials;
- it may allow, deny, transform admitted content, emit findings, and add only approved namespaced headers;
Authorization, cookies, credential headers, routing headers, and framing headers remain protected;- the identity policy stage defaults to
fail_closedfor matching protected API hosts.
Middleware should enforce request-aware identity policy and produce non-secret context. Providers v2 remains the only component that mints, stores, refreshes, resolves, and injects credentials. Do not return bearer tokens in middleware metadata, findings, body mutations, or namespaced headers.
Constraints and Non-goals
- Assume feat(supervisor-middleware): add network egress middleware OpenShell#2027 lands in relatively its current shape. Pin the first compatible OpenShell release in the blueprint and remove the pin only through the normal compatibility process.
- Current Providers v2 supports OAuth2 refresh-token and client-credentials refresh plus SPIFFE JWT-SVID token grants, but not a general request-aware RFC 8693 OBO source. feat(providers): add dynamic identity sources to Oauth2TokenExchange strategy OpenShell#1736 tracks dynamic identity sources for token exchange. The reference must either depend on the smallest accepted upstream capability from that issue or clearly stage OBO as blocked; it must not add an Okta-only or Entra-only token-exchange engine to NemoClaw.
- Current middleware cannot write
Authorizationand has no credential-resolution result. Preserve that boundary. If request-derived context must select a delegated grant, propose a non-secret handoff from middleware to Providers v2 or a separate credential resolver contract in OpenShell. - Do not capture the OpenShell CLI gateway-login token as delegated provider material. The application-user flow and control-plane login flow are independent even when the same human and IdP participate in both.
- Core eligibility is based on conformance and sustained ownership, not provider market position. Okta and Entra establish the contract first; subsequent providers may land directly in core when their proposal names an owner and proves the same lifecycle, security, compatibility, validation, and maintenance commitments. NemoClaw Community may incubate incomplete or independently maintained variants but is not a permanent second-class tier.
- Do not create a public NemoClaw plugin SDK, arbitrary executable extension point, identity CRD, custom controller, or vendor-specific OpenShell authentication subsystem.
- Do not claim production certification for an IdP tenant. Local mock services and browser flows are acceptance tools; production requires HTTPS, durable encrypted state, tenant isolation, revocation, audit export, backup/recovery, and IdP-specific review.
Implementation Idea
Use existing repository-owned seams before adding a new abstraction:
- Add reviewed Okta and Entra Providers v2 profiles under
nemoclaw-blueprint/provider-profiles/. Follow the existing Brave and Tavily import-before-create path. Profiles contain no secrets and declare only destination-specific credential placement, refresh/grant metadata, endpoint policy, and allowed binaries. - Add a strict, repository-owned identity-reference manifest consumed by the existing blueprint plan/apply path. It should compose an identity flow, IdP adapter, resource profile, deployment profile, and reference scenario while naming the provider profile, gateway OIDC mapping, external middleware service registration, policy attachment, provider ownership, and cleanup behavior. Treat it as an internal data contract until at least Okta and Entra prove the same fields are needed; do not expose arbitrary executable hooks or promise a public plugin SDK.
- Package the identity policy/broker service as a reviewed NemoClaw component reachable by both the gateway and sandbox supervisors. Register it statically in the OpenShell gateway TOML as required by feat(supervisor-middleware): add network egress middleware OpenShell#2027, start it before the gateway, and include it in health, reconcile, rebuild, and removal behavior. Service upgrades must restart the gateway and reconcile running supervisors; do not assume an in-place service change at the same endpoint refreshes cached manifests.
- Keep application OAuth bootstrap outside the sandbox. For a local reference, use a minimal host service or reference application that completes Authorization Code + PKCE or device authorization, validates issuer/audience/nonce/state, maps the immutable subject to an opaque provider name, transfers custody to OpenShell, and clears its local token bundle after successful transfer.
- Extend NemoClaw's provider lifecycle state to preserve the selected profile, opaque provider name, attachment, middleware registration, and non-secret identity configuration across rebuild and restore. Never persist raw token material in NemoClaw host state, manifests, generated config, logs, or backups.
- Use one mock standards-compliant IdP/resource server test fixture for deterministic CI, then retain separate manual acceptance checklists for real Okta and Entra tenants.
The initial implementation should define the smallest internal composition contract needed by two explicit references, not a public provider plugin framework. Okta and Entra prove that the contract is provider-neutral. Further IdPs should add data-only adapters and resource profiles wherever the standards permit, with code reserved for genuinely distinct protocol behavior.
Acceptance Criteria
- Okta and Entra references each complete one application-user-to-agent delegated API call through an OpenShell sandbox.
- Gateway administrator login and application-user delegation use separate clients, tokens, storage, and configuration.
- The agent and sandbox-visible configuration contain placeholders only; raw OAuth tokens, client secrets, private keys, gateway tokens, and middleware service credentials are absent from environment dumps, process arguments, generated files, logs, snapshots, and backups.
- Providers v2 profiles are bundled, linted, imported before provider creation, attached explicitly, and composed into the effective sandbox policy.
- Provider endpoints and L7 paths are least privilege; credential injection occurs only on matching inspected requests from allowed binaries.
- Middleware policy applies before credential injection, defaults to fail closed for protected hosts, and cannot inspect or mutate protected credential headers.
- Token refresh or exchange updates the provider without changing the agent-visible placeholder or restarting the sandbox process that initiates new requests.
- Logout, revocation, timeout, sandbox removal, interrupted onboarding, rebuild, and restore have deterministic provider and middleware cleanup/recovery behavior.
- CI covers import failure, middleware outage, expired/revoked grant, subject/provider ownership mismatch, refresh rotation, provider attachment conflicts, and secret-negative assertions.
- Manual Okta and Entra acceptance evidence distinguishes browser authentication from automated proof and contains no token or personal-data payloads.
- Documentation includes the five-principal trust model, deployment topology, IdP setup worksheet, supported OpenShell version, troubleshooting, security boundaries, and conformance-based core admission policy.
- An adapter authoring guide and conformance tests show how ID.me, Ping, Palo Alto Networks, XAA.dev, and similar providers can implement the contract without adding provider-specific code to OpenShell.
Alternatives Considered
Land each IdP in OpenShell. Rejected because generic OIDC gateway authentication, supervisor middleware, and Providers v2 are the reusable runtime primitives. Vendor deployment, consent, lifecycle, and reference application choices belong in the blueprint layer.
Route providers to core or community by vendor. Rejected because provider popularity is not an architectural boundary. Core support does imply lifecycle, compatibility, security, validation, and ownership commitments, so admission remains deliberate; however, any provider that satisfies those requirements can be maintained in core. Community is useful for incubation and independent ownership, not as the default home for every provider after Okta and Entra.
Let middleware mint and inject bearer tokens. Rejected because NVIDIA/OpenShell#2027 intentionally runs before credential injection, omits protected headers, and forbids Authorization mutation. Mixing policy inspection with secret-bearing credential injection would weaken the trust boundary.
Reuse the OpenShell gateway login token for OBO. Rejected because control-plane authorization and application-user delegation have different audiences, scopes, storage, revocation, and ownership. The ID.me reference demonstrates the safer separation.
Keep an opaque token-manager sidecar per integration. Useful as prior art and a temporary community implementation, but not the target. It duplicates provider custody, refresh, policy, observability, and recovery already owned by OpenShell.
Agent Investigation
- Reviewed the ID.me OpenShell Minikube beta (
NVIDIA-dev/idme-openshell-minikube-demo). Its strongest reusable contract is separation of application user, gateway administrator, backend service, sandbox supervisor, and agent identities, followed by explicit delegated credential custody transfer into OpenShell. - Reviewed stale OpenShell PRs feat(auth): add Okta workforce gateway login OpenShell#1672 (Okta gateway login), feat(providers): add Okta runtime provider profile OpenShell#1673 (Okta runtime refresh profile), feat(auth): support live Okta OBO token exchange OpenShell#1681 (Okta RFC 8693 OBO), and feat(xaa): add sample xaa provider flow OpenShell#1682 (Okta/XAA sample). Their provider profiles and tutorials are useful input, but feat(auth): support live Okta OBO token exchange OpenShell#1681 and feat(xaa): add sample xaa provider flow OpenShell#1682 couple delegation to the gateway-login subject token and add provider-specific refresh strategies that should not be copied into NemoClaw.
- Reviewed feat(supervisor-middleware): add network egress middleware OpenShell#2027 and RFC 0009. The current API is an ordered
HttpRequest/pre_credentialspolicy and transformation hook with static external-service registration, host selectors, body limits, strict header protections, findings, and fail-open/fail-closed behavior. It is a policy/context seam, not a credential provider API. - Reviewed Providers v2 in current OpenShell. It already supplies custom profile import/update, provider-owned network policy, attach/detach lifecycle, refresh material custody, short-lived credential rotation, dynamic SPIFFE token grants, and proxy injection. The missing OBO capability is dynamic user/actor identity sourcing, tracked by feat(providers): add dynamic identity sources to Oauth2TokenExchange strategy OpenShell#1736.
- Reviewed current NemoClaw
origin/main. The closest core precedent isnemoclaw-blueprint/provider-profiles/plussrc/lib/actions/credentials-add.tsandsrc/lib/onboard/brave-provider-profile.ts, which import bundled data-only profiles before provider creation and preserve provider lifecycle through onboarding/rebuild. - Reviewed
NVIDIA/nemoclaw-community.examples/personal-community-sentiment-triage/is the closest full reference architecture: explicit host services, gateway, providers, sandbox, policy, agent assets, bring-up/tear-down, and Entra/Graph token-manager lifecycle. It is useful packaging precedent and demonstrates behavior that core references can simplify with Providers v2. - Searched NemoClaw issues for Okta, OBO, OAuth, and identity-provider references. No existing issue covers this proposal; closed feat: add azure-nim inference profile for Microsoft Foundry-hosted NIM endpoints #58 concerns Azure-hosted inference rather than delegated agent identity.
Category
Provider
Activity
[-]feat: add Okta and Entra agent identity reference blueprints[/-][+]feat: add a core agent identity blueprint contract with Okta and Entra references[/+]afourniernv commentedon Jul 14, 2026
wscurran commentedon Jul 14, 2026
✨ Thanks for the proposal, @afourniernv. This is a significant cross-cutting reference architecture for agent identity. Before implementation, maintainers need to align on the scope, composition model, and which Okta/Entra flows the initial blueprints should cover.
afourniernv commentedon Jul 17, 2026
Scope alignment proposal after upstream middleware merge
I revalidated this proposal against NemoClaw
origin/mainat7d1cef9dand the currentOpenShell dependencies:
available rather than hypothetical.
8693 OBO should therefore remain outside the first slice.
src/lib/onboard/credential-provider-registration.ts; the first slice should reuse theexisting provider registration and lifecycle contracts rather than create a parallel
registry.
scripts/validate-configs.mts.To make the remaining product decision explicit, I recommend the following alignment:
reference contract. Okta and Entra are the first product-owned conformance references.
Other standards-based providers remain eligible for core only with a named owner and
equivalent lifecycle, security, compatibility, validation, and maintenance evidence.
outside NemoClaw. Entra proves
GET https://graph.microsoft.com/v1.0/me; Okta provesthe OIDC
userinfoendpoint. Gateway administrator login remains independent fromapplication-user delegation.
data-only Providers v2 profiles, and explicit
plan,apply,status, andremoveoperations. Reuse current provider registration, attachment, rebuild, and cleanup
seams. Do not add a public plugin SDK, arbitrary hooks, an identity CRD, or a custom
controller.
agent access, one-sandbox attachment, rotation, revocation failure, and deterministic
cleanup. It does not ship an OAuth browser application, request-derived provider
selection, RFC 8693 OBO, or a production identity-policy middleware service. A later
slice can use the merged middleware contract for request-aware policy while preserving
the pre-credential boundary.
The specific decisions needed before implementation are therefore:
userinfoand Microsoft Graph/meas the first concrete resource flows;If those four decisions are accepted, the implementation can proceed as a bounded first
slice without waiting on NVIDIA/OpenShell#1736. If maintainers want middleware or OAuth
bootstrap in the initial deliverable, the issue should remain
needs: designand thedeployment and ownership model should be specified before code begins.
afourniernv commentedon Jul 20, 2026
Initial implementation is now split by ownership:
The Entra reference has deterministic unit and configuration coverage. Live Entra validation remains pending because the previous tenant is unavailable. OBO remains intentionally staged behind the generic upstream identity-source capability described in this issue.
afourniernv commentedon Jul 20, 2026
Correction: draft PR #7265 is now the Okta-only reference slice. Microsoft Entra has been removed from that PR and remains tracked in this issue for a later companion reference. OBO remains deferred pending a generic dynamic actor-credential source in the platform.
feat(blueprint): add Okta runtime identity reference (#7265)
ericksoa commentedon Jul 29, 2026
Maintainer decision: accept the bounded Okta and Entra runtime identity references
I am recording the maintainer product decision for this issue.
The following first-slice scope is accepted:
GET /v1.0/medelivery surface. A data profile alone cannot expand token-issuer or credential-delivery trust.Ownership, compatibility, and security expectations are also accepted:
The accepted validation contract is:
GET /v1.0/me, rejection before delivery for an unreviewed resource, placeholder-only sandbox surfaces, secret-safe evidence, ownership-aware rollback, and complete cleanup.GET /v1.0/mefor the authenticated principal.This decision clears the Product Scope Gate for the bounded implementation in #7686. The issue can remain open for later OBO, middleware, bootstrap, and broader conformance work, but those follow-ups do not block the accepted Entra reference.
feat(blueprint): add Entra runtime identity reference (#7686)
chore(deps): trust OpenShell 0.0.106 manifests (#9224)
chore(deps): update OpenShell to 0.0.106 (#9192)
jyaunches commentedon Oct 7, 2026
This issue is being rescoped into new epics as part of the NemoClaw V1 planning review. The rescoped work will return in a few days.
Closing this issue for replanning, not because the work is complete.