Outlook 365 is part of Microsoft Office 365 Suite, a cloud-based subscription service that allows your organization to create, communicate, and collaborate using Microsoft tools. Greenhouse Recruiting users who wish to schedule to and from their calendars (or any shared calendars where they have appropriate permissions) must enable the integration on their personal Greenhouse Recruiting account.
In this article, we will provide a technical overview of the Outlook 365 integration, as well as answers to security-related questions.
How does the Outlook365 integration work?
The integration is built using Microsoft's Graph API. Greenhouse Recruiting users who choose to use the integration will go through an OAuth2 grant flow to provide Greenhouse Recruiting access to read and write to that user’s calendars.
Each user will connect the integration by clicking the Connect button under Outlook365 on the Integrations page in Greenhouse Recruiting. After clicking Connect, the user will be redirected to Microsoft’s login flow and prompted to enter their Outlook365 credentials. Once they have entered their credentials, Outlook365 will prompt the user to give consent to share information with the Greenhouse application, then redirect the user back to Greenhouse Recruiting.
During the redirect, Outlook365 will provide Greenhouse Recruiting with an access token and a refresh token that Greenhouse Recruiting will use to access the Graph API on behalf of the user.
How long are the Outlook365 Graph API tokens valid?
The access token will expire after one hour, and the refresh token will expire after an undefined amount of time. The expiration depends on your organization’s max token age settings within Outlook365.
Once the access token expires, Greenhouse Recruiting will use the refresh token to retrieve another access token from Outlook365. This allows us to connect to the user’s Outlook365 instance without storing the user’s Outlook365 username and password. When Greenhouse Recruiting later makes a request to Outlook365 (e.g. to schedule a time on the user’s calendar), Greenhouse Recruiting will authenticate requests using the access token granted by Outlook365.
Based on your risk tolerance you can define the maximum refresh token length. It should be noted that once a refresh token expires, the user will be forced to re-connect their integration. This could lead to a bad user experience.
The user can disconnect the Outlook365 integration from the Integrations page in Greenhouse Recruiting by clicking Disconnect. This will trigger Greenhouse Recruiting to delete their tokens from our systems. It should be noted Microsoft’s Graph API does not support the ability for Greenhouse Recruiting to revoke the tokens. Token revocation must initiated by the Outlook user/organization.
What permissions does the Outlook365 integration request?
Greenhouse Recruiting requests access to the following Graph API OAuth2 scopes:
Allows Greenhouse Recruiting to read profile properties of other organization users in your organization on behalf of the signed-in user. This includes:
- Display Name
- Full Name
- Email Address
This scope is required for Greenhouse Recruiting to implement the Find Times scheduling feature, as Greenhouse Recruiting must query for a user based on their email address, and for Greenhouse Recruiting to determine which users are actually rooms. Greenhouse Recruiting is only able to view the full profile of the signed-in user. The full profile does not include the user’s Outlook365 credentials.
Allows Greenhouse Recruiting to create, read, update, and delete events in the signed-in user’s calendars. This scope is required to support the scheduling of the interviews directly into the user’s Outlook365 calendar.
Allows Greenhouse Recruiting to receive long-lived refresh tokens to invoke the Graph API on behalf of the user without requiring them to re-initialize the integration due to the expiring tokens.
What calendar data does Greenhouse Recruiting have access to?
Greenhouse Recruiting is able to see full calendar details for the signed-in user. Permissions to other calendars is inherited from the signed-in user. Therefore, if the user is only authorized to view free/busy for another user’s calendar, then Greenhouse Recruiting will receive only that data.
Greenhouse Recruiting only requests calendar data for users who are added as interviewers. The calendar data is presented to the user as requested and not stored on the Greenhouse systems.
I am receiving an error message that states Need admin approval.
Some organizations with more restrictive security policies might receive the following prompt that requires an admin to grant approval before a user can complete their integration.
This is due to your organization deactivating the ability for users to consent access to company data on their behalf.
In this scenario, an Outlook365 admin user will first need to set up the integration on their Greenhouse Recruiting account. When the admin user is prompted with the OAuth2 grant screen, you will need to ensure the box for Consent on behalf of your organization is checked.
Moving forward, other users will be allowed to set up their own Outlook365 integrations in Greenhouse Recruiting.
How does Greenhouse keep your data safe?
Greenhouse does not store the calendar data it requests through the Graph API. All calendar data is requested as the user is interacting with the Greenhouse Recruiting scheduling feature. Greenhouse Recruiting only stores the details for the interview events it creates.
Greenhouse encrypts all OAuth2 access and refresh tokens using AES-256 prior to storing them within our database. Access to the encryption keys and database is accessible only to a very small set of Greenhouse staff members. All access is protected using multi-factor and only accessible behind a VPN. All access is recorded and auditable.
All of these staff members must complete a successful background check before being granted access to any customer data. Additionally, all staff members with customer data access must sign our written zero-tolerance policy that defines their responsibilities with such access and the consequences (including but not limited to termination of employment) of abusing their access.