Skip to main content
SmartRecruiters

Set up Office 365 calendar integration (post Q2 2022)

Requires:
  • SmartRecruit

 

Delegated Permissions - New multi-tenant app (Q2 2022 launch)

In order to set up the Microsoft Office 365 Calendar integration using the new delegated permissions app, you'll need to have:

  • an Administrator-level account in SmartRecruiters.
  • a user that is authorized to produce Azure consent on behalf of your organization.

There are two steps to integrating your company's Office 365 Calendar with SmartRecruiters using:

  1. Get an Azure Admin to provide concent for the SmartRecruiters app
  2. Add your credentials to SmartRecruiters using the Sign in with Microsoft button.

Please check that you are not setting up the integration with Internet Explorer 11 or Edge (40.15063.0.0. to 45.01.4.4900) browsers due to known issues reported by Microsoft.  It is recommended to use Chrome, Firefox, Safari or Edge (above 45 version).

When you enable a calendar integration, you give SmartRecruiters permissions to read and write ALL calendar data in your organisation. However, SmartRecruiters' integration pulls only a minimal subset of required data. Due to the technical limitations of Microsoft's calendar services, we cannot limit or configure the scope of permissions allowed by the integration.

Prerequisites

Granting tenant-wide admin consent requires you to sign in as a user that is authorized to consent on behalf of the organization.

To grant tenant-wide admin consent, you need:

  • An Azure AD user account with one of the following roles:
    • Global Administrator or Privileged Role Administrator, for granting consent for apps requesting any permission, for any API.
    • Cloud Application Administrator or Application Administrator, for granting consent for apps requesting any permission for any API, except Azure AD Graph or Microsoft Graph app roles (application permissions).
    • A custom directory role that includes the permission to grant permissions to applications, for the permissions required by the application.

Setup

  1. Navigate to Settings / Admin.
  2. Click Apps & Integration in the Administration list.
  3. Click the Microsoft Office 365 Calendar Integration tab
  4. From this screen you should see a URL on screen and an option to "Sign In With Microsoft"
  5. Using the copy button to the right hand side, send this URL to your Azure AD user who has permission to grant tenant-wide consent.
  6. Once they have confirmed that consent has been provided you can return back to this page and click the "Sign in with Microsoft" button where you will be prompted to sign in to your account.
  7. Once signed in, the integration is now setup

Permissions Overview

Permission Name: User.Read

Permission Overview: Allows users to sign-in to the app, and allows the app to read the profile of signed-in users. It also allows the app to read basic company information of signed-in users.

Permission Name: Calendars.ReadWrite

Permission Overview: Allows the app to create, read, update, and delete events in user calendars.

Permission Name: Place.Read.All

Permission Overview: Allows the app to read company places (conference rooms and room lists) set up in Exchange Online for the tenant.

Permission Consent: Admin Consent Required

 

Application Permissions (existing option)

Register Azure App

You'll need to register SmartRecruiters as an App to get two pieces of information:

  1. Application ID
  2. Client Secret Key

You may need assistance from your Azure Portal Administrator in order to register a SmartRecruiters app in Azure.

Create the app

First, you'll need to register the app itself:

  1. Log in to https://portal.azure.com under and an Administrator account.
  2. Click Azure Active Directory in the left-hand panel.
  3. Click App Registrations. 
  4. Click + New Application Registration at the top of the page.
  5. In the Create pane, enter a name for the app, e.g., SmartRecruiters Calendar Integration.
  6. For Supported account types, choose Accounts in this organizational directory only.
  7. Enter https://www.smartrecruiters.com into the Redirect URL field.
  8. Click Register. You'll see a new summary pane with 8 entries.

    o365_sr_create_app

  9. Copy the Application ID. 

Generate Secret Key

Now, you'll need to generate a security key that's specific to the app:

  1. Click the Certificates & secrets icon in the app's options pane.

    o365_sr_generate_cert

  2. In the Client secrets section click + New client secret, enter a name for the Key description of a new Key.

  3. Select any time frame between 3 months to 24 months, or define a 'Custom' duration for the expiration date.

  4. Click Add to generate the key's value.

  5. Copy the key's value. You won't be able to retrieve it later.

You are responsibile for making sure your key is live and active. We recommend setting a calendar reminder on the expiration date and renewing the key before it's expired.

Assign Permissions

Finally, you'll need to give the app permission to read your company's calendar:

  1. In the options pane, click API permissions
  2. In the API permissions section, click +Add a permission.

    o365_sr_add_permission

  3. In the Select an API pane, choose Microsoft Graph.

    o365_sr_choose_graph

  4. Back in the Request API permission pane, click Application permissions.

    o365_sr_delegate_or_app

  5. In the Select Access section, select these permissions:

    • Directory.Read.All - Read directory data

    • Calendars.ReadWrite - Read and write calendars in all mailboxes

    • Place.Read.All - Read and retrieve all rooms and resources

  6. Click Add permissions.

  7. In the Grant consent section, click Grant admin consent for company.

    o365_sr_grant_consent

  8. Click Yes

Done!

Add credentials

Once you've registered an SmartRecruiters app in Azure and copied down the Application ID, and Secret key, enter them into SmartRecruiters. 

  1. Navigate to Settings / Admin.
  2. Click Apps & Integration in the Administration list.
  3. Click the Microsoft Office 365 Calendar Integration tab.Screen Shot 2021-11-09 at 12.58.21 PM.png
  4. Select the Application Permissions option
  5. Enter the Application ID from the Azure app into the Client ID field.
  6. Enter the key into the Client Secret field.
  7. Enter your full Tenant ID, e.g., SmartRecruiters.onmicrosoft.com into the Tenant ID field.
  8. Click Save, and Load Resources to check the connection.

    If an error appears, please check that all the steps above are completed correctly.

    If no error shows up, please Contact Support to complete the integration.

  9. Once Support confirms that the integration is complete, return to this page and select Load Resources to see the list of rooms and reservable resources from your calendars.

Click on the following to see the Technical FAQ for Office 365.