What is OAuth 2 sync?
OAuth 2 is a modern, secure way of syncing LibCal with Outlook. Unlike username/password authentication, no sensitive user credentials are ever shared for OAuth 2, which makes it highly secure. OAuth 2 integration returns control to users and IT administrators so that they may grant or revoke LibCal's access to their individual accounts or the entire system respectively.
Why use the OAuth 2 integration for Outlook calendar sync?
Using the OAuth 2 integration allows you to easily allow 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 disconnect 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 activate 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 granted).
- Note: Springshare only stores the application ID, client secret, and access token. The Offline Access grant permission uses that data only for the purpose interacting with a user's calendar, such as when a patron submits an appointment booking.
- 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 Client Secret Value (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 activated, you can then turn on syncing for Appointments and/or Spaces.
- Appointments: users will have the option to sync their LibCal appointments with their Outlook calendars.
- Spaces: Admin users will have the option to activate two-way sync between LibCal spaces and Exchange room resources.
- IMPORTANT: depending upon your organization's consent framework settings, an Office 365 administrator may first need to approve a user's app authorization before they can connect it to their Outlook calendars.
Before you can activate 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 Client Secret Value, 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 OAuth2 Outlook/Exchange Calendar Sync 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.
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 the level of access that you want to allow.
- 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.
- If you selected Accounts in this organizational directory only for the Supported Account types above, locate the Directory (tenant) ID and copy that as well -- you'll need to enter it in LibCal.
- 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 24 months, 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 in 2 years.
- If you do not want to replace this secret, select Custom and set a date far in the future.
- Click the Add button.
- Once the secret has been created, copy the Value column for the secret -- 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.
- Springshare only stores the application ID, client secret, and access token. The Offline Access grant permission uses that data only for the purpose of interacting with a user's calendar, such as when a patron submits an appointment booking.
- Under Calendars, select the Calendars.ReadWrite checkbox. (Some sites may also require the Calendars.ReadWrite.Shared permission, too.)
- Click the Add permissions button. Once finished, remember to provide the Application ID and Client Secret Value to the LibCal admin so they can enter it into LibCal to activate 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 activate syncing for their LibCal system.
- Log into LibCal and go to Admin > Integrations.
- In the OAuth2 Outlook/Exchange Calendar Sync box, enter the Application ID obtained during the app registration process.
- In the Client Secret: Value field, enter the Client Secret Value (not the Secret ID) obtained during the app registration process.
- In the Supported Account Type dropdown, select the corresponding supported account type that was used when setting up and registering in Microsoft Azure.
- If you selected Accounts in this organizational directory only for the Supported Account types above, enter the Tenant ID.
- Set the Activate Calendar Sync with Azure AD OAuth 2 option to Active to allow users to set up syncing with their calendars. You can return to this page at any time to inactivate 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 more restrictive than what is selected in the Support Account Type. You may need to work with the person who registered the app in Azure to adjust permissions accordingly.
Once OAuth 2 sync has been activated 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 activated 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 activate 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 activates 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.
Remove OAuth sync
Admin users can disconnect the Azure OAuth 2 integration for all users and spaces, while individual users (who have Appointments activated) can turn off sync for their personal appointments. Not only will this stop the syncing of all appointments and spaces, but it will also prevent users from setting up the integration with their Outlook accounts. However, please note that it will not remove events from users' Outlook calendars. Previously synced bookings and appointments will remain on users' calendars unless they manually delete the events.