How can we help you?

Outlook 365: Authentication and Permissions

How does the regular Outlook365 integration work?

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

Steps to Authenticate:

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

During the redirect, Outlook365 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 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 makes a request to Outlook365 (e.g. to schedule a time on the user’s calendar), Greenhouse will authenticate requests using the access token granted by Outlook365.

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

What permissions does the regular Outlook365 integration require?

Greenhouse will be granted the following permissions using the OAuth access tokens provided by Outlook365 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.

 

Outlook365 “Find Times” Feature: Authentication and Permissions 

How does the Outlook365 “Find Times” feature work?

An Outlook365 administrator can authenticate the “Find Times” feature using a two-legged or client-credentials OAuth flow. In this case, a single Outlook365 administrator will configure Outlook365 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 Outlook365 administrator will click the Authorize button on the Configure > Email Settings page in Greenhouse, which will redirect them to an administrator consent page in Outlook365. The administrator will be prompted to enter their credentials, after which they’ll 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 Outlook365 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 Outlook365 user. Finally, the admin will be redirected back to Greenhouse. 

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

What permissions does the Outlook365 “Find Times” feature require?

Greenhouse needs read access to all calendars in your org, 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.

 

Resources

OAuth 2.0 client credentials flow:
https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols- oauth-client-creds

Refreshing Access Tokens:
https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-protocols- oauth-code#refreshing-the-access-tokens

User Entity Details:
https://msdn.microsoft.com/Library/Azure/Ad/Graph/api/entity-and-complex-type- reference#user-entity

TenantDetail Entity Details:
https://msdn.microsoft.com/Library/Azure/Ad/Graph/api/entity-and-complex-type- reference#tenantdetail-entity

General Outlook365 Integration Information:
https://support.greenhouse.io/hc/en-us/articles/205982485-I-use-Outlook-365-How-do-I-enable- the-Integration-with-Greenhouse-How-does-scheduling-work-

Outlook365 Find Times Feature:
https://support.greenhouse.io/hc/en-us/articles/115004806866-Scheduling-with-Greenhouse- Outlook365

Outlook365 Requested OAuth Scopes:
https://msdn.microsoft.com/en- us/library/azure/ad/graph/howto/azure-ad-graph-api-permission-scopes

Outlook365_Free-Busy_Security_Documentation.pdf (60 KB)