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?
The Greenhouse Outlook365 integration is built using Microsoft's Graph API. Greenhouse users that choose to use the integration will go through an OAuth2 grant flow to provide Greenhouse 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 they click “Connect,” users will be redirected to Microsoft’s login flow and prompted to enter their Outlook365 credentials. Once they’ve entered their credentials, Outlook365 will redirect the user back to Greenhouse Recruiting.
During the redirect, Outlook365 will provide Greenhouse with an access token and a refresh token that we’ll use to access the Graph API on behalf of the user.
Does Greenhouse support customers who use a GCC High environment for Outlook365?
Yes, Greenhouse’s Outlook365 scheduling integration supports customers operating on Microsoft Office 365 GCC High environments.
Customers will need to contact their Account team to enable this environment on their Greenhouse tenant.
The GCC High environment has two main differences from the normal Outlook integration environment:
- Microsoft does not currently support finding rooms when scheduling in a GCC High environment.
- The GCC High integration utilizes the .us top-level domain. However, this change has no impact on the end-user experience
How long are the Outlook 365 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 the organization’s max token age settings within Outlook365.
Once the access token expires, Greenhouse 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 later requests Outlook365 (e.g. to schedule a time on the user’s calendar), Greenhouse 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 integrations from the Integrations page in Greenhouse by clicking “Disconnect”. This will trigger us to delete their tokens from our systems. It should be noted that Microsoft’s Graph API does not support the ability for us to revoke the tokens. Token revocation would need to be initiated by the Outlook user/organization.
Which permissions does the Outlook 365 integration request?
Greenhouse Recruiting requests access to the following Graph API OAuth2 scopes:
| Microsoft Scope | Endpoints | Why it's required |
|---|---|---|
Calendars.ReadWrite and Calendars.ReadWrite.Shared
|
POST /me/calendars/{id}/events |
We use this endpoint to create the calendar invitation after completing the scheduling flow |
| GET /me/events/{id} |
We use this endpoint to get the latest information about the calendar information when you click "Update" in Greenhouse |
|
| GET /me/calendars |
We use this endpoint to get the list of calendars a user has access to. This allows interview schedulers to select which calendar the invitations will be assigned into |
|
| PATCH /me/events/{id} |
We use this endpoint to update calendar events after you click "Update" for an interview request |
|
| DELETE /me/events/{id} |
We use this endpoint to delete calendar events if you delete the interview event in the Greenhouse application |
|
| POST /me/calendar/getSchedule |
We use this endpoint to get the availability details for interviewers when scheduling in Greenhouse. *This endpoint does not include event details. |
|
User.ReadBasic.All |
GET /me/findRooms |
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. * This endpoint is currently not supported in Greenhouse Outlook 365 GCC High implementation |
offline_access |
- | A special Azure AD scope which allows Greenhouse to request a refresh token to read and update user data, even when they are not currently using the app |
What calendar data can Greenhouse Recruiting access?
Greenhouse Recruiting receives permission to view 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 availability data (free/busy) for the interviewer is presented to the recruiter when it is requested and is not stored in Greenhouse Recruiting.
Greenhouse only utilizes the free/busy information for all attendees for scheduling interviews and does not retain or request the full calendar details for events that it does not create or maintain control over. Any calendar data is presented to the user as requested and not stored on our systems.
I’m receiving the error message "Need admin approval." What does this mean?
Some organizations with more restrictive security policies might receive the following prompt that requires that an admin approve before a user can complete their integration.
This message is caused when your organization deactivates the ability for users to consent access to company data on their behalf.
For these scenarios, an Outlook365 admin user needs to set up the integration on their Greenhouse account. While the admin user is prompted with the OAuth2 grant screen, ensure ‘Consent on behalf of your organization’ is checked.
From that point, other users will be allowed to set up their Outlook365 integrations in Greenhouse.
How does Greenhouse keep my data safe?
Greenhouse 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.
Greenhouse encrypts all OAuth2 access and refresh tokens using AES-256 before storing them within our database. Access to the encryption keys and database is only accessible to a very small set of Greenhouse staff members. All access is protected using multi-factor authentication and only accessible behind a VPN installed on a Greenhouse trusted endpoint. All production access is logged, auditable, and monitored.
Staff members must complete a successful background check before being granted access to customer data. Additionally, all staff members with customer data access must agree to 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.
Customer support employees are not allowed to access a customer’s account unless access has been explicitly granted by the user or an organization administrator. You can read more about the temporary account access process here.
Is Greenhouse FedRAMP certified?
Greenhouse is not pursuing FedRAMP certification at this time.
How does the Microsoft Teams integration work?
Greenhouse provides the ability to create a Microsoft Teams video conference meeting with the calendar interview event. Utilizing this integration does not require any additional access grants beyond what Greenhouse already requests for its Outlook365 integration. The video link added to the calendar invite uses the same Graph API endpoints used by Greenhouse to create the event. You can read more about the Teams integration in Microsoft's documentation.