Tools
Microsoft Graph
By Community-maintained OpenClaw plugin providing bounded, default-deny Microsoft Graph access for OneDrive, Outlook Mail, Calendar, and Microsoft To Do.
Install
openclaw plugins install npm:@baumus/[email protected]README
# Microsoft Graph for OpenClaw
`@baumus/openclaw-microsoft-graph` is a community-maintained OpenClaw tool plugin for bounded Microsoft Graph v1.0 access to OneDrive, Outlook Calendar, Outlook Mail, and Microsoft To Do. It is not an official Microsoft or OpenClaw product and carries no enterprise, compliance, or security certification.
## Security model
- Every operation is checked against a credential-free, default-deny per-agent policy before plugin-side key selection, vault I/O, OAuth, or Graph access.
- Warning-level mutations require OpenClaw-native call approval by default. Operators may explicitly set `warningApprovalsRequired: false`; critical delete, send, and respond operations always retain native call-bound approval.
- One shared delegated OAuth credential serves every authorized read and write operation. The plugin requests only the operation-specific scope for each exchange.
- One AES-256-GCM encrypted vault record, one fail-closed lock, and one authenticated quarantine marker protect the rotating refresh-token lifecycle.
- Access-token caching is bounded and transactional: a token associated with a rotated refresh token is admitted only after durable vault replacement and verification.
- Every refresh durably publishes authenticated `in_flight` state before OAuth dispatch; uncertainty transitions it to `quarantined`, and either state blocks another exchange until verified completion, explicit recovery, or reauthorization.
- HTTP-200 OAuth responses require a 1–16 KiB RFC 6750 `b64token`/header-safe access token and a positive integer `expires_in` no greater than 86,400 seconds. Cache residency is capped at one hour with a 60-second skew.
This simpler shared-credential model has an explicit tradeoff: compromise of the credential, vault key, or a plugin bypass can expose the union of Microsoft delegated scopes granted to that credential. The policy and write-approval gates constrain normal plugin behavior; they are not provider-side credential isolation.
See [architecture](docs/ARCHITECTURE.md), [OAuth access matrix](docs/OAUTH_ACCESS_MATRIX.md), [vault design](docs/CREDENTIAL_VAULT_DESIGN.md), and [support](docs/SUPPORT.md).
## Setup guide
Version 3.5.0 uses one Microsoft delegated OAuth credential and one encrypted local vault. The policy contains authorization rules only; it never contains credential locations or credential material.
### 1. Check prerequisites
You need:
- Node.js `>=24.16.0 <25` or `>=26.1.0`.
- OpenClaw `>=2026.9.6` running as the OS account that will own the plugin state.
- A Microsoft Entra app registration and one delegated user grant for the account the plugin will use. Application permissions, client secrets, certificates, and daemon/service-principal flows are not supported.
- GNU `pass` and GPG only if you choose the optional emergency `restore-pass` backup. Normal setup and tool calls do not use `pass`.
- Permission to edit the OpenClaw configuration and to review the third-party plugin's declared capabilities.
Check the local versions before continuing:
```bash
node --version
openclaw --version
```
### 2. Prepare the Microsoft delegated credential
1. Register an application in Microsoft Entra and record its **Application (client) ID**. Select the tenant/account audience appropriate for your organization.
2. Enable public-client/device-code support for that application in accordance with tenant policy. No client secret is needed or accepted. An administrator may need to grant delegated consent first; tenant conditional-access and consent rules remain authoritative.
3. Configure the policy and vault-key SecretRef below. Then open the Microsoft Graph plugin page in the OpenClaw Control UI and follow **Connect to Microsoft** in section 7. The Gateway derives requested delegated scopes from the configured policy and stores the refresh token directly in the encrypted vault. No token is copied into a file or command argument.
### 3. Install version 3.5.0
Version 3.5.0 is not yet available from npm. After publication, install the exact reviewed package and version:
```bash
openclaw plugins install npm:@baumus/[email protected] --pin
```
Review the package source, integrity, and declared capabilities before accepting the interactive consent prompt. Installation does not create credentials, consent Microsoft permissions, grant tool access, or make an incomplete configuration usable. OpenClaw may leave the plugin disabled until its required configuration is present.
### 4. Create the vault-key SecretRef
`credentialVaultKey` accepts a structured OpenClaw SecretRef only. A plaintext string in `openclaw.json` is rejected. The resolved value must be exactly 32 random bytes encoded as canonical, unpadded base64url (43 characters).
The built-in team secret store is the simplest supported provider. The following command generates the key without printing it and writes it as a secret-kind value:
```bash
node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("base64url"))' \
| openclaw secrets store set MICROSOFT_GRAPH_CREDENTIAL_VAULT_KEY --kind secret --value-file -
```
Reference it with the complete object shape:
```json5
credentialVaultKey: {
source: "store",
provider: "default",
id: "MICROSOFT_GRAPH_CREDENTIAL_VAULT_KEY",
}
```
You may instead use an `env`, `file`, or `exec` SecretRef backed by a correctly configured OpenClaw secret provider. Do not replace the object with the resolved value. Back up the SecretRef provider independently from the encrypted vault; losing or changing this key makes the existing vault unreadable.
### 5. Create a version-2 default-deny policy
Copy [the shipped v2 example](examples/microsoft-graph-policy-v2.json5) to `microsoft-graph-policy.json5` beside `openclaw.json`, then replace every placeholder. `$include` paths are resolved relative to the file that contains them and normally must remain inside the top-level config directory.
A conservative OneDrive read-only policy looks like this:
```json5
{
version: 2,
rules: { default: "deny" },
services: {
onedrive: {
allowed_roots: [{
label: "documents",
path: "/Documents",
drive_id: "replace-with-immutable-drive-id",
item_id: "replace-with-immutable-root-item-id",
include_descendants: true,
permissions: { read: true, write: false, delete: false },
agents: {
"replace-with-openclaw-agent-id": {
permissions: { read: true, write: false, delete: false },
},
},
}],
},
calendar: {
agents: {
// "replace-with-openclaw-agent-id": { operations: ["read"], resources: ["me"] },
},
},
mail: { agents: {} },
todo: { agents: {} },
},
}
```
Use agent IDs from the OpenClaw host configuration; the plugin does not infer policy grants from local workspace content. For OneDrive, obtain the immutable drive and item IDs with Microsoft Graph Explorer or another tenant-approved administrative client; the display path alone is not an authorization boundary. Calendar grants may use `me` or exact calendar IDs. Mail and To Do use fixed signed-in-user `/me` routes. Add only the operations and resources you intend to permit, and add the corresponding delegated scopes to the one credential.
Keep `rules.default: "deny"`. `include_descendants` must be literal `true`; remove a root entirely if descendants must not be available. Leave `agents_instructions` absent unless trusted administrators control every writer to that root and you intentionally set `agents_instructions: "trusted"`. This optional plugin feature applies OpenClaw's standard `AGENTS.md` instruction format to policy-pinned OneDrive content; it does not read, copy, or modify the host agent's local workspace `AGENTS.md`.
### 6. Configure and enable the plugin
Add the following shape to `openclaw.json`. If you already use `tools.allow`, merge `microsoft-graph` into that existing allowlist instead of replacing unrelated entries.
```json5
{
plugins: {
entries: {
"microsoft-graph": {
enabled: true,
config: {
enabled: true,
warningApprovalsRequired: true,
credentialVaultKey: {
source: "store",
provider: "default",
id: "MICROSOFT_GRAPH_CREDENTIAL_VAULT_KEY",
},
policy: { $include: "./microsoft-graph-policy.json5" },
},
},
},
},
tools: { allow: ["microsoft-graph"] },
}
```
`$include` is OpenClaw host-config composition. The plugin receives the resolved policy object and does not read policy files itself. If the plugin remains disabled after saving valid configuration, enable it explicitly and accept capabilities only after review:
`warningApprovalsRequired` defaults to `true` when omitted. Set it to `false` only when policy-authorized warning-level mutations should run without an approval prompt. This setting never affects critical approvals and never bypasses policy authorization, parameter validation, managed-root instruction checks, protected-media checks, or write preconditions.
```bash
openclaw plugins enable microsoft-graph
```
### 7. Sign in from the browser UI
Open **Plugins → Microsoft Graph** in an administrator Control UI session. Save the access rules and wait until the page confirms that the Gateway has applied them. Under **Connect to Microsoft**, enter the approved public application's client ID and tenant ID/domain, then select **Start sign-in**. Open the Microsoft link, enter the one-time code shown on this page, and approve the displayed delegated permissions. The page detects completion automatically; you can cancel before authorization finishes.
The Gateway, not the browser, polls Microsoft's token endpoint, verifies the granted scopes against the applied policy, and writes the refresh token directly to an **empty encrypted vault**. The UI only receives a one-time code, scoped status, and sanitize
... (truncated)
tools
Comments
Sign in to leave a comment