How can we help you?

Authentication and Permissions (Outlook 365)


Basic Outlook 365 Integration

Users can authenticate the Basic Outlook 365 integration through a standard “three-legged” OAuth flow. With this type of OAuth flow, each individual user will connect their own Outlook 365 calendars to Greenhouse and will be able to schedule events to their own calendars or to calendars that they have access to edit within Outlook 365.

Steps to Authenticate:

Each user will connect the integration by clicking the Connect button under Outlook 365 on the Integrations page in Greenhouse. After they click Connect, they will be redirected to Outlook and prompted to enter their Outlook 365 credentials. Once they have entered their credentials, Outlook 365 will redirect the user back to Greenhouse. 

During the redirect, Outlook 365 will provide Greenhouse with an access token and a refresh token that we will use to authenticate the integration for the user. The access token will expire after one hour, and the refresh token will expire after an undefined amount of time, depending on the organization’s settings within Outlook 365. Once the access token expires, Greenhouse 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 later makes a request to Outlook 365 (e.g. to schedule a time on the user’s calendar), Greenhouse will authenticate requests using the access token granted by Outlook 365.

The user can revoke permissions to the integration at any time on the Integrations page in Greenhouse by clicking Disconnect.

Required Permissions for Basic Outlook 365 Integration 

Greenhouse will be granted the following permissions using the OAuth access tokens provided by Outlook 365 during the authentication flow above:

1. Sign you in and read your profile

This is the default permission of Outlook third party apps that allows Greenhouse to read the full profile of the signed-in user. The full profile includes all of the declared properties of the User entity. This permission allows Greenhouse to read the following basic company information of the signed-in user through the TenantDetail entity:

• Tenant ID
• Tenant display name
• Verified domains

Greenhouse will not be able to read navigation properties, such as manager or direct reports. Additionally, Greenhouse will not be able to read the user's Outlook365 password.

2. Read and write to your calendars

This allows Greenhouse to create, read, update, and delete events in user calendars. This is a more powerful permission that allows users to schedule events onto their Outlook365 calendar from within Greenhouse.


Advanced Outlook365 Integration

An Outlook 365 administrator can authenticate the advanced integration using a two-legged or client-credentials OAuth flow. In this case, a single Outlook 365 administrator will configure Outlook 365 to grant Greenhouse access to a certain class of data for all users in the organization. This will allow Greenhouse to show the user time-blocks that other users are busy or available.

Steps to Authenticate:

An Outlook 365 administrator will click the Authorize button on the Configure > Email Settings page in Greenhouse, which will redirect them to an administrator consent page in Outlook 365. The administrator will be prompted to enter their credentials, after which they will be shown the list of permissions that Greenhouse requests, which they can either accept or deny.

When the administrator accepts the permissions request, a setting will be enabled in Outlook 365 that will allow Greenhouse to request OAuth access tokens in the future which will provide access to the specified data. This allows Greenhouse to request access tokens moving forward without the additional involvement of any Outlook 365 user. Finally, the admin will be redirected back to Greenhouse.

The Outlook 365 administrator can revoke access to the integration at any time from within the Outlook 365 administrator console.

Required Permissions for Advanced Outlook 365 Integration 

Greenhouse needs read access to all calendars in your organization, including users and resources. Specifically, the three permissions we request are:

1. Read calendars in all mailboxes

This allows Greenhouse to read events of all calendars without a signed-in user. This allows Greenhouse to see whether or not an e-mail address at your organization is free/busy during a certain time interval, including rooms.

2. Read all users' full profiles

This allows Greenhouse to read the full set of profile properties, reports, and managers of other users in your organization on behalf of the signed-in user. This allows Greenhouse to locate what e-mail addresses at your organization are actually rooms. This allows us to only show rooms in the “Resources” drop down in Greenhouse.

3. Sign in and read user profile

This allows users to sign-in to Greenhouse, and allows Greenhouse to read the profile of signed-in users. It also allows Greenhouse to read basic company information of signed- in users.

Will Greenhouse have access to any other Global Admin permissions?

Greenhouse will only have access to the permissions listed above and will not have any additional permissions granted to the Global Admin user. Our access will be limited by the OAuth scopes that Greenhouse will request to generate the OAuth token from Outlook365. From the Outlook365 Permissions Scopes details page:

“The actual privileges granted to the app will be the least privileged combination (the intersection) of the privileges granted by the scope and those possessed by the signed- in user. For example, if the permission scope grants delegated privileges to write all directory objects, but the signed-in user has privileges only to update their own user profile, the app will only be able to write the signed-in user's profile but no other objects.”

How does Greenhouse keep your data safe?

Only a small number of Greenhouse staff members have the ability to view customer account data. 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.



OAuth 2.0 client credentials flow: oauth-client-creds

Refreshing Access Tokens: oauth-code#refreshing-the-access-tokens

User Entity Details: reference#user-entity

TenantDetail Entity Details: reference#tenantdetail-entity

General Outlook365 Integration Information:

Outlook365 Requested OAuth Scopes: us/library/azure/ad/graph/howto/azure-ad-graph-api-permission-scopes

Outlook365_Free-Busy_Security_Documentation.pdf (60 KB)