FAQ content

Integrations: How to enable Azure OAuth 2 integration for Outlook calendar sync in LibStaffer

In this article

What is OAuth 2 sync?

OAuth 2 is a modern, secure way of syncing LibStaffer 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 LibStaffer's access to their individual accounts or the entire system respectively.

Learn more

Why enable OAuth 2 integration for Outlook calendar sync?

Enabling OAuth 2 integration allows users to sync their assigned LibStaffer shifts with their Outlook calendars, making it easy for them to know their work schedules without having to log into LibStaffer. By default, LibStaffer requires users to enter their server address, username, password, and email address in order to facilitate Outlook calendar sync.

By contrast, OAuth 2 integration doesn't require users to enter any account information directly into LibStaffer. Instead, they will simply need to log into their Outlook accounts and give the LibStaffer app authorization to write events to their calendars. Not only is this the most secure way of enabling calendar sync with Outlook, it's by far the most convenient. Once authorized, users can choose to stop syncing at any time by simply revoking the authorization in their LibStaffer account settings. (Admins also have the option to disable the app integration for all users, if desired.)

Does my version of Outlook support Azure OAuth 2 sync? In most cases, if you're using Office 365 or a personal Outlook.com account, then you should be able to use Azure OAuth 2 sync. However, we recommend that you contact your IT staff to confirm that your organization supports registering apps via the Microsoft Azure Portal and allows users to authorize these registered apps with their Office/Outlook accounts. If Azure OAuth 2 sync is not supported, you can still set up LibStaffer syncing using password authentication.

Getting started

  • Step 1. An Admin user will need to register the LibStaffer 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 LibStaffer system.
    • The LibStaffer app requires only the Calendar.ReadWrite and User.Read permissions to be granted, along with offline access.
      • 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 LibStaffer admin will need to enter the Application ID and Client Secret Value (provided during the registration process) in your LibStaffer integration settings.
    • Please note: it may take a few minutes after the app is registered before LibStaffer will be able to communicate with it.
  • Step 3. After the integration has been set up and enabled, users will be able to individually authorize syncing within their LibStaffer account settings.

Step 1. Register the app for your institution

Before you can enable Outlook calendar sync via OAuth 2 for your LibStaffer system, you must first register the LibStaffer 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 LibStaffer needs in order for OAuth 2 sync to work. This step only needs to be done once.

A. Obtaining the Redirect URL

The first part of this step is to obtain your system's Redirect URL. A LibStaffer admin will need to do this part.

  1. Log into LibStaffer and go to Admin > Integrations.
  2. 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.
The Redirect URL in the Azure AD OAuth2 box

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.)

  1. 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.
Microsoft Azure sign in page
Searching for the App registrations service
  1. Click on the New Registration button.
The New Registration button
  1. On the Register an application page, give your new application a name to help you identify it (i.e. LibStaffer Shift Sync).
  2. For the Supported account types, select the level of access that you want to allow..
  3. For the Redirect URI setting, leave the dropdown set to Web and enter the Redirect URL provided in your LibStaffer Azure AD OAuth2 settings.
  4. Click the Register button.
The Name, Supported Account Types, and Redirect URI options
  1. 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 LibStaffer Integrations settings.
    1. 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 LibStaffer.
The Application ID on the Overview page
  1. Under the Manage menu, click on Certificates & secrets.
  2. Under Client secrets, click on the New client secret button.
