docs(providers): add microsoft agent s2s guidance

afourniernv · afourniernv · commit abfb90006c03 · 2026-06-01T13:48:21.000-07:00
diff --git a/docs/get-started/tutorials/index.mdx b/docs/get-started/tutorials/index.mdx
@@ -27,6 +27,11 @@ Launch Claude Code in a sandbox, diagnose a policy denial, and iterate on a cust
 Configure a Providers v2 Microsoft Graph provider with gateway-managed OAuth2 refresh-token rotation.
 </Card>
 
+<Card title="Microsoft Agent S2S Provider" href="/get-started/tutorials/microsoft-agent-s2s">
+
+Create a `microsoft-agent-s2s` provider and verify that a sandboxed workload receives a brokered runtime token URL instead of the Microsoft secret.
+</Card>
+
 <Card title="Inference with Ollama" href="/get-started/tutorials/inference-ollama">
 
 Route inference through Ollama using cloud-hosted or local models, and verify it from a sandbox.
diff --git a/docs/get-started/tutorials/microsoft-agent-s2s.mdx b/docs/get-started/tutorials/microsoft-agent-s2s.mdx
@@ -0,0 +1,143 @@
+---
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+title: "Broker Microsoft Agent S2S Tokens with Providers v2"
+sidebar-title: "Microsoft Agent S2S Provider"
+slug: "get-started/tutorials/microsoft-agent-s2s"
+description: "Create a microsoft-agent-s2s provider, attach it to a sandbox, and verify that the workload receives a brokered runtime token URL instead of the Microsoft secret."
+keywords: "Generative AI, Cybersecurity, Tutorial, Providers, Microsoft, A365, Agent 365, S2S, Token Broker"
+---
+
+Use Providers v2 to keep Microsoft Agent service-to-service identity material at the gateway while sandboxed workloads request short-lived tokens on demand. Instead of injecting a static bearer token or the blueprint client secret into the sandbox, OpenShell injects a sandbox-local token provider URL and brokers Microsoft tokens for approved audiences at runtime.
+
+After completing this tutorial, you have:
+
+- A `microsoft-agent-s2s` provider instance on your gateway.
+- A sandbox with the provider attached.
+- A concrete example of the runtime contract the workload receives: `A365_TOKEN_PROVIDER_URL`.
+
+<Warning>
+Do not commit Microsoft client secrets, local `.env` files, or emitted bearer tokens. The commands below pass secret material to the gateway; they are not examples of values to store in source control.
+</Warning>
+
+<Steps toc={true}>
+
+## Prerequisites
+
+- A working OpenShell installation with an active gateway. Complete the [Quickstart](/get-started/quickstart) before proceeding.
+- Providers v2 enabled on the active gateway.
+- A Microsoft setup that already provides:
+  - `AZURE_TENANT_ID`
+  - `A365_BLUEPRINT_CLIENT_ID`
+  - `A365_BLUEPRINT_CLIENT_SECRET`
+  - `A365_RUNTIME_AGENT_ID`
+  - `A365_ALLOWED_AUDIENCES`
+
+`A365_ALLOWED_AUDIENCES` is a comma-separated list of downstream audiences that the sandboxed workload may request tokens for.
+
+## Enable Providers v2
+
+Enable provider profile policy composition on the active gateway:
+
+```shell
+openshell settings set --global --key providers_v2_enabled --value true --yes
+```
+
+## Inspect the Built-in Profile
+
+Export the built-in `microsoft-agent-s2s` profile:
+
+```shell
+openshell provider profile export microsoft-agent-s2s -o yaml
+```
+
+The built-in profile intentionally does not include default network policy. It defines the provider type and discovery shape only.
+
+## Create the Provider
+
+Create a provider instance from the Microsoft S2S inputs:
+
+```shell
+openshell provider create \
+  --name microsoft-a365 \
+  --type microsoft-agent-s2s \
+  --credential A365_BLUEPRINT_CLIENT_SECRET="$A365_BLUEPRINT_CLIENT_SECRET" \
+  --config AZURE_TENANT_ID="$AZURE_TENANT_ID" \
+  --config A365_BLUEPRINT_CLIENT_ID="$A365_BLUEPRINT_CLIENT_ID" \
+  --config A365_RUNTIME_AGENT_ID="$A365_RUNTIME_AGENT_ID" \
+  --config A365_ALLOWED_AUDIENCES="$A365_ALLOWED_AUDIENCES"
+```
+
+The provider stores:
+
+- `A365_BLUEPRINT_CLIENT_SECRET` as the secret credential
+- `AZURE_TENANT_ID`, `A365_BLUEPRINT_CLIENT_ID`, `A365_RUNTIME_AGENT_ID`, and `A365_ALLOWED_AUDIENCES` as provider config
+
+Unlike a normal placeholder provider, the sandbox does not receive `A365_BLUEPRINT_CLIENT_SECRET` directly.
+
+## Launch a Sandbox
+
+Launch a simple sandbox with the provider attached:
+
+```shell
+openshell sandbox create \
+  --name microsoft-a365-demo \
+  --keep \
+  --provider microsoft-a365 \
+  --no-auto-providers \
+  -- /bin/sh
+```
+
+This tutorial uses `/bin/sh` so you can inspect the runtime contract directly. Substitute your own A365 workload image or startup command later.
+
+## Verify the Runtime Contract
+
+Inside the sandbox, inspect the injected token broker metadata:
+
+```shell
+env | grep '^A365_TOKEN_PROVIDER_URL\|^OPENSHELL_MICROSOFT_AGENT_S2S'
+```
+
+You should see a local token provider URL and related metadata, for example:
+
+```text
+A365_TOKEN_PROVIDER_URL=http://<sandbox-local-resolver>/v1/microsoft-agent-s2s/token/<provider-id>
+OPENSHELL_MICROSOFT_AGENT_S2S_TOKEN_PROVIDER_URL=http://<sandbox-local-resolver>/v1/microsoft-agent-s2s/token/<provider-id>
+OPENSHELL_MICROSOFT_AGENT_S2S_TOKEN_URL=http://<sandbox-local-resolver>/v1/microsoft-agent-s2s/token/<provider-id>
+OPENSHELL_MICROSOFT_AGENT_S2S_DEFAULT_AUDIENCE=<audience>
+```
+
+The important difference from placeholder providers is that the sandbox receives a token URL rather than the blueprint client secret.
+
+## Request a Token from the Local Broker
+
+If your workload knows the audience it wants, it can call the broker URL directly. For example, from inside the sandbox:
+
+```shell
+curl -sS "${A365_TOKEN_PROVIDER_URL}?audience=${OPENSHELL_MICROSOFT_AGENT_S2S_DEFAULT_AUDIENCE}"
+```
+
+The exact response shape depends on the workload-side adapter, but the flow is always the same:
+
+1. the workload calls the sandbox-local token URL
+2. the gateway checks that the sandbox has the provider attached
+3. the gateway verifies that the requested audience is allowed
+4. the gateway returns a short-lived Microsoft bearer token
+
+OpenShell keeps the blueprint secret and the Microsoft token exchange at the gateway boundary.
+
+## Use the Contract from a Workload
+
+Workloads that already support a token callback can consume the broker directly. For example, the NAT/A365 integration we validated uses this shape:
+
+```yaml
+authentication:
+  a365_auth:
+    _type: openshell_bearer_token
+    token_url: ${A365_TOKEN_PROVIDER_URL}
+    audience: "<audience>"
+```
+
+A non-NAT Microsoft agent can use the same OpenShell provider as long as it can request tokens from a callback or token-provider URL instead of requiring a static bearer token or direct access to the Microsoft secret material.
+
+</Steps>
diff --git a/docs/sandboxes/manage-providers.mdx b/docs/sandboxes/manage-providers.mdx
@@ -16,6 +16,10 @@ Create and manage providers that supply credentials to sandboxes.
 Providers v2 is available for profile-backed provider policy, provider-owned network rules, and gateway-managed credential refresh. This page remains the credential-focused provider command reference. For the new workflow, see [Providers v2](/sandboxes/providers-v2).
 </Info>
 
+<Note>
+Most providers inject placeholder environment variables such as `GITHUB_TOKEN` or `OPENAI_API_KEY`. Brokered runtime providers such as `microsoft-agent-s2s` are different: the sandbox receives a local token-provider URL, and the gateway mints short-lived tokens at runtime instead of projecting the long-lived provider secret into the workload.
+</Note>
+
 Provider profiles include metadata for known endpoints and binaries. View
 the available profiles before creating a provider:
 
@@ -47,6 +51,19 @@ Supply a credential value directly:
 openshell provider create --name my-api --type generic --credential API_KEY=sk-abc123
 ```
 
+Brokered providers can combine one secret credential with non-secret config. For example, create a Microsoft Agent S2S provider by storing the blueprint client secret as the credential and the Microsoft identity metadata as provider config:
+
+```shell
+openshell provider create \
+  --name microsoft-a365 \
+  --type microsoft-agent-s2s \
+  --credential A365_BLUEPRINT_CLIENT_SECRET="$A365_BLUEPRINT_CLIENT_SECRET" \
+  --config AZURE_TENANT_ID="$AZURE_TENANT_ID" \
+  --config A365_BLUEPRINT_CLIENT_ID="$A365_BLUEPRINT_CLIENT_ID" \
+  --config A365_RUNTIME_AGENT_ID="$A365_RUNTIME_AGENT_ID" \
+  --config A365_ALLOWED_AUDIENCES="$A365_ALLOWED_AUDIENCES"
+```
+
 ### Bare Key Form
 
 Pass a key name without a value to read the value from the environment variable
@@ -203,6 +220,19 @@ The agent process inside the sandbox never sees real credential values. At start
 
 This resolution requires the proxy to see plaintext HTTP. Endpoints must use `protocol: rest` in the policy (which auto-terminates TLS) or explicit `tls: terminate`. Endpoints without TLS termination pass traffic through as an opaque stream, and credential placeholders are forwarded unresolved.
 
+### Brokered Runtime Providers
+
+Some providers do not inject the primary credential into the workload at all. `microsoft-agent-s2s` is the first built-in example.
+
+Instead of projecting `A365_BLUEPRINT_CLIENT_SECRET` into the sandbox, OpenShell injects sandbox-local token broker metadata:
+
+- `A365_TOKEN_PROVIDER_URL`
+- `OPENSHELL_MICROSOFT_AGENT_S2S_TOKEN_PROVIDER_URL`
+- `OPENSHELL_MICROSOFT_AGENT_S2S_TOKEN_URL`
+- `OPENSHELL_MICROSOFT_AGENT_S2S_DEFAULT_AUDIENCE`, when the provider config resolves one automatically
+
+The workload calls the local token URL when it needs a bearer token. The gateway validates that the sandbox has the provider attached, checks that the requested audience is allowed by the provider config, and returns a short-lived Microsoft token. This keeps blueprint client secrets and Microsoft token exchange logic out of the sandboxed application process.
+
 ### Supported injection locations
 
 The proxy resolves credential placeholders in the following parts of an HTTP request:
@@ -251,6 +281,7 @@ The following provider types are supported.
 | `generic` | User-defined | Any service with custom credentials |
 | `github` | `GITHUB_TOKEN`, `GH_TOKEN` | GitHub API and `gh` CLI. Refer to [GitHub Sandbox](/get-started/tutorials/github-sandbox). |
 | `gitlab` | `GITLAB_TOKEN`, `GLAB_TOKEN`, `CI_JOB_TOKEN` | GitLab API, `glab` CLI |
+| `microsoft-agent-s2s` | `A365_TOKEN_PROVIDER_URL`, `OPENSHELL_MICROSOFT_AGENT_S2S_TOKEN_PROVIDER_URL`, `OPENSHELL_MICROSOFT_AGENT_S2S_TOKEN_URL`, optional `OPENSHELL_MICROSOFT_AGENT_S2S_DEFAULT_AUDIENCE` | Brokered Microsoft Agent 365 service-to-service access. The sandbox receives a local token broker URL rather than the blueprint client secret. Refer to [Microsoft Agent S2S Provider](/get-started/tutorials/microsoft-agent-s2s). |
 | `nvidia` | `NVIDIA_API_KEY` | NVIDIA API Catalog |
 | `openai` | `OPENAI_API_KEY` | Any OpenAI-compatible endpoint. Set `--config OPENAI_BASE_URL` to point to the provider. Refer to [Inference Routing](/sandboxes/inference-routing). |
 | `opencode` | `OPENCODE_API_KEY`, `OPENROUTER_API_KEY`, `OPENAI_API_KEY` | OpenCode |
diff --git a/docs/sandboxes/providers-v2.mdx b/docs/sandboxes/providers-v2.mdx
@@ -25,6 +25,7 @@ Providers v2 keeps those pieces together:
 | Custom provider definitions | You can export, edit, lint, import, list, and delete custom profiles. |
 | Runtime provider lifecycle | You can list, attach, and detach providers on existing sandboxes. |
 | Credential rotation | Provider refresh metadata lets the gateway refresh short-lived access tokens and update provider records. |
+| Brokered runtime tokens | Selected providers can keep long-lived identity material at the gateway and inject a sandbox-local token URL instead. |
 | Backward compatibility | Credential delivery still uses environment placeholders and proxy rewrite. |
 
 ## Enable Providers v2
@@ -60,6 +61,7 @@ Providers v2 currently includes these user-facing features:
 - Runtime sandbox provider lifecycle commands under `openshell sandbox provider list|attach|detach`.
 - Credential refresh configuration with `openshell provider refresh status|configure|rotate|delete`.
 - Credential expiry metadata with `openshell provider update --credential-expires-at`; values accept Unix epoch milliseconds or ISO/RFC3339 timestamps.
+- Brokered runtime provider contracts for workloads that need the gateway to mint tokens on demand instead of injecting the underlying secret.
 
 ## Roadmap
 
@@ -94,6 +96,7 @@ Built-in Providers v2 profiles currently include:
 |---|---|---|
 | `claude-code` | `agent` | `ANTHROPIC_API_KEY`, `CLAUDE_API_KEY` |
 | `github` | `source_control` | `GITHUB_TOKEN`, `GH_TOKEN` |
+| `microsoft-agent-s2s` | `agent` | `A365_TOKEN_PROVIDER_URL`, `OPENSHELL_MICROSOFT_AGENT_S2S_TOKEN_PROVIDER_URL`, `OPENSHELL_MICROSOFT_AGENT_S2S_TOKEN_URL`, optional `OPENSHELL_MICROSOFT_AGENT_S2S_DEFAULT_AUDIENCE` |
 | `nvidia` | `inference` | `NVIDIA_API_KEY` |
 
 Export a built-in profile as YAML:
@@ -236,6 +239,8 @@ binaries:
 
 `credentials` declares the credential names, environment variables, auth metadata, and optional refresh metadata for the provider type. The current runtime still exposes configured credential keys as placeholder environment variables and resolves placeholders in outbound HTTP requests.
 
+Some provider profiles intentionally use a brokered runtime contract instead of direct credential projection. `microsoft-agent-s2s` is the built-in example. It stores `A365_BLUEPRINT_CLIENT_SECRET` and related Microsoft identity config on the gateway, injects a sandbox-local token URL into the workload, and lets the gateway mint short-lived tokens for approved audiences on demand.
+
 `discovery` controls what `--from-existing` scans when
 `providers_v2_enabled=true`. Each entry in `discovery.credentials` must name a
 credential declared under `credentials`. OpenShell scans the referenced
@@ -274,6 +279,24 @@ Gateway-managed refresh strategies use these material keys:
 
 OpenShell keeps token endpoints profile-owned. Refresh material cannot override `token_url` or `token_uri` during refresh configuration.
 
+## Brokered Runtime Providers
+
+Most Providers v2 instances still follow the placeholder injection model: the sandbox process receives a credential placeholder such as `GITHUB_TOKEN`, then the proxy resolves it in outbound HTTP traffic.
+
+Brokered runtime providers are different. They keep the long-lived identity material at the gateway and inject a local token broker contract into the sandbox instead. The first built-in brokered provider is `microsoft-agent-s2s`.
+
+For `microsoft-agent-s2s`:
+
+- the provider instance stores `A365_BLUEPRINT_CLIENT_SECRET` as the credential
+- provider config stores `AZURE_TENANT_ID`, `A365_BLUEPRINT_CLIENT_ID`, `A365_RUNTIME_AGENT_ID`, and allowed audiences
+- the sandbox receives `A365_TOKEN_PROVIDER_URL` and related OpenShell metadata env vars
+- the workload calls the local URL when it needs a Microsoft bearer token
+- the gateway validates the attached provider and requested audience, then returns a short-lived token
+
+This is useful for workloads such as Microsoft Agent 365 or NAT/A365 integrations that already expect a token callback or resolver instead of a static bearer token.
+
+Brokered runtime providers do not currently imply provider-owned network policy. The built-in `microsoft-agent-s2s` profile intentionally ships without default endpoint rules, so you can pair it with the workload-specific policy or ingress model that fits your deployment.
+
 ## Provider Instances
 
 A provider instance stores concrete credentials and config for a profile type. Built-in profile IDs and imported custom profile IDs are accepted by `--type`.
