FAQ content

Integrations: What is OAuth and how does it work with LibCal & Microsoft Outlook / Teams?

In this article

OAuth integration at a glance

  • OAuth 2 is a modern, secure way of syncing LibCal & 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 LibCal & LibStaffer's access to their individual accounts or the entire system respectively
  • Springshare's integration of LibCal & LibStaffer with Outlook via OAuth 2 follows current day best practices prescribed by Microsoft
  • No service account is used for the integration. Each user must consent before LibCal or LibStaffer obtains access to their Outlook data.
  • Springshare only stores the application ID, application 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.

Granting & limiting LibCal or LibStaffer's access to Outlook

The steps below provide a general overview of how to enable the OAuth 2 integration with Outlook and LibCal or LibStaffer. For detailed instructions, please check out the following articles:

Step 1. The Outlook administrator makes their Azure Active Directory (AD) aware of LibCal's existence.

This is a one-time process. By default, LibCal and LibStaffer are not known to Azure AD and each therefore needs to be registered for use with Outlook. When this step is performed by the Outlook administrator, there is no access granted to any user accounts yet; it simply "introduces" LibCal or LibStaffer to Outlook so that syncing for individual accounts may be enabled in subsequent steps.

Successful registration of LibCal or LibStaffer generates an application ID and secret that need to provided when enabling syncing within LibCal or LibStaffer, respectively (Pro tip: store the secret in a secure location, like a password manager. Each one you create can only be viewed once.). An Outlook administrator may also choose to limit within Azure AD which set of users within their organization may sync their accounts with LibCal or LibStaffer, as well as what permissions are granted as part of this integration. This gives administrators granular control over users' activities, as well as the ability to limit what LibCal or LibStaffer is & is not allowed to do within their organization.

What happens when this step is performed?

LibCal or LibStaffer gets registered with Outlook and an application ID and secret pair is generated that is unique to the instance of the LibCal application.

Step 2. The LibCal/LibStaffer administrator enables Outlook integration using the application ID and secret obtained from the previous step.

This is to provide LibCal or LibStaffer the necessary details to connect with Outlook. Note again that no access has been granted to any one particular user's data nor no service account is involved in any of this.

What happens when this step is performed?

LibCal or LibStaffer now has the necessary information to securely connect to the organization's Outlook instance and to allow individual users to consent to syncing their data between LibCal and Outlook.

Step 3. An individual user attempts to enable integration between LibCal/LibStaffer and Outlook.

This prompts the user to login to their Microsoft account and consent to the sharing of information between the two systems. Note that the user's credentials are not sent to or shared with LibCal or LibStaffer, but with Microsoft instead. If once the user consents, a temporary token is issued to LibCal or LibStaffer to perform actions on the user's account data, with the permissions enforced in Step 1 above. This is a revolving token that periodically expires and can be revoked at any time.

What happens when this step is performed?

The user provides explicit consent to sync their data between Outlook and LibCal or LibStaffer. LibCal or LibStaffer finally has all the necessary information to access an individual user's account data to perform actions as limited by the permissions in Step 1.

Revoking access to Outlook

By using OAuth 2, organizations and their users retain full control over who has access to their accounts and the data within. They can choose to revoke their consent at will and immediately disable access to any and all third party applications.

An Outlook administrator, or LibCal or LibStaffer administrator may disable the OAuth 2 integrations for all accounts very easily. This is typically only done if syncing with Outlook is no longer desired for all users in the organization. Performing this step disables integrations immediately and the steps for granting access (including that of individual users consenting) must be performed to re-enable the integration between Outlook and LibCal or LibStaffer.

If, however, only a particular user no longer wishes to sync their data between the two systems, integration may be disabled by revoking access solely for that particular account. They will need to consent again to enable the integration for their account.

Learn more