How to enable Azure OAuth 2 integration for Outlook calendar sync in LibCal
Why enable OAuth 2 integration for Outlook calendar sync?
Enabling OAuth 2 integration allows you to easily enable syncing between LibCal and your Outlook/Exchange calendars. This includes:
- Syncing your LibCal Appointments with your personal Outlook calendar. You can optionally sync your free/busy times in Outlook with LibCal, too, so you won't be listed as available when you have meetings on your calendar.
- Two-way syncing between your Space bookings and Exchange room resources. That way, when a space is booked in LibCal, the corresponding room in Exchange will also be listed as unavailable (and vice versa).
Unlike using password authentication, OAuth 2 integration doesn't require you to enter any Exchange user account information directly into LibCal. Instead, an admin will need to register a LibCal sync app with your organization, at which point you will simply need to log into Outlook and give the LibCal app authorization to write events to your Outlook calendar (for appointments) and/or room resource calendars (for space bookings). Once authorized, you can choose to stop syncing at any time by simply revoking the authorization in each space's sync settings. (Admins also have the option to disable the app integration system-wide, if desired.)
- Step 1. An Admin user will need to register the LibCal app with Microsoft for your organization. You may want to ask the appropriate IT staff member do this, though it may not be required for your organization.
- Registering an app is what allows you to enable syncing for your LibCal system.
- The LibCal app requires only the Calendar.ReadWrite and User.Read permissions to be granted (offline access will need to be enabled). No other account permissions are needed by LibCal.
- The person registering the app can user either their organizational Exchange/Office 365 account, or a personal Outlook/Microsoft account.
- Step 2. Once the app has been registered, a LibCal admin will need to enter the Application ID and Application Secret (provided during the registration process) in your LibCal integration settings.
- Please note: it may take a few minutes after the app is registered before LibCal will be able to communicate with it.
- Step 3. After the integration has been set up and enabled, you can then enable syncing for Appointments and/or Spaces.
Before you can enable Outlook calendar sync via OAuth 2 for your LibCal system, you must first register the LibCal app for your organization. Although you may prefer to ask a member of your IT staff to do this step, it is not required. Once the app has been registered, you will receive a unique Application ID and Application Secret, which LibCal needs in order for OAuth 2 sync to work. This step only needs to be done once.
The first part of this step is to obtain your system's Redirect URL. A LibCal admin will need to do this part.
- Log into LibCal and go to Admin > Integrations.
- In the Azure AD OAuth 2 box, you'll find the Redirect URL for your system.
- If you will be completing the app registration yourself, leave this page open in a separate browser tab. You'll need to copy and paste this URL during the registration process.
- Otherwise, provide this URL to the person completing the app registration.
B. Registering the app
The person who will be registering the app for your organization will complete the following steps. (This only needs set up once.)
- Sign into the Microsoft Azure App Registrations service with your Microsoft account.
- Alternatively, sign into https://portal.azure.com and search for "App Registrations".
- Please note: our directions are for the Preview Experience of the App Registrations service, which will replace the current App Registrations interface starting May 2019. If you see a banner saying "Click this banner to launch the preview experience", please do so before continuing.
- Click on the New Registration button.
- On the Register an application page, give your new application a name to help you identify it (i.e. LibCal Shift Sync).
- For the Supported account types, select Accounts in any organizational directory and personal Microsoft accounts.
- For the Redirect URI setting, leave the dropdown set to Web and enter the Redirect URL provided in your LibCal Azure AD OAuth2 settings.
- Click the Register button.
- Once your app has been registered, you'll be taken to its Overview page. Locate the Application (client) ID and copy it -- you'll need to enter this in your LibCal Integrations settings.
- Under the Manage menu, click on Certificates & secrets.
- Under Client secrets, click on the New client secret button.
- In the Add a Client Secret window, enter a description for this secret (it'll help you identify where this is being used).
- Under Expires, select whether you want this secret to automatically expire or not.
- If you select In 1 year, for example, you will have to generate a new secret and add it to your LibCal Integrations settings in order for syncing to continue working.
- If you do not want to replace this secret, select Never.
- Click the Add button.
- Once the secret has been created, copy it -- you'll need to enter this in your LibCal Integrations settings along with the Application ID.
- Under the Manage menu, click on API Permissions.
- Click on the Add a permission button.
- In the Request API Permissions list, click on Microsoft Graph.
- Click on Delegated Permissions.
- Select the offline_access checkbox.
- Under Calendars, select the Calendars.ReadWrite checkbox.
- Click the Add permissions button. Once finished, remember to provide the Application ID and Client Secret to the LibCal admin so they can enter it into LibCal to enable the app (see Step 2 below).
Once the Application ID and Application Password have been obtained during the app registration process, the LibCal Admin will use these to enable syncing for their LibCal system.
- Log into LibCal and go to Admin > Integrations.
- In the Azure AD OAuth 2 box, enter the Application ID obtained during the app registration process.
- In the Application Secret field, enter the Application Password obtained during the app registration process.
- Set the Enable Calendar Sync with Azure AD OAuth 2 option to Enabled to allow users to set up syncing with their calendars.
- You can return to this page at any time to disable syncing system-wide.
- Click the Save Settings button.
- Please note: it may take a few minutes after registering the app with Microsoft's Azure Portal before LibCal will be able to communicate with it.
- If you receive an App ID or Secret is incorrect error message, and you just registered the app with Microsoft, please wait several minutes and try again.
- This error can also indicate that your app's permissions are not set correctly. Please work with the person who registered your app to ensure its Supported account types option is set to Accounts in any organizational directory and personal Microsoft accounts.
Once OAuth 2 sync has been enabled for your LibCal system, you will now be able to set up syncing for appointments and/or space bookings using this method.
- Appointments: all users (who have appointments enabled for their accounts) will have the option to sync their LibCal appointments with their Outlook calendars. They can also sync their Outlook free/busy times to Libcal to prevent appointments during other meetings and events.
- Spaces: Admin users will have the option to enable two-way sync between LibCal spaces and Exchange room resources. This works by connecting each individual LibCal space to a corresponding room resource in your Exchange system. Once connected, the space's availability will be in sync regardless of whether it was booked via LibCal or via an Outlook calendar event.
If you were previously using the password authentication method for Outlook/Exchange sync, those settings will remain active in LibCal until you connect using the OAuth 2 method. For example, if a user was syncing their appointments to Outlook/Exchange using password authentication and an Admin enables OAuth 2 sync for LibCal, that user's password authentication settings will remain active until they connect to OAuth 2 in their Appointments settings. The same is true for spaces currently connected to your Exchange resources using password authentication, as well.