Nojoin Calendar Guide

Nojoin supports Google Calendar and Microsoft Outlook calendar integration for dashboard month and agenda views.

This guide covers both sides of the feature:

• Admin and owner setup of the installation OAuth credentials.
• End-user connection of their own calendar accounts.
• Dashboard behaviour, colours, links, and troubleshooting.

Overview

Calendar integration has two distinct layers:

1. The installation must be configured with Google and/or Microsoft OAuth credentials.
2. Individual users then connect their own accounts and choose which calendars to sync.

Users do not enter OAuth client IDs, client secrets, or tenant IDs themselves.

Before You Begin

• Use a stable HTTPS browser origin whenever possible.
• Set WEB_APP_URL to the exact public browser origin used to access Nojoin.
• Set a stable DATA_ENCRYPTION_KEY before storing provider secrets or connecting user calendars.
• If you deploy behind a reverse proxy, make sure the browser origin and provider callback origin are identical.

For the full hosting context, see DEPLOYMENT.md.

Admin Configuration Options

You can provide the installation OAuth credentials in either of these ways:

1. Preferred: sign in as an Owner or Admin and save them in Settings > Administration > Calendar providers.
2. Alternative: set the matching environment variables and restart the stack.

Supported environment variables:

• WEB_APP_URL
• DATA_ENCRYPTION_KEY
• GOOGLE_OAUTH_CLIENT_ID
• GOOGLE_OAUTH_CLIENT_SECRET
• MICROSOFT_OAUTH_CLIENT_ID
• MICROSOFT_OAUTH_CLIENT_SECRET
• MICROSOFT_OAUTH_TENANT_ID

DATA_ENCRYPTION_KEY is not an OAuth credential, but it is what keeps stored calendar provider secrets and user calendar tokens readable across upgrades and infrastructure changes. Earlier v0.8.1 deployments could rely only on the generated key file, which was an operational oversight for installations where the app data directory and database might be managed separately.

End-User Connection Flow

Once the installation credentials exist:

1. Open Settings > Personal and go to Calendar Connections.
2. Choose Connect Gmail Calendar or Connect Outlook Calendar.
3. Complete the provider sign-in and consent flow.
4. Return to Nojoin and choose which calendars to sync.
5. Optionally apply per-calendar colour overrides.

Connected calendars then feed the dashboard month view, agenda view, and next-event surface. Unlinked Nojoin recordings also appear on the dashboard calendar as first-class historical items.

Dashboard Behaviour

When calendar sync is configured:

• The dashboard month view shows dots on days with synced events and on days that contain unlinked Nojoin recordings.
• Unlinked Nojoin recordings use the Nojoin orange accent so they remain visually distinct from Google or Microsoft calendar sources.
• The agenda view is month-scoped and shows both calendar events and unlinked historical recordings for the viewed month.
• Selecting a day in month view opens a day agenda, and selecting today shows a live now marker against timed events.
• The Today action jumps back to the current month and date context.
• Per-calendar colours can be used so different sources remain visually distinct.
• Event times render in the user’s configured Nojoin timezone.
• Meeting links and supported online meeting URLs can be surfaced directly from agenda items.

When no calendar is connected and there are no unlinked recordings in view, the dashboard deliberately shows an honest empty state rather than mock data.

Synced calendar events also store their description and attendee list, and recordings carry a nullable calendar_event_id so a recording can be linked to the calendar event it belongs to (see Meeting Intelligence in USAGE.md). When a recording is linked, the dashboard suppresses the standalone Nojoin meeting item and shows only the calendar event.

Google OAuth Setup

1. Open Google Cloud Console and create or select the project you want to use.
2. Enable the Google Calendar API.
3. Configure the OAuth consent screen.
4. Add the scopes used by Nojoin:
   • openid
   • email
   • profile
   • https://www.googleapis.com/auth/calendar.readonly
5. If the app remains in testing mode, add every Google account that needs access as a test user.
6. Create an OAuth client ID of type Web application.

7. Add this redirect URI exactly:

   <public-origin>/api/v1/calendar/oauth/google/callback
   

8. Save the client.
9. Enter the generated client ID and client secret into Nojoin Admin Calendar settings or the matching environment variables.

Microsoft OAuth Setup

Microsoft setup is slightly more sensitive because tenant choice affects which accounts can sign in.

Supported Account Type

• In the current Entra registration UI, use Any Entra ID Tenant + Personal Microsoft Accounts if you want both Microsoft 365 work or school accounts and personal Outlook.com or Hotmail accounts.
• Older Microsoft documentation may describe this same choice using different wording, but in the current interface the label to look for is Any Entra ID Tenant + Personal Microsoft Accounts.
• Use Accounts in this organisational directory only only if you deliberately want a single-tenant work or school deployment.

Registration Steps

1. Open Microsoft Entra admin centre.
2. Go to Identity > Applications > App registrations.
3. Create a new registration.
4. Choose the supported account type that matches your intended users. For mixed Microsoft 365 and personal Microsoft account support, select Any Entra ID Tenant + Personal Microsoft Accounts.

5. Add this redirect URI as a Web platform redirect:

   <public-origin>/api/v1/calendar/oauth/microsoft/callback
   

6. Copy the Application (client) ID.
7. If the app is single-tenant, also copy the Directory (tenant) ID.
8. Open API permissions and add delegated permissions for:
   • openid
   • profile
   • email
   • offline_access
   • User.Read
   • Calendars.Read
9. Do not add application permissions for this user-consent flow.
10. Open Certificates & secrets and create a client secret.
11. Copy the secret Value immediately. Do not use the Secret ID.
12. Save the values into Nojoin Admin Calendar settings or the matching environment variables.

Tenant Selection Rules

• Use common only when the app registration supports both organisational directories and personal Microsoft accounts.
• If the app is single-tenant, use the explicit tenant ID instead of common.
• If the app is meant to support personal Microsoft accounts but Nojoin is pointed at a specific tenant GUID, sign-in may succeed while the first calendar read still fails. In that case, switch back to common, save, disconnect the failed connection, and reconnect it.

Verification Checklist

After setup:

1. Sign in as a normal user.
2. Connect Google or Microsoft from Settings > Personal > Calendar Connections.
3. Approve the provider consent flow.
4. Select one or more calendars.
5. Confirm the dashboard shows calendar markers, agenda items, and next-event data.

Troubleshooting

Redirect Origin Is Wrong

• Confirm WEB_APP_URL matches the exact browser origin users open.
• Confirm the provider registration uses the same callback origin.

AADSTS50194 with Microsoft

Your Microsoft app is still single-tenant while Nojoin is using common.

Fix one of these:

• Change the app registration to Any Entra ID Tenant + Personal Microsoft Accounts.
• Or set Nojoin to the explicit tenant ID instead of common.

Microsoft Sign-In Works but Calendar Sync Still Fails

If you intend to support personal Microsoft accounts or mixed account types, confirm Nojoin is using common, then disconnect and reconnect the Outlook calendar connection.

invalid_client During Token Exchange

Make sure Nojoin stores the client secret Value, not the Secret ID.

Admin Approval Message in Microsoft

The delegated permissions exist, but the tenant blocks user consent. A tenant administrator must grant consent.

Google Testing Mode Blocks a User

If the Google app is still in testing mode, that Google account must be listed as a test user until the consent screen is published.

Related Docs

• DEPLOYMENT.md
• USAGE.md
• ADMIN.md