Microsoft Calendar Integration

Purpose and Scope

This page explains how to configure the Microsoft Calendar integration for a self-hosted Cal.diy instance. In Cal.diy terminology, the Microsoft calendar integration is the Office 365 Calendar app backed by Microsoft Graph OAuth credentials. The reader task is to create a Microsoft Entra ID app registration, connect its redirect URI to the Cal.diy callback route, and provide the resulting client credentials to the Cal.diy environment so users can add their Microsoft calendars from the application.

Sources: apps/docs/content/apps/microsoft.mdx, packages/app-store/office365calendar/api/index.ts

The official setup flow is intentionally small: Cal.diy needs a Microsoft Graph application client ID, a client secret, and a web redirect URI that points back to the running Cal.diy deployment. The app-store package source then exposes the Office 365 Calendar API surface through add and callback exports. That split matters operationally: administrators configure credentials outside the app, while the runtime uses the Office 365 Calendar app package to start the add flow and complete the OAuth callback.

Sources: apps/docs/content/apps/microsoft.mdx, packages/app-store/office365calendar/api/index.ts

Relevant Source Files

• apps/docs/content/apps/microsoft.mdx - The first-party Microsoft integration setup guide. It documents the Azure App Registration flow, the multitenant account type, the exact OAuth redirect URI, and the MS_GRAPH_CLIENT_ID and MS_GRAPH_CLIENT_SECRET environment variables.
• packages/app-store/office365calendar/api/index.ts - The Office 365 Calendar app-store API barrel. It re-exports the add and callback handlers used by the integration package surface.

Configuration Flow

Start in the Azure portal under App registrations and create a new registration for Cal.diy. The documented account type is Accounts in any organizational directory (Any Azure AD directory - Multitenant), which makes the registration usable across Azure AD tenants rather than only the tenant where it was created. Choose a clear application name that identifies the Cal.diy instance or environment, especially if you operate separate development, staging, and production-like self-hosted deployments.

Sources: apps/docs/content/apps/microsoft.mdx

During registration, configure a Web redirect URI that points to the Cal.diy Office 365 Calendar callback route. The documented URI format is tied to the externally reachable base URL of your instance. Replace <Cal.diy URL> with the URL users actually load in their browser; do not use an internal container hostname unless that is also the browser-facing URL. This is the value Microsoft will compare during OAuth, so a mismatch in scheme, host, path, or deployed domain can prevent the callback from completing.

Sources: apps/docs/content/apps/microsoft.mdx

<Cal.diy URL>/api/integrations/office365calendar/callback

After the app registration exists, copy the Application (client) ID into the Cal.diy .env file as MS_GRAPH_CLIENT_ID. Then open Certificates and secrets in the Azure app registration, create a new client secret, and store the generated secret value as MS_GRAPH_CLIENT_SECRET. The generated secret is the value Cal.diy uses during the OAuth exchange, so capture it when Azure displays it and treat it as sensitive deployment configuration.

Sources: apps/docs/content/apps/microsoft.mdx

MS_GRAPH_CLIENT_ID=<application-client-id>
MS_GRAPH_CLIENT_SECRET=<generated-client-secret>

System-to-Code Mapping

The documentation names the browser-visible callback route as /api/integrations/office365calendar/callback. In the app-store package, the Office 365 Calendar API entrypoint re-exports a callback handler from ./callback, which is the package-level symbol corresponding to the OAuth return path. The same barrel also re-exports add from ./add, indicating that the app exposes both the flow that begins connecting a calendar and the flow that receives Microsoft’s OAuth response.

Sources: packages/app-store/office365calendar/api/index.ts

This mapping helps separate configuration failures from code-surface questions. If Microsoft rejects the redirect, first verify the Azure Web redirect URI and the Cal.diy public URL. If the user cannot begin the connection flow, the relevant app-store surface is the add export. If Microsoft returns the user to Cal.diy but completion fails, the relevant public surface is the callback export and the configured Microsoft Graph credentials.

Sources: apps/docs/content/apps/microsoft.mdx, packages/app-store/office365calendar/api/index.ts

Operational Checklist

Before asking users to connect Microsoft Calendar, confirm that the self-hosted instance has a stable externally reachable URL and that the exact URL is used in the Azure app registration. OAuth providers compare redirect URIs strictly, so changing from HTTP to HTTPS, moving to another domain, or adding a reverse proxy can require updating the registration. For local experiments, use the local URL that Microsoft can redirect to; for deployed instances, use the production-like public URL that users will access.

Sources: apps/docs/content/apps/microsoft.mdx

Next, confirm the credentials are present in the environment loaded by the Cal.diy web application. The Microsoft setup page specifically calls for placing the Application client ID in MS_GRAPH_CLIENT_ID and the generated client secret in MS_GRAPH_CLIENT_SECRET in .env. After changing these values, restart the relevant Cal.diy process so the runtime reads the new environment. If you rotate the secret in Azure, update Cal.diy at the same time to avoid broken OAuth exchanges.

Sources: apps/docs/content/apps/microsoft.mdx

Finally, test from the same UI path users will use to add calendars. The source package exposes an add entrypoint for beginning the Office 365 Calendar integration and a callback entrypoint for completing it. A successful test should leave the user able to add the Microsoft calendar integration and return through /api/integrations/office365calendar/callback without a redirect mismatch or credential error. Keep the Azure app registration name and secret lifetime documented for future maintenance.

Sources: packages/app-store/office365calendar/api/index.ts, apps/docs/content/apps/microsoft.mdx

Next Steps

After Microsoft Calendar is configured, review the broader apps documentation for other providers that follow a similar OAuth pattern, especially Google Calendar and Zoho Calendar if your users need multiple external calendars. For deployment-related OAuth problems, check the environment and URL guidance before changing app credentials, because most redirect failures come from an incorrect public base URL rather than from the Office 365 Calendar package itself.