Skip to content

Microsoft Calendar Integration

Sync Outlook/Microsoft 365 calendar events with Kiket for team capacity planning and availability tracking.

Overview

The Microsoft Calendar integration automatically imports calendar events from Outlook and updates team member availability. This is ideal for organizations using Microsoft 365.

Prerequisites

Before connecting Microsoft Calendar, you need:

  1. Microsoft OAuth Extension installed (microsoft-oauth)
  2. Microsoft Calendar Extension installed (microsoft-calendar)
  3. A Microsoft 365 or personal Microsoft account

Installation

Step 1: Install OAuth Provider

First, install the Microsoft OAuth provider extension:

  1. Go to Settings > Extensions > Browse
  2. Search for "Microsoft OAuth"
  3. Click Install
  4. Configure the OAuth credentials:
  5. Register an application in Azure Portal
  6. Set the redirect URI to https://your-domain.kiket.dev/oauth/microsoft-oauth/callback
  7. Create a client secret
  8. Enter the Application (Client) ID and Client Secret in Kiket

Step 2: Azure AD App Registration

When creating your Azure AD app registration:

  1. Go to Azure Portal > Azure Active Directory > App registrations
  2. Click New registration
  3. Enter a name (e.g., "Kiket Calendar Integration")
  4. Set supported account types:
  5. Single tenant: For your organization only
  6. Multi-tenant: For any Microsoft account
  7. Add a redirect URI: https://your-domain.kiket.dev/oauth/microsoft-oauth/callback
  8. Under API permissions, add:
  9. Calendars.Read (Delegated)
  10. User.Read (Delegated)
  11. Under Certificates & secrets, create a new client secret

Step 3: Install Calendar Extension

  1. Go to Settings > Extensions > Browse
  2. Search for "Microsoft Calendar"
  3. Click Install

Step 4: Connect Your Account

  1. Go to Settings > Connected Accounts
  2. Click Connect next to Microsoft
  3. Sign in with your Microsoft account
  4. Grant the requested calendar permissions

Adding a Calendar Feed

Once connected:

  1. Go to Capacity > Calendar Settings
  2. Click Add Calendar
  3. Select Microsoft Calendar as the source
  4. Choose the calendar(s) you want to sync
  5. Configure sync settings:
  6. Sync Interval: How often to check for updates (default: 60 minutes)
  7. Sync Window: How far ahead to sync events (default: 180 days)
  8. Include Private: Whether to sync private events (title only)
  9. Include Tentative: Whether to sync tentative events

Event Type Mapping

Outlook calendar events are automatically categorized based on keywords and Outlook categories:

Event Type Keywords
Holiday "holiday", "bank holiday"
PTO "vacation", "pto", "out of office", "ooo", "time off"
Travel "travel", "flight", "trip"
Focus "focus", "deep work", "heads down", "focus time"
Training "training", "learning", "workshop"
Other Everything else

Outlook's "Show As" status is also considered:

  • Free: Typically ignored for capacity
  • Tentative: Included if "Include Tentative" is enabled
  • Busy/Out of Office: Always included
  • Working Elsewhere: Included as "other"

Using with Microsoft Teams

If you also use the Microsoft Teams extension, both can share the same Microsoft OAuth connection:

  1. Install microsoft-oauth (one time)
  2. Connect your Microsoft account
  3. Install both microsoft-teams and microsoft-calendar
  4. Both extensions will use the same connection

This is the recommended setup for Microsoft 365 organizations.

Health Monitoring

Kiket monitors calendar feed health and alerts you when syncs fail:

  • Healthy: Syncing normally
  • Degraded: Multiple consecutive failures (3+)
  • Unhealthy: Failing for 12+ hours

You'll receive notifications in Kiket and optionally via Microsoft Teams when issues occur.

Troubleshooting

"Insufficient privileges" error

This usually means the Azure AD app doesn't have the required permissions:

  1. Go to Azure Portal > App registrations
  2. Select your app
  3. Go to API permissions
  4. Ensure Calendars.Read is added
  5. Click Grant admin consent if required by your organization

"AADSTS50011: Reply URL does not match"

The redirect URI doesn't match:

  1. Go to Azure Portal > App registrations
  2. Select your app
  3. Go to Authentication
  4. Add the exact URL: https://your-domain.kiket.dev/oauth/microsoft-oauth/callback

Events not appearing

  1. Verify the calendar is selected for sync
  2. Check if events fall within the sync window
  3. For private events, ensure "Include Private" is enabled
  4. Check the feed health status

Token refresh failing

Microsoft tokens expire after 90 days of inactivity:

  1. Go to Settings > Connected Accounts
  2. Click Reconnect next to Microsoft
  3. Sign in again to refresh the token

API Reference

The Microsoft Calendar extension provides these commands:

# Trigger manual sync
microsoftCalendar.sync:
  calendar_id: "primary"

# List available calendars
microsoftCalendar.listCalendars: {}

Security

  • Only the Calendars.Read and User.Read scopes are requested by default
  • Events are synced as read-only; Kiket cannot modify your Outlook calendar
  • Tokens can be revoked at any time from Settings > Connected Accounts
  • You can also revoke access from Microsoft Account Security

Enterprise Considerations

For enterprise deployments:

  1. Tenant Restriction: Set the Tenant ID in the Microsoft OAuth extension to restrict to your organization
  2. Admin Consent: If your organization requires admin consent, an Azure AD admin must approve the app
  3. Conditional Access: Ensure Kiket's IP addresses are allowed if you have conditional access policies