The New Client Secret button
  1. In the Add a Client Secret window, enter a description for this secret (it'll help you identify where this is being used).
  2. 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 LibStaffer 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.
  3. Click the Add button.
The Add a Client Secret window
  1. Once the secret has been created, copy the Value column for the secret -- you'll need to enter this in your LibStaffer Integrations settings along with the Application ID.
Copying the client secret
  1. Under the Manage menu, click on API Permissions.
  2. Click on the Add a permission button.
The Add a Permission button
  1. In the Request API Permissions list, click on Microsoft Graph.
The Microsoft Graph button
  1. Click on Delegated Permissions.
The Delegated Permissions button
  1. 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.
  2. Under Calendars, select the Calendars.ReadWrite checkbox. (Some sites may also require the Calendars.ReadWrite.Shared permission, too.)
  3. Click the Add permissions button. Once finished, remember to provide the Application ID and Client Secret Value to the LibStaffer admin so they can enter it into LibStaffer to enable the app (see Step 2 below).
Selecting and adding permissions

Step 2. Enable Azure AD OAuth 2 sync in LibStaffer

Once the Application ID and Application Password have been obtained during the app registration process, the LibStaffer Admin will use these to enable syncing for their LibStaffer system.

  1. Log into LibStaffer and go to Admin > Integrations.
  2. In the Azure AD OAuth 2 box, enter the Application ID obtained during the app registration process.
  3. In the Client Secret: Value field, enter the Client Secret Value (not the Secret ID) obtained during the app registration process.
  4. In the Supported Account Type dropdown, select the corresponding supported account type that was used when setting up and registering in Microsoft Azure. 
    1. If you selected Accounts in this organizational directory only for the Supported Account types above, enter the Tenant ID 
  5. 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.
  6. Click the Save Settings button.
    • Please note: it may take a few minutes after registering the app with Microsoft's Azure Portal before LibStaffer 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.
Options for enabling Azure AD OAuth2 calendar sync

Step 3. Users individually authorize calendar sync in their LibStaffer account settings

With OAuth 2 calendar sync enabled in your LibStaffer Integrations settings, all users will now be able to start syncing their LibStaffer shifts with their Outlook calendars.

  1. Click on your email address in the orange nav bar to access your personal account settings.
  2. On the Manage Account page, click on the Outlook/Exchange tab.
  3. In the OAuth 2 Authorization box, click on 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 LibStaffer admin for assistance, or use the legacy Password Authentication method.
The Authorize with Microsoft Account button
  1. You will be taken to the sign-in page for your Microsoft account. Enter your Outlook username and password to log in.
The Microsoft sign-in screen
  1. When prompted, click Yes to grant permissions for the LibStaffer app to read your profile and write events to your calendar.
    • These permissions are required in order for LibStaffer 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.
The Microsoft prompt to grant permissions to LibStaffer
  1. You'll be taken back to your LibStaffer Outlook/Exchange settings. In the OAuth 2 Authorization box, select which calendar to which you want to sync your shifts to with the Calendar to Sync shifts with dropdown.
  2. Then select the calendar that will be used to check your available status with the Calendar to Check Free/Busy Status dropdown.
  3. Click the Save Calendars button.
    1. 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.
The Calendar dropdown in the OAuth2 Authorization box

Export your assigned shifts (optional)

Once you've successfully connected to your Outlook calendar, future assigned shifts will begin syncing to your calendar automatically. However, you'll be given the option of adding all of your currently assigned shifts, as well.

  1. In the Outlook/Exchange - Export box, choose your preferred Export Option from the dropdown.
    • Export shifts which have not been exported previously: this will only add any shifts that have not been previously exported or synced to your Outlook calendar. If there are no such shifts, then nothing will be exported.
    • Export all shifts: this will add all of your shifts to your Outlook calendar, even those that have already been synced. As a result, you may end up with duplicates on your calendar by choosing this option.
  2. Click the Run the Export button.
The shift export options in the Outlook/Exchange - Export box

Disabling OAuth integration for all users

Admin users can completely disable the Azure OAuth 2 integration for all users. Not only will this stop the syncing of all shifts, 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 shifts will remain on users' calendars unless they manually delete the events. 

Disable OAuth integration for a single user

A user can disable OAuth sync at any time. Please note that this will not remove events from the user's Outlook calendar. Previously-synced shifts will remain on a user's calendar unless the events are manually deleted.

  1. After logging into LibStaffer, click on your email address in the navigation bar.
  2. On your Manage Account page, click on the Calendar Sync tab.
  3. In the Outlook/Exchange Settings panel, click on the Remove Authorization button in the OAuth2 Authorization box.
The Remove Authorization button under the Calendar Sync tab