The Microsoft Teams integration allows you to easily schedule online appointments and events with patrons through LibCal. This integration uses OAuth to provide a secure way of interacting with your connected Microsoft Teams accounts. Learn more: What is OAuth and how does it work with LibCal?
To get started, you will need to work with your institution's IT administrator to set up the integration between Microsoft Teams and your LibCal system.
- 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 create Teams meetings via your LibCal system.
- The LibCal app requires only the OnlineMeetings.ReadWrite permission to be granted (offline access will need to be enabled). No other account permissions are needed by LibCal.
- The person registering the app can use either their organizational Exchange/Office 365 account, or a personal 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, users can authorize the integration in their LibCal account settings. This will allow them to start scheduling virtual appointments & online events using Teams.
- 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 Teams account.
Before you can enable the Microsoft Teams integration 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.
In addition to following the instructions below, your IT staff will also need to provide you with the MaxInactiveTime value for your institution's Azure Active Directory setup.
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 Microsoft Teams 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".
- 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 Online Events).
- 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 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 OnlineMeetings, select the OnlineMeetings.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 Microsoft Teams 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.
- 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.
- Use the Enable Online Meetings with Microsoft Teams toggle to turn the integration on or off. When Enabled, individual users will still need to authorize the LibCal app before using Teams.
- When this option is set to Disabled, this will turn the Teams integration off for all LibCal users.
- For the Token Max Inactive Time, enter the MaxInactiveTime value from your Azure Active Directory setup. LibCal will automatically attempt to refresh a user's token based on this value so they do not become disconnected from Teams after a period of inactivity.
- 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.
After an Admin has enabled the integration in your site, you need to authorize LibCal to create meetings with your Microsoft Teams account. This can only be done on a user-by-user basis in their personal LibCal account settings.
- Log into LibCal and click on your email address in the navigation bar. This will take you to your personal LibCal account settings page.
- Click on the Integrations tab.
- Under the Integrations tab, in the Microsoft Teams box, click the Authorize with Microsoft Account button. If you are not already signed into your Microsoft account, you'll be prompted to do so.
- Note: your Admin may have configured the integration to only allow you to use your organization's Microsoft/Office 365 account. If you get an error after trying to use an Outlook.com or personal Microsoft user account, please try again using your organization account.
- If you encounter other authentication issues, or receive a message saying that an admin must approve the authorization, please consult your organization's IT staff.
- After you've successfully authorized the LibCal integration, you'll be taken back to LibCal where an automated test will be run to ensure that the connection between LibCal and Microsoft Teams is working.
- If the test is successful, you'll see an "Authorized by Microsoft account..." message and a time stamp of when the authorization token was last refreshed.
- To disable your Microsoft Teams integration, you can return to this page at any time and click the Remove Authorization button.
- This will prevent new online meetings from being scheduled with your Microsoft Teams account.
Disabling OAuth sync
Admin users can completely disable the Microsoft Teams integration for all users, while individual users can disable sync for their LibCal accounts. Please note that, when an admin disables the integration for all users, then Teams will no longer be available for scheduling online appointments and events. This will not cancel any previously-created events or appointments, however.