Outlook Calendar Sync Administrator Setup | Axero Documentation

Introduction

This guide walks site administrators through connecting Axero to Microsoft Outlook for bidirectional calendar sync. After setup, users can connect their Outlook account from My Calendar to sync events between both platforms.

The setup takes approximately 30 minutes and requires a system administrator with the appropriate Microsoft Entra ID and Axero permissions.

Overview

• Introduction
• Prerequisites
• Step 1: Configure the Entra App
• Step 2: Configure Axero
• Step 3: Grant Admin Consent for External Tenants (Multi-Tenant Only)
• Verify Your Setup
• Troubleshooting
• Maintenance
• Additional Resources
• Support and Feedback

Prerequisites

Before you start, ensure 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
• Multi-tenant only: A Global Administrator in each external tenant must grant admin consent for the app (see Step 3). Each user must also have Outlook on the web, Exchange Web Services, and Authenticated SMTP enabled 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. Navigate to Identity > Applications > App registrations.
3. Select New registration.
4. Enter a name for the application. This name will appear 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 6 months for security; 24 months reduces renewal frequency.
5. Select Add.
6. Immediately copy the client secret Value (not the Secret ID). This value is only displayed once and cannot 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
   • offline_access - Maintain access when users are not actively signed in, enabling automatic background synchronization
   • 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. This permission may already be added by default.
5. Select Add permissions.
6. Select Grant admin consent for [Your Organization] (where [Your Organization] is your Microsoft 365 tenant name) to pre-approve these permissions for all users. This prevents individual users from being prompted to grant consent themselves.
7. In the confirmation dialog, select Yes. Verify that all permissions show a green checkmark under the Status column, confirming consent was granted successfully.

Step 2: Configure Axero

1. In your Axero platform, navigate 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. Navigate to 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 offline_access openid User.Read

7. Update the following system properties based on the account type selected when creating the app registration:

   Account Type	SAMLTenantID	UseSAMLTenantIDForOutlook
   Single tenant only	Directory (tenant) ID copied earlier	Enabled/True
   Multiple tenants	Delete the current value	Disabled/False

   Note: The SAMLTenantID property name is shared with SAML SSO configuration but serves as the Outlook tenant identifier when UseSAMLTenantIDForOutlook is enabled.

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

8. Navigate to System > Advanced System Utilities and select Restart Site. The site restart is required because system property changes are cached and only reload on restart.

Step 3: Grant Admin Consent for External Tenants (Multi-Tenant Only)

If you selected Multiple tenants in Step 1, each external tenant's Global Administrator must grant admin consent before their users can connect.

1. Construct the admin consent URL by replacing your_client_id with your Application (client) ID:
   
   https://login.microsoftonline.com/common/adminconsent?client_id=your_client_id
2. Send this URL to the Global Administrator of each external tenant.
3. The Global Administrator must open the URL, sign in, and select Accept to grant the required permissions.
4. After consent is granted, verify the app appears in the external tenant's Enterprise Applications list in the Entra admin center.

Verify Your Setup

After completing the configuration, verify the integration is working correctly:

1. Navigate to My Calendar in your Axero platform.
2. Confirm the Connect to Outlook option appears. If it does not, see the Troubleshooting section.
3. Select Connect to Outlook and complete the Microsoft authentication flow.
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 set up"

This error appears when a user tries to create an event and has not connected their Outlook account. The user must connect their Outlook account from My Calendar before events can sync. See Outlook Calendar Sync User Setup for instructions.

Users see an AADSTS error when connecting their Outlook account

This usually indicates a permissions or configuration issue. Navigate to Identity > Applications > App registrations in the Entra admin center and verify that admin consent has been granted for all four required permissions:

• Calendars.ReadWrite
• offline_access
• openid
• User.Read

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

The OutlookApiClientID system property contains an incorrect value. Verify 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)

Permission propagation between tenants may be delayed or blocked. Ask the external tenant's Global Administrator to navigate to Enterprise Applications in their Entra admin center, delete the app entry, and re-grant consent using the admin consent URL. Also verify the user has Outlook on the web, Exchange Web Services, and Authenticated SMTP enabled 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 is routed to a different tenant than expected, the user may be signed into multiple Microsoft accounts. Have the user sign out of all Microsoft accounts in their browser, sign in with only their intended account, and retry the connection.

Users cannot see the "Connect to Outlook" option

Verify that Enable calendar sync from 3rd party systems is set to Yes in Control Panel > System > General Settings > Advanced Settings. If the setting was recently changed, navigate 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 zero-downtime renewal steps.

Maintenance

Rotating Client Secrets

Client secrets expire based on the duration selected during creation. To rotate a secret without service interruption:

1. In the Entra admin center, navigate to Identity > Applications > 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, navigate to Control Panel > System > System Properties, locate OutlookApiClientSecret, and update it with the new value.
5. Navigate to System > Advanced System Utilities and select Restart Site.
6. Verify the connection is working by testing a calendar sync, then delete the old secret from Entra.

Existing users will not 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
• Periodically review which users have connected Outlook accounts from Control Panel > System > System Properties
• Monitor API permission usage through Microsoft Entra audit logs
• If your organization uses Conditional Access policies, ensure they do not block the OAuth callback flow to your Axero domain

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.

Removing the Integration

To fully remove the Outlook calendar sync integration:

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

Additional Resources

• Once administrator setup is complete, each user must connect their own Outlook account: Outlook Calendar Sync User Setup
• For additional calendar integration options, see: Connect Email to Calendar
• Microsoft Graph Permissions Reference - Full list of available Graph API permissions
• Microsoft Entra App Registration Best Practices

Support and Feedback

We are always working to improve our documentation. If you encounter an issue not covered here, or if a step could be clearer, let us know through a Support Case so we can help you and improve this guide for everyone.