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.
Set up OAuth 2 sync for a space
With OAuth 2 calendar sync enabled in your LibCal Integrations settings, you will have the option to enable two-way sync between LibCal spaces and Exchange room resource calendars.
Before you begin, please note the following about room resource calendars in Office 365:
- In order to select a room mailbox's calendar for syncing with LibCal, an Office 365 administrator must either:
- Delegate access to you with full permission (i.e. allow you to open the room's mailbox), or
- Share with you its calendar with edit permission.
- Once shared, you will then need to import the room's calendar to your own Outlook calendar using the Import Calendar > From Directory option.
- Microsoft provides more info about calendar sharing in their Office 365 Support site. However, please consult with your Office 365 for help setting up calendar sharing.
To connect a space to one of your Exchange room resources, a LibCal admin will need to follow the steps below.
- Log into LibCal and go to Admin > Spaces & Equipment.
- Under the Locations tab, navigate to the location containing the space you want to configure and click on its link in the Spaces column.
- Under the location's Spaces tab, locate the space you want to configure and click on its edit () icon in the Actions column.
- On the Edit Space page, click on the Outlook/Exchange tab.
- In the Outlook/Exchange Settings box and click the Authorize with Microsoft Account button.
- Don't see this option? A yellow alert message will indicate if OAuth 2 Authorization is not currently set up or enabled for your system. Please contact your LibCal admin for assistance, or use the legacy Password Authentication method.
- Note: if you were previously using the password authentication method, these settings will remain in place until you have enabled the OAuth 2 syncing method.
- You will be taken to the sign-in page for your Microsoft account. Enter your Outlook username and password to log in.
- When prompted, click Yes to grant permissions for the LibCal app to read your profile and write events to your calendar.
- These permissions are required in order for LibCal to create, edit, and delete events for your scheduled shifts.
- IMPORTANT: depending upon your organization's consent framework settings, an Office 365 administrator may need to approve your authorization before you can connect it to your Outlook calendar. If this is the case, Microsoft will display a message letting you know to contact your administrator. You will not be able to continue the setup process until the app authorization is approved.
- You'll be taken back to your LibCal Outlook/Exchange settings. In the Sync Resource field:
- If access to the room resource was delegated to you with full permission, enter the email address of the room resource (i.e. firstname.lastname@example.org).
- If the room resource calendar was shared with you, you can leave this set to the default, which is the email address you authenticated with.
- From the Sync Calendar dropdown, select the calendar to which you want to sync.
- Click the Save button.
- You can return to this page at any time to disable syncing. Simply click the Remove Authorization button and shifts will no longer be synced to your calendar.
- Once the authorization has been saved, you will have the option to export the space's future bookings to Exchange. To do this, click on the Run the Export button in the Outlook/Exchange Bulk Export box.
- Note: this option only appears if there are future LibCal bookings in that space. You will not see the Outlook/Exchange Bulk Export box if there are no future bookings in that space.
Manage a location's Outlook/Exchange settings
While the sync between Outlook/Exchange and LibCal is managed for each individual space, there are also location-level settings that allow you to control the details of the bookings that are pushed to Outlook/Exchange and pulled from Outlook/Exchange into LibCal.
To manage a location's Outlook/Exchange settings:
- Go to Admin > Spaces & Equipment.
- Under the Locations tab, click on the location's edit () icon in the Action column.
- Click on the Outlook/Exchange tab in the location's settings.
Outlook/Exchange Bookings created from LibCal
When syncing with Exchange, you can choose whether to display the patron's name or the public nickname in your Outlook calendar events.
- In the Outlook/Exchange Bookings created from LibCal panel, use the Outlook/Exchange Event Title option to choose what to display in your synced events.
- Use patron name: this will display the first and last name of the patron who submitted the booking.
- Use patron name and email: this will display the first & name, as well as the email address, of the patron who submitted the booking.
- Use public nickname: if the category has public nicknames enabled and one was provided with the booking, then that display instead of the patron's name. If public nicknames are not enabled or one was not provided with the booking, then the synced events will not display a title in your Outlook calendar.
Outlook/Exchange Bookings in LibCal
When syncing with Exchange, you can choose to control the information for bookings from Outlook/Exchange that will appear in LibCal. This will allow you to display the name and email address of the Outlook account that created the booking in Outlook/Exchange directly in LibCal.
After this is enabled, only new bookings synced from Exchange will populate the event creator's name and email address. Existing Outlook/Exchange bookings will not be updated. You will need to disconnect and re-connect the sync at the space-level if you want this information to appear for currently synced Exchange bookings.
- In the Outlook/Exchange Bookings in LibCal panel, use the Populate Name/Email from Outlook/Exchange option to choose whether or not to display the name and email address of the event creator for synced events.
How do I know if a booking synced?
When viewing a booking's details, look for the Outlook/Exchange Sync ID for each date/time in the booking.
Disabling OAuth sync
Admin users can also disable the OAuth 2 integration just for individual spaces. Please note that this will not remove events from the user or resource's Outlook calendar. Previously-synced bookings will remain on their calendars unless the events are manually deleted.