Refresh Microsoft Graph Credentials with Providers v2

Enable Providers v2

Enable provider profile policy composition on the active gateway:

$
openshell settings set --global --key providers_v2_enabled --value true --yes

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-mail
display_name: Microsoft Graph Mail
description: Delegated Microsoft Graph mail read access
category: messaging
credentials:
  - 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_seconds: 600
      max_lifetime_seconds: 3600
      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: true
endpoints:
  - host: graph.microsoft.com
    port: 443
    protocol: rest
    access: read-only
    enforcement: enforce
binaries:
  - /usr/bin/curl
  - /usr/local/bin/curl

Lint and import the profile:

$
openshell provider profile lint -f microsoft-graph-mail.yaml
$
openshell provider profile import -f microsoft-graph-mail.yaml

The 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

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

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_TOKEN

Check refresh status:

$
openshell provider refresh status microsoft-mail \
>
  --credential-key MS_GRAPH_ACCESS_TOKEN

The 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

Launch a sandbox with the Microsoft Graph provider attached:

$
openshell sandbox create \
>
  --name microsoft-graph-mail \
>
  --keep \
>
  --provider microsoft-mail \
>
  --no-auto-providers \
>
  -- /bin/sh

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.

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

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.