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.
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 configure 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.
Microsoft’s Graph API does not allow Greenhouse Recruiting to revoke the tokens. Token revocation must be initiated by the Outlook user/organization.
Which permissions does the Outlook365 integration request?
Greenhouse Recruiting requests access to the following Graph API OAuth2 scopes:
1. User.ReadBasic.All
Allows Greenhouse Recruiting to read profile properties of other organization 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 Greenhouse Recruiting 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 does not include the user’s Outlook365 credentials.
2. Calendars.ReadWrite
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.
3. offline_access
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 can Greenhouse Recruiting access?
Greenhouse Recruiting is able to 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/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 when it is requested and not stored on the Greenhouse systems.
I am receiving a "Needs admin approval" error message. What now?
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 error is caused when your organization turns off the setting to allow users to consent access to company data on their behalf.
To address this error, an Outlook365 admin user will need to set up the integration on their Greenhouse Recruiting account and select Consent on behalf of your organization on the OAuth2 grant screen.
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 interacts with the Greenhouse Recruiting scheduling feature. In other words, Greenhouse Recruiting only stores the details for the interview events it creates.
Greenhouse encrypts all OAuth2 access and refresh tokens using AES-256 before storing them in 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.