Outlook Calendar Sync Administrator Setup | Axero Documentation

Introduction

This guide shows site administrators how to connect Axero to Microsoft Outlook for two-way calendar sync. After setup, users can connect their Outlook account from My Calendar to sync events between the two.

The setup takes approximately 30 minutes. It needs a system administrator with the right permissions in both Axero and Microsoft Entra ID (Microsoft's identity and access service).

Table of Contents

• Introduction
• Prerequisites
• Step 1: Configure the Entra App
• Step 2: Configure Axero
• Step 3: Grant Admin Consent for External Tenants
• Verify Your Setup
• Troubleshooting
• Maintenance
• Microsoft documentation
• Support and Feedback

Prerequisites

Before you start, make sure you have:

• Cloud Application Administrator, Application Administrator, or Global Administrator role in Microsoft Entra ID
• Site Administrator access to your Axero platform
• Your Axero site URL (e.g., https://your-site.com)
• Access to your organization's Microsoft 365 tenant (its own Microsoft environment)
• Multi-tenant only: A Global Administrator, Cloud Application Administrator, or Application Administrator in each external tenant must grant admin consent for the app (see Step 3: Grant Admin Consent for External Tenants). Each user must also have Outlook on the web, Exchange Web Services, and Authenticated SMTP enabled. Those settings are in the Microsoft 365 Admin Center under Users > Active Users > [User] > Mail > Manage email apps.

Step 1: Configure the Entra App

1.1 Create the App Registration

1. Sign in to the Microsoft Entra admin center using an account with Cloud Application Administrator, Application Administrator, or Global Administrator permissions.
2. Go to Entra ID > App registrations.
3. Select New registration.
4. Enter a name for the application. This name appears on the consent page when users connect their Outlook calendar.
5. Under Supported account types, select the option that matches your organization:
   • Single tenant only: Most common for intranets where all users are in one Entra ID tenant.
   • Multiple Entra ID tenants: For organizations whose users are spread across more than one tenant.
6. Under Redirect URI, select Web as the platform and enter your Axero site URL followed by /oauth2/outlook/callback
   
   Example: https://your-site.com/oauth2/outlook/callback

   Important: The Redirect URI must use HTTPS and match your Axero URL exactly, including path and casing. Do not include a trailing slash or space.

7. Select Register.
8. On the app's Overview page, copy and securely store the Application (client) ID and Directory (tenant) ID for later use.

1.2 Configure Authentication Credentials

1. In the left navigation, select Certificates & secrets.
2. Under Client secrets, select New client secret.
3. Enter a meaningful Description (e.g., "Axero Outlook Integration").
4. Under Expires, select an expiration period. Microsoft recommends less than 12 months. The longest allowed is 24 months, which means fewer renewals.
5. Select Add.
6. Copy the client secret Value (not the Secret ID) right away. It's shown only once and can't be retrieved later.

1.3 Configure API Permissions

1. In the left navigation, select API permissions.
2. Select Add a permission.
3. Select Microsoft Graph.
4. Select Delegated permissions and add the following:
   • Calendars.ReadWrite: Read, create, update, and delete events in the signed-in user's Outlook calendar
   • Contacts.Read: Read the signed-in user's contacts. Axero asks for this permission by default. Either grant it here or remove contacts.read from OutlookApiAuthorizationScopes in Step 2, so that the app registration and the property match.
   • offline_access: Keep access when users aren't signed in, so the automatic background sync can run
   • openid: Authenticate users and return an ID token through Microsoft's identity platform
   • User.Read: Read the signed-in user's profile to verify identity for secure account linking. Entra adds this permission to every new app registration, so it is usually already listed.
   • email and profile: Read the signed-in user's email address and basic profile. Axero requests both by default, so grant them here too.
5. Select Add permissions.
6. Select Grant admin consent for [Your Organization] (where [Your Organization] is your Microsoft 365 tenant name) to approve these permissions for all users in advance. Users then aren't asked to grant consent themselves.
7. In the confirmation dialog, select Yes. Check that every permission shows a green checkmark in the Status column, which confirms consent was granted.

Step 2: Configure Axero

1. In Axero, go to Control Panel > System > General Settings.
2. Expand the Advanced Settings section.
3. Next to Enable calendar sync from 3rd party systems, select Yes.
4. Select Save System Settings.
5. Go to Control Panel > System > System Properties.
6. Update the following system properties (search for each, select Edit, paste the value, and select Save):

   Property	Value
   OutlookApiClientID	Application (client) ID from the app's Overview page. Do not use the Secret ID from Certificates & secrets.
   OutlookApiClientSecret	Secret value copied earlier
   OutlookApiAuthorizationScopes	calendars.readwrite contacts.read openid offline_access profile email This is the value Axero ships with. Leave it as is unless you have a reason to change it. Make sure every scope listed here is also granted on the app registration in Step 1.
   OutlookApiBaseUrl	https://graph.microsoft.com/v1.0 Current installations already have this value. Check it anyway before you finish. Older sites started with https://outlook.office.com/api/v2.0, and the upgrade replaces that address only where nobody had edited it. The Microsoft Graph permissions granted in Step 1 work only with the Graph address. A site that still has the older value won't sync until you update this property.

7. Update the following system properties based on the account type you chose when you created the app registration:

   Account Type	SAMLTenantID	UseSAMLTenantIDForOutlook
   Single tenant only	Directory (tenant) ID copied earlier	true (the shipped value)
   Multiple Entra ID tenants	Leave it as it is. Outlook ignores it when UseSAMLTenantIDForOutlook is false, and single sign-on may still use it.	false

   Note: SAML single sign-on (SSO) configuration also uses the SAMLTenantID property name. When UseSAMLTenantIDForOutlook is enabled, the same property is the Outlook tenant identifier too.

   Important: If you change the account type after users have already connected, they'll need to disconnect and reconnect their Outlook calendar.

8. Go to Control Panel > System > Advanced System Utilities and select Restart Site.
9. Connect the site's sending mailbox as Default Outlook Email. Go to Control Panel > System > General Settings > Email Settings and find Additional email settings. Use Connect next to Default Outlook Email to sign in with the mailbox the site should send calendar invitations from. Do this immediately after the steps above, in this order. The Connect flow runs a Microsoft sign-in built from the OutlookApiClientID and OutlookApiClientSecret you just saved, so it can't run before them. Saving those two also switches the integration on. From that moment until this mailbox is connected, anyone who hasn't synced a personal calendar can't create an event. They see "Default Outlook account has not been setup" (see Troubleshooting).

Step 3: Grant Admin Consent for External Tenants

If you selected Multiple Entra ID tenants in Step 1, an administrator in each external tenant must grant admin consent before their users can connect. That can be a Global Administrator, Cloud Application Administrator, or Application Administrator.

1. Build the admin consent URL by replacing your_client_id with your Application (client) ID:
   
   https://login.microsoftonline.com/organizations/adminconsent?client_id=your_client_id
2. Send this URL to that administrator in each external tenant.
3. The administrator opens the URL, signs in, and selects Accept to grant the required permissions.
4. After consent is granted, check that the app appears in the external tenant's Enterprise apps list in the Entra admin center.

Verify Your Setup

When the configuration is done, check that the integration works:

1. Go to My Calendar in Axero.
2. Confirm a person icon appears above the calendar. If it does not, see the Troubleshooting section.
3. Select the person icon, select Connect beside Outlook.com, and complete the Microsoft sign-in.
4. Create a test event in Axero and confirm it appears in your Outlook calendar.
5. Create a test event in Outlook and confirm it syncs to your Axero calendar.

If the connection fails or events do not sync, see the Troubleshooting section below.

Troubleshooting

"Default Outlook account has not been setup"

This error means the site has no Default Outlook Email connected. Once the integration is switched on, Axero won't create an event for anyone who hasn't synced a personal calendar until that site-level mailbox is set. That's why the error appears for every user at once. To fix it for the whole site, connect the mailbox as Default Outlook Email. The setting is at Control Panel > System > General Settings > Email Settings, under Additional email settings. The last step of Step 2 above walks through it. A user can also clear the error for themselves alone by connecting their own Outlook account from My Calendar (Outlook Calendar Sync User Setup). That's a workaround, not the fix.

Users see an AADSTS error when connecting their Outlook account

An AADSTS error is a Microsoft sign-in error code, and it usually points to a permissions or configuration issue. Go to Entra ID > App registrations in the Entra admin center and check that admin consent was granted for every permission from step 1.3:

• Calendars.ReadWrite
• Contacts.Read (unless you removed contacts.read from OutlookApiAuthorizationScopes)
• email and profile
• offline_access
• openid
• User.Read

"Application with identifier [id] was not found in the directory" (AADSTS700016)

The OutlookApiClientID system property has the wrong value. Check that it matches the Application (client) ID from the app's Overview page in Entra, not the Secret ID from Certificates & secrets.

"Error connecting your account" or 403 Forbidden errors in the exception log (multi-tenant)

The permissions may be slow to reach the other tenant, or blocked on the way. Ask the external tenant's administrator to go to Enterprise apps in their Entra admin center and delete the app entry. They then re-grant consent with the steps in Step 3: Grant Admin Consent for External Tenants. Also check that the user has Outlook on the web, Exchange Web Services, and Authenticated SMTP enabled. Those settings are in the Microsoft 365 Admin Center under Users > Active Users > [User] > Mail > Manage email apps.

Multi-tenant consent request routes to the wrong tenant

If a user's consent request goes to a different tenant than expected, the user may be signed in to multiple Microsoft accounts. Have them sign out of all Microsoft accounts in their browser, sign in with only the account they mean to use, and try connecting again.

Users cannot see the person icon above My Calendar

Check that Enable calendar sync from 3rd party systems is set to Yes in Control Panel > System > General Settings > Advanced Settings. If the setting changed recently, go to System > Advanced System Utilities and select Restart Site.

Sync stops working after a period of time

The client secret may have expired. Generate a new secret in the Entra admin center and update the OutlookApiClientSecret system property in Axero. See Rotating Client Secrets for steps that renew it without interrupting sync.

Maintenance

Rotating Client Secrets

A client secret expires at the end of the period chosen when it was created. To rotate a secret (replace it with a new one) without interrupting the service:

1. In the Entra admin center, go to Entra ID > App registrations and open your Axero Outlook integration app.
2. Under Certificates & secrets, select New client secret to create a replacement secret before the current one expires.
3. Copy the new secret value immediately.
4. In Axero, go to Control Panel > System > System Properties, find OutlookApiClientSecret, and update it with the new value.
5. Go to Control Panel > System > Advanced System Utilities and select Restart Site.
6. Test a calendar sync to confirm the connection works, then delete the old secret from Entra.

Users who are already connected don't need to reconnect their Outlook calendar after a secret rotation.

Security Best Practices

• Set a calendar reminder to rotate client secrets at least two weeks before expiration
• Monitor API permission usage through Microsoft Entra audit logs
• If your organization uses Conditional Access policies, make sure they don't block the OAuth callback flow to your Axero domain (the step where Microsoft sends a signed-in user back to Axero)

Known Limitations

• Personal default calendar is always synced: When connecting to Outlook, the user's personal default calendar is automatically included alongside any other selected calendars. Users cannot deselect the default calendar during connection.
• Two event notifications cannot be switched off: the in-app notices for "an event you are attending is updated" and "an event time is changed" ignore every user preference and every site-level setting. Event invitations, RSVPs, comments, and reminders do follow each person's notification preferences. Deactivating the two matching email templates stops the emails, but the in-app notices still appear. When you plan a rollout, expect every attendee of a synced event to see these two notices.
• Meetings reach people who haven't connected: when someone connects Outlook, each meeting on their calendar also appears on the Axero calendar of its organizer and of every invitee who has an Axero account. Those people don't have to connect, and they can't opt out. No setting limits the sync to people who have connected. Tell your staff before the first person connects.

Removing the Integration

To fully remove the Outlook calendar sync integration:

1. In Axero: Go to Control Panel > System > General Settings > Advanced Settings and set Enable calendar sync from 3rd party systems to No.
2. In Axero: Go to Control Panel > System > System Properties and clear the values for OutlookApiClientID and OutlookApiClientSecret.
3. In Entra: Go to Entra ID > App registrations, open the Axero Outlook integration app, and select Delete. This revokes all permissions and invalidates the client secret.

Microsoft documentation

• Microsoft Graph Permissions Reference: Full list of available Graph API permissions
• Overview of Enterprise Application Ownership (who can manage the app registration once it exists)

Support and Feedback

If you encounter an issue not covered here, or if a step could be clearer, let us know through a Support Case.

Related pages

• Outlook Calendar Sync (how the sync behaves once connected)
• Outlook Calendar Sync User Setup (what each person does after this setup)
• Connect Email to Calendar (the default Outlook account this setup makes available)
• System Properties (where the Outlook properties live)
• Advanced System Utilities (where the Restart Site step in Step 2 lives)