Refresh Microsoft Graph Credentials with a Provider Profile
Configure a Microsoft Graph provider profile with gateway-managed OAuth2 refresh-token rotation.
Use a provider profile 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.
After completing this tutorial, you have:
- A custom Microsoft Graph mail provider profile.
- A provider instance configured with
oauth2-refresh-token. - A sandbox that can use
curlto read Microsoft Graph mail through provider-owned policy.
Prerequisites
Section titled “Prerequisites”- A working OpenShell installation with an active gateway. Refer to Installation before proceeding.
- A Microsoft Entra app registration that can acquire delegated Microsoft Graph mail access.
- Delegated Microsoft Graph mail permission for the signed-in user.
Mail.Readallows reading the signed-in user’s mailbox; see the Microsoft Graph permissions reference. OAuth material from your initial Microsoft sign-in flow:
| Variable | Value |
|---|---|
MS_TENANT_ID |
Microsoft Entra tenant ID, domain, or common. |
MS_CLIENT_ID |
Microsoft Entra application client ID. |
MS_GRAPH_ACCESS_TOKEN |
Current delegated Microsoft Graph access token. |
MS_GRAPH_REFRESH_TOKEN |
Delegated OAuth refresh token. |
MS_GRAPH_ACCESS_TOKEN_EXPIRES_AT |
Absolute expiry for the current access token. |
MS_GRAPH_ACCESS_TOKEN_EXPIRES_AT can be an RFC3339 timestamp such as 2026-01-01T00:00:00Z or a Unix epoch millisecond timestamp.
Create a Microsoft Graph Provider Profile
Section titled “Create a Microsoft Graph Provider Profile”Create microsoft-graph-mail.yaml with this profile:
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.# SPDX-License-Identifier: Apache-2.0
id: microsoft-graph-maildisplay_name: Microsoft Graph Maildescription: Delegated Microsoft Graph mail read accesscategory: messagingcredentials: - name: graph_access_token description: Microsoft Graph delegated access token env_vars: [MS_GRAPH_ACCESS_TOKEN] required: true auth_style: bearer header_name: authorization refresh: strategy: oauth2_refresh_token token_url: https://login.microsoftonline.com/common/oauth2/v2.0/token scopes: [https://graph.microsoft.com/.default] refresh_before: "600s" max_lifetime: "3600s" material: - name: tenant_id description: Microsoft Entra tenant ID required: true - name: client_id description: Microsoft Entra application client ID required: true - name: refresh_token description: Delegated OAuth refresh token required: true secret: trueendpoints: - host: graph.microsoft.com port: 443 protocol: rest access: read-only enforcement: enforcebinaries: - /usr/bin/curl - /usr/local/bin/curlLint and import the profile:
openshell profile lint -f microsoft-graph-mail.yamlopenshell profile import -f microsoft-graph-mail.yamlThe profile defines the refresh strategy and Graph network policy. The tenant_id refresh material selects the Microsoft token endpoint during gateway-managed refresh.
Create the Provider
Section titled “Create the Provider”Create the provider with the current Microsoft Graph access token:
openshell provider create \ --name microsoft-mail \ --type microsoft-graph-mail \ --credential MS_GRAPH_ACCESS_TOKEN="$MS_GRAPH_ACCESS_TOKEN"The current CLI requires an initial credential at provider creation time. Refresh material is configured separately and is not injected into the sandbox.
Configure Refresh
Section titled “Configure Refresh”Configure gateway-managed OAuth2 refresh-token rotation:
openshell provider refresh configure microsoft-mail \ --credential-key MS_GRAPH_ACCESS_TOKEN \ --strategy oauth2-refresh-token \ --material tenant_id="$MS_TENANT_ID" \ --material client_id="$MS_CLIENT_ID" \ --material refresh_token="$MS_GRAPH_REFRESH_TOKEN" \ --secret-material-key refresh_token \ --credential-expires-at "$MS_GRAPH_ACCESS_TOKEN_EXPIRES_AT"--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.
Force the first refresh immediately:
openshell provider refresh rotate microsoft-mail \ --credential-key MS_GRAPH_ACCESS_TOKENCheck refresh status:
openshell provider refresh status microsoft-mail \ --credential-key MS_GRAPH_ACCESS_TOKENThe status output shows refresh state, expiry, next refresh, and last refresh timing. It does not print access-token values or refresh material.
Launch a Sandbox
Section titled “Launch a Sandbox”Launch a sandbox with the Microsoft Graph provider attached:
openshell sandbox create \ --name microsoft-graph-mail \ --from registry.example.com/team/agent-tools:1.0 \ --provider microsoft-mail \ --no-auto-providers \ -- /bin/shProvider 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.
Verify Microsoft Graph Access
Section titled “Verify Microsoft Graph Access”Inside the sandbox, list a small page of mailbox messages:
curl -sS \ -H "Authorization: Bearer $MS_GRAPH_ACCESS_TOKEN" \ 'https://graph.microsoft.com/v1.0/me/messages?$select=sender,subject&$top=5'The request uses the Microsoft Graph list messages API. If the token has delegated mail read permission, Microsoft Graph returns message metadata for the signed-in user’s mailbox.
Update Running Sandboxes
Section titled “Update Running Sandboxes”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.
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.
We are a Cloud Native Computing Foundation sandbox project.
Copyright OpenShell a Series of LF Projects, LLC
For website terms of use, trademark policy and other project policies please see lfprojects.org/policies/.