Skip to content

Commit 03589fe

Browse files
committed
docs(providers): add Microsoft Graph refresh tutorial
Signed-off-by: John Myers <9696606+johntmyers@users.noreply.github.com>
1 parent 35cbc06 commit 03589fe

2 files changed

Lines changed: 194 additions & 0 deletions

File tree

‎docs/get-started/tutorials/index.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,11 @@ Create a sandbox, observe default-deny networking, apply a read-only L7 policy,
2222
Launch Claude Code in a sandbox, diagnose a policy denial, and iterate on a custom GitHub policy from outside the sandbox.
2323
</Card>
2424

25+
<Card title="Microsoft Graph Provider Refresh" href="/get-started/tutorials/microsoft-graph-provider-refresh">
26+
27+
Configure a Providers v2 Microsoft Graph provider with gateway-managed OAuth2 refresh-token rotation.
28+
</Card>
29+
2530
<Card title="Inference with Ollama" href="/get-started/tutorials/inference-ollama">
2631

2732
Route inference through Ollama using cloud-hosted or local models, and verify it from a sandbox.
Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
---
2+
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
3+
# SPDX-License-Identifier: Apache-2.0
4+
title: "Refresh Microsoft Graph Credentials with Providers v2"
5+
sidebar-title: "Microsoft Graph Provider Refresh"
6+
slug: "get-started/tutorials/microsoft-graph-provider-refresh"
7+
description: "Configure a Providers v2 Microsoft Graph profile with gateway-managed OAuth2 refresh-token rotation."
8+
keywords: "Generative AI, Cybersecurity, Tutorial, Providers, Microsoft Graph, OAuth2, Credential Refresh, Sandbox"
9+
---
10+
11+
Use Providers v2 to keep Microsoft Graph access tokens short lived while sandboxes receive a stable `MS_GRAPH_ACCESS_TOKEN` placeholder. OpenShell stores the non-injectable refresh material at the gateway, refreshes the Microsoft Graph access token before it expires, updates the provider record, and injects the current credential into newly launched sandbox processes.
12+
13+
After completing this tutorial, you have:
14+
15+
- A custom Microsoft Graph mail provider profile.
16+
- A provider instance configured with `oauth2-refresh-token`.
17+
- A sandbox that can use `curl` to read Microsoft Graph mail through provider-owned policy.
18+
19+
<Note>
20+
This tutorial starts after your OAuth client has already completed the initial Microsoft sign-in flow. It does not publish a token bootstrap script. Use the Microsoft identity platform documentation for the [device authorization grant flow](https://learn.microsoft.com/en-ie/entra/identity-platform/v2-oauth2-device-code) or [authorization code flow](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-auth-code-flow), and use any standards-compliant client that returns an access token, refresh token, and expiry.
21+
</Note>
22+
23+
## Prerequisites
24+
25+
- A working OpenShell installation with an active gateway. Complete the [Quickstart](/get-started/quickstart) before proceeding.
26+
- A Microsoft Entra app registration that can acquire delegated Microsoft Graph mail access.
27+
- Delegated Microsoft Graph mail permission for the signed-in user. `Mail.Read` allows reading the signed-in user's mailbox; see the [Microsoft Graph permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference).
28+
OAuth material from your initial Microsoft sign-in flow:
29+
30+
| Variable | Value |
31+
|---|---|
32+
| `MS_TENANT_ID` | Microsoft Entra tenant ID, domain, or `common`. |
33+
| `MS_CLIENT_ID` | Microsoft Entra application client ID. |
34+
| `MS_GRAPH_ACCESS_TOKEN` | Current delegated Microsoft Graph access token. |
35+
| `MS_GRAPH_REFRESH_TOKEN` | Delegated OAuth refresh token. |
36+
| `MS_GRAPH_ACCESS_TOKEN_EXPIRES_AT` | Absolute expiry for the current access token. |
37+
38+
`MS_GRAPH_ACCESS_TOKEN_EXPIRES_AT` can be an RFC3339 timestamp such as `2026-01-01T00:00:00Z` or a Unix epoch millisecond timestamp.
39+
40+
<Warning>
41+
Do not commit access tokens, refresh tokens, or local `.env` files. The commands below pass token material to the gateway; they are not examples of values to store in source control.
42+
</Warning>
43+
44+
<Steps toc={true}>
45+
46+
## Enable Providers v2
47+
48+
Enable provider profile policy composition on the active gateway:
49+
50+
```shell
51+
openshell settings set --global --key providers_v2_enabled --value true --yes
52+
```
53+
54+
## Create a Microsoft Graph Provider Profile
55+
56+
Create `microsoft-graph-mail.yaml` with this profile:
57+
58+
```yaml showLineNumbers={false}
59+
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
60+
# SPDX-License-Identifier: Apache-2.0
61+
62+
id: microsoft-graph-mail
63+
display_name: Microsoft Graph Mail
64+
description: Delegated Microsoft Graph mail read access
65+
category: messaging
66+
credentials:
67+
- name: graph_access_token
68+
description: Microsoft Graph delegated access token
69+
env_vars: [MS_GRAPH_ACCESS_TOKEN]
70+
required: true
71+
auth_style: bearer
72+
header_name: authorization
73+
refresh:
74+
strategy: oauth2_refresh_token
75+
token_url: https://login.microsoftonline.com/common/oauth2/v2.0/token
76+
scopes: [https://graph.microsoft.com/.default]
77+
refresh_before_seconds: 600
78+
max_lifetime_seconds: 3600
79+
material:
80+
- name: tenant_id
81+
description: Microsoft Entra tenant ID
82+
required: true
83+
- name: client_id
84+
description: Microsoft Entra application client ID
85+
required: true
86+
- name: refresh_token
87+
description: Delegated OAuth refresh token
88+
required: true
89+
secret: true
90+
endpoints:
91+
- host: graph.microsoft.com
92+
port: 443
93+
protocol: rest
94+
access: read-only
95+
enforcement: enforce
96+
binaries:
97+
- /usr/bin/curl
98+
- /usr/local/bin/curl
99+
```
100+
101+
Lint and import the profile:
102+
103+
```shell
104+
openshell provider profile lint -f microsoft-graph-mail.yaml
105+
openshell provider profile import -f microsoft-graph-mail.yaml
106+
```
107+
108+
The profile defines the refresh strategy and Graph network policy. The `tenant_id` refresh material selects the Microsoft token endpoint during gateway-managed refresh.
109+
110+
## Create the Provider
111+
112+
Create the provider with the current Microsoft Graph access token:
113+
114+
```shell
115+
openshell provider create \
116+
--name microsoft-mail \
117+
--type microsoft-graph-mail \
118+
--credential MS_GRAPH_ACCESS_TOKEN="$MS_GRAPH_ACCESS_TOKEN"
119+
```
120+
121+
The current CLI requires an initial credential at provider creation time. Refresh material is configured separately and is not injected into the sandbox.
122+
123+
## Configure Refresh
124+
125+
Configure gateway-managed OAuth2 refresh-token rotation:
126+
127+
```shell
128+
openshell provider refresh configure microsoft-mail \
129+
--credential-key MS_GRAPH_ACCESS_TOKEN \
130+
--strategy oauth2-refresh-token \
131+
--material tenant_id="$MS_TENANT_ID" \
132+
--material client_id="$MS_CLIENT_ID" \
133+
--material refresh_token="$MS_GRAPH_REFRESH_TOKEN" \
134+
--secret-material-key refresh_token \
135+
--credential-expires-at "$MS_GRAPH_ACCESS_TOKEN_EXPIRES_AT"
136+
```
137+
138+
`--secret-material-key refresh_token` names the material key to mark as sensitive. It is not the refresh-token value. If Microsoft returns a rotated refresh token during refresh, OpenShell stores the new `refresh_token` material and marks it secret automatically.
139+
140+
Force the first refresh immediately:
141+
142+
```shell
143+
openshell provider refresh rotate microsoft-mail \
144+
--credential-key MS_GRAPH_ACCESS_TOKEN
145+
```
146+
147+
Check refresh status:
148+
149+
```shell
150+
openshell provider refresh status microsoft-mail \
151+
--credential-key MS_GRAPH_ACCESS_TOKEN
152+
```
153+
154+
The status output shows refresh state, expiry, next refresh, and last refresh timing. It does not print access-token values or refresh material.
155+
156+
## Launch a Sandbox
157+
158+
Launch a sandbox with the Microsoft Graph provider attached:
159+
160+
```shell
161+
openshell sandbox create \
162+
--name microsoft-graph-mail \
163+
--keep \
164+
--provider microsoft-mail \
165+
--no-auto-providers \
166+
-- /bin/sh
167+
```
168+
169+
Provider policy allows `curl` to reach `graph.microsoft.com:443`. The sandbox process receives `MS_GRAPH_ACCESS_TOKEN` as an OpenShell placeholder, and the proxy resolves that placeholder to the current gateway-managed access token when `curl` sends it in the authorization header.
170+
171+
## Verify Microsoft Graph Access
172+
173+
Inside the sandbox, list a small page of mailbox messages:
174+
175+
```shell
176+
curl -sS \
177+
-H "Authorization: Bearer $MS_GRAPH_ACCESS_TOKEN" \
178+
'https://graph.microsoft.com/v1.0/me/messages?$select=sender,subject&$top=5'
179+
```
180+
181+
The request uses the [Microsoft Graph list messages API](https://learn.microsoft.com/en-us/graph/api/user-list-messages?view=graph-rest-1.0). If the token has delegated mail read permission, Microsoft Graph returns message metadata for the signed-in user's mailbox.
182+
183+
## Update Running Sandboxes
184+
185+
Provider refresh updates the provider record at the gateway. Running sandboxes poll for provider environment revisions, but already-running processes keep the environment they started with.
186+
187+
If you attach this provider to an existing sandbox or update provider credentials after a process has already started, launch a new process inside the sandbox before expecting `MS_GRAPH_ACCESS_TOKEN` to appear in that process environment.
188+
189+
</Steps>

0 commit comments

Comments
 (0)