Onenote Upgrade Migration

Migration 1: App-Only to Delegated Auth

Before (broken after March 2025):

// OLD — ClientSecretCredential (DEPRECATED for OneNote)
import { ClientSecretCredential } from "@azure/identity";
const credential = new ClientSecretCredential(TENANT_ID, CLIENT_ID, CLIENT_SECRET);
const authProvider = new TokenCredentialAuthenticationProvider(credential, {
  scopes: ["https://graph.microsoft.com/.default"],
});

After:

// NEW — DeviceCodeCredential (required)
import { DeviceCodeCredential } from "@azure/identity";
const credential = new DeviceCodeCredential({
  clientId: CLIENT_ID, tenantId: TENANT_ID,
  userPromptCallback: (info) =>
    console.log(`Open ${info.verificationUri} and enter code: ${info.userCode}`),
});
const authProvider = new TokenCredentialAuthenticationProvider(credential, {
  scopes: ["Notes.Read", "Notes.ReadWrite"],  // Explicit, not .default
});
const client = Client.initWithMiddleware({ authProvider });

Python equivalent:

# OLD: credential = ClientSecretCredential(tenant_id, client_id, client_secret)
# NEW:
from azure.identity import DeviceCodeCredential
credential = DeviceCodeCredential(client_id=CLIENT_ID, tenant_id=TENANT_ID)

Required Azure portal changes: Add "Mobile and desktop applications" platform with http://localhost redirect URI to your app registration.

Migration 2: Webhooks to Polling

// OLD — Webhook subscription (DECOMMISSIONED June 2023)
// await client.api("/subscriptions").post({ resource: "/me/onenote/pages", ... });

// NEW — Polling with delta link tracking
async function pollForChanges(client: any, deltaLink: string | null) {
  const endpoint = deltaLink || "/me/onenote/notebooks";
  const response = await client.api(endpoint)
    .header("Prefer", "odata.track-changes").get();

  for (const item of response.value || []) {
    await processChange(item);
  }
  return response["@odata.deltaLink"] || deltaLink;
}

// Poll every 60s (stays under 600 req/60s per-user rate limit)
let deltaLink: string | null = null;
setInterval(async () => {
  try { deltaLink = await pollForChanges(client, deltaLink); }
  catch (err: any) {
    if (err?.statusCode === 429) {
      console.warn(`Rate limited. Retry after ${err.headers?.["retry-after"] ?? 30}s`);
    }
  }
}, 60_000);

Migration 3: Search Endpoint to OData Filters

// OLD — Search endpoint (DEPRECATED April 2024)
// const results = await client.api("/me/onenote/pages").query({ search: "term" }).get();

// NEW — OData filter for title, client-side for content
async function searchPages(client: any, query: string) {
  // Server-side title filter
  const titleMatches = await client.api("/me/onenote/pages")
    .filter(`contains(title,'${query.replace(/'/g, "''")}')`)
    .top(50).orderby("lastModifiedDateTime desc").get();

  // Client-side content search (Graph no longer supports full-text)
  const contentMatches: any[] = [];
  const pages = await client.api("/me/onenote/pages").top(100)
    .orderby("lastModifiedDateTime desc").get();
  for (const page of pages.value) {
    const html = await client.api(`/me/onenote/pages/${page.id}/content`).get();
    if (html.replace(/<[^>]+>/g, "").toLowerCase().includes(query.toLowerCase())) {
      contentMatches.push(page);
    }
  }

  // Deduplicate
  const seen = new Set(titleMatches.value.map((p: any) => p.id));
  return [...titleMatches.value, ...contentMatches.filter((m) => !seen.has(m.id))];
}

Migration 4: Graph SDK v5 to v6 (TypeScript)

// SDK v5 — callback-based auth (REMOVED in v6)
const client = Client.init({
  authProvider: (done) => done(null, accessToken),
});

// SDK v6 — middleware-based auth (REQUIRED)
import { TokenCredentialAuthenticationProvider } from
  "@microsoft/microsoft-graph-client/authProviders/azureTokenCredentials";
const authProvider = new TokenCredentialAuthenticationProvider(credential, {
  scopes: ["Notes.Read", "Notes.ReadWrite"],
});
const client = Client.initWithMiddleware({ authProvider });

Migration Checklists

Auth migration: Remove AZURE_CLIENT_SECRET from env/secrets. Add redirect URI in Azure portal. Replace .default with explicit scopes. Verify GET /me/onenote/notebooks returns 200.

SDK upgrade: Update @microsoft/microsoft-graph-client to v6+. Replace Client.init() with Client.initWithMiddleware(). Remove callback auth providers. Run full test suite.

Search migration: Replace /pages?search= with OData $filter. Add client-side content search fallback. Performance test: client-side search under 2s for 100 pages.

Feature Detection at Runtime

export function requiresDelegatedAuth(): boolean { return true; } // Since March 2025
export function isSearchEndpointAvailable(): boolean { return false; } // Since April 2024
export function isWebhookAvailable(): boolean { return false; } // Since June 2023

Rollback Strategy

Use a feature flag for gradual auth migration:

const useDelegated = process.env.ONENOTE_AUTH_MODE !== "legacy";
const credential = useDelegated
  ? new DeviceCodeCredential({ clientId, tenantId })
  : new ClientSecretCredential(tenantId, clientId, clientSecret); // Legacy fallback

Output

• Auth migration: ClientSecretCredential to DeviceCodeCredential with code diff
• Webhook migration: subscription API to polling with delta queries
• Search migration: deprecated endpoint to OData filters + client-side search
• SDK v5 to v6: Client.init() to Client.initWithMiddleware()
• Migration checklists and feature detection module
• Rollback strategy with feature flag pattern

Error Handling

Examples

# Check which migrations your codebase needs
grep -r "ClientSecretCredential" src/ --include="*.ts" --include="*.py"
grep -r "search=" src/ --include="*.ts" --include="*.py"
grep -r "/subscriptions" src/ --include="*.ts" --include="*.py"
grep -r "Client.init(" src/ --include="*.ts"

// Smoke test after auth migration
const client = getGraphClient();
const nb = await client.api("/me/onenote/notebooks").top(1).get();
console.log("Auth migration OK:", nb.value.length, "notebooks");

Resources

• OneNote API Overview
• Graph API Known Issues
• Azure App Registration
• MSAL Python
• OneNote Error Codes

Next Steps

• Set up CI for migrated code with onenote-ci-integration
• Debug migration issues with onenote-debug-bundle
• Review security after migration with onenote-security-basics