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