Outlook 365 is part of Office 365, a cloud-based subscription service that allows your organization to create, communicate, and collaborate using Microsoft tools. Greenhouse Recruiting's integration with Outlook 365 lets your organization schedule, update, and delete interviews from calendars where people have the appropriate permissions.

You may have questions about this integration's security settings, so we've collected answers to some frequently asked questions.

How does the Outlook 365 integration work?

This integration is built using Microsoft's Graph API. People 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 person configures the integration by connecting the integration in Greenhouse Recruiting. The user is redirected to Microsoft and prompted to enter their Outlook 365 credentials.

Once they have entered their credentials, Outlook 365 will prompt them to give consent to share information with Greenhouse Recruiting, then redirect the person back to Greenhouse Recruiting.

During the redirect, Outlook 365 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 Outlook 365 Graph API tokens valid?

The Graph API access token will expire after one hour. The refresh token expiration depends on your organization's max token age settings within Outlook 365. Based on your organization's 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.

Once the access token expires, Greenhouse Recruiting will use the refresh token to retrieve another access token from Outlook 365. This allows us to connect to the user's Outlook 365 instance without storing the user's Outlook 365 username and password. When Greenhouse Recruiting later requests Outlook 365, for instance, to schedule a time on the user's calendar, we'll authenticate the requests using the access token granted by Outlook 365.

Microsoft's Graph API doesn't allow Greenhouse Recruiting to revoke the tokens. Token revocation must be initiated by the Outlook user or organization. Anyone can disconnect the Outlook 365 integration in Greenhouse Recruiting. This will trigger Greenhouse Recruiting to delete these access tokens from our system.

Which permissions does the Outlook 365 integration require?

Greenhouse Recruiting requests access to the following Graph API OAuth2 scopes:

Permission What to know
User.ReadBasic.All

This permission allows Greenhouse Recruiting to read profile properties of other users in your organization on behalf of the signed-in user. This permission includes the following data:

  • Display name
  • Full name
  • Email address
  • Photo

This permission is required to use the Find Times scheduling feature in Greenhouse Recruiting, as we must search for a user based on their email address and then differentiate those email addresses from room addresses in your Outlook 365 configuration. Greenhouse Recruiting is only able to view the full profile of the signed-in user. The full profile doesn't include the user's Outlook 365 credentials.

Calendars.ReadWrite This permission allows Greenhouse Recruiting to create, read, update, and delete events on the signed-in user's calendars. This scope is required to support the scheduling of interviews directly onto the user's Outlook 365 calendar.
offline_access This permission allows Greenhouse Recruiting to receive refresh tokens to invoke the Graph API on behalf of the user without requiring them to re-initialize the integration due to expiring tokens.

What calendar data can Greenhouse Recruiting access?

Greenhouse Recruiting can see full calendar details for the signed-in user. Permissions to other calendars are based on the permissions of the signed-in user. For example, if the user is only authorized to view free or busy for another user's calendar, then Greenhouse Recruiting will only receive that data. Greenhouse Recruiting requests calendar data for users who are added as interviewers. The calendar data is presented to the user when it is requested and is not stored in Greenhouse Recruiting.

How does Greenhouse Recruiting keep my data safe?

Greenhouse Recruiting doesn't store the calendar data it requests through Graph API. All calendar data is requested as the user interacts with the Greenhouse Recruiting scheduling feature. Greenhouse Recruiting only stores the details for interview events it creates.

Additionally, Greenhouse Recruiting encrypts all OAuth2 access and refresh tokens using AES-256 before storing them in our database. Access to encryption keys to this database is accessible only to a very small subset of Greenhouse Recruiting staff. Access is protected using multi-factor authentication and is only accessible through a VPN. Access is recorded and auditable. This subset of staff must complete a successful background check before being granted access to any customer data. Additionally, all staff members with customer data access must sign a zero-tolerance policy that defines their responsibilities with such access and the consequences of abusing access.