FAQ content

Email Settings: Use Exchange OAuth for LibCal's email sending method

In this article

LibCal supports using OAuth for Microsoft Exchange as an SMTP option for email sending.

To get started, you will need to work with your institution's IT administrator to set up the integration between Exchange 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 to do this, though it may not be required for your organization.
    • Registering an app is what allows you to send emails using your institution's SMTP server.
    • The LibCal app requires the Mail.Send and Mail.Send.Shared the permissions to be granted (offline access will need to be granted as well). No other account permissions are needed by LibCal.
    • The person registering the app must use the account you plan to use for email sending or an account that has sharing privileges for the account that you will use for email sending.
  • Step 2. Once the app has been registered, a LibCal admin will need to enter the Application ID, Client Secret: Value (provided during the registration process), and email address (that will be used for sending) in your LibCal system's Email Sending Method settings.
    • Please note: it may take a few minutes after the app is registered before LibCal will be able to communicate with it.

Step 1. Register the app for your institution

Before you can activate the Exchange OAuth 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 Client Secret Value, which LibCal needs in order for Exchange OAuth sending 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 LibCal admin will need to do this part.

  1. Log into LibCal and go to Admin > System Settings.
  2. Click on the Email Settings tab.
  3. In the Email Sending Method panel, select the Exchange OAuth radio button.
  4. After selecting the Exchange OAuth option, you'll see the Redirect URL.
    • 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.
Redirect URL in the Email Sending Method panel

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. You must sign in with the account you plan to use for email sending or an account that has sharing privileges for the account that you will use for email sending.
    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. LibCal Email Sending).
  2. For the Supported account types, select the level of access that you want to allow.
  3. ​For the Redirect URI setting, Set the "Select a platform" dropdown to Web and enter the Redirect URL provided in your system's Email Sending Method 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 LibCal system's Email Sending Method 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 LibCal.
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 LibCal system's 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 LibCal system's Email Sending Method 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.
  2. Under Mail, select the Mail.Send and Mail.Send.Shared checkboxes.
  3. Click the Add permissions button. Once finished, remember you will need to provide the Application ID and Client Secret: Value (and the Directory (tenant) ID for single-tenant apps) to the LibCal admin so they can enter it into LibCal to activate the app (see Step 2 below).
Selecting and adding permissions

Step 2. Activate Exchange Oauth in LibCal

Once the Application ID and Client Secret: Value have been obtained during the app registration process, the LibCal Admin will use these to activate the system to use Exchange OAuth email sending.

  1. Log into LibCal and go to Admin > System Settings.
  2. Click on the Email Settings tab.
  3. In the Email Sending Method panel, select the Exchange OAuth radio button.
  4. Enter the Application ID obtained during the app registration process.
  5. In the Client Secret: Value field, enter the Client Secret Value (not the Secret ID) obtained during the app registration process.
  6. 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.  
  7. Enter the From Email you will be sending mail from.
    • This address must be the one for the account you authenticate with or an account with which the authenticating account has sharing privileges.
  8. Click the Save button.
  9. After saving, click the Authorize with Microsoft button to complete the authentication process with Microsoft.
    • Reminder: You must authenticate using the email address/account set above or with an account that has sharing privileges with the above email address. 
application ID, application secret, and tenant ID fields
  1. After authenticating, you will see an "Authorized by Microsoft/Outlook account" message indicating that the connection was successful.
    • To confirm the connection, we recommend sending test messages from your system to a local email address and an external address.
    • If any changes have been made to the Application ID, Client Secret: Value, Tenant ID, or From Email, click the Save button to confirm the changes.
      • Making changes will also require you to run through the authentication process with Microsoft again.
viewing the authentication success message