Purpose

This article details the process of integrating Microsoft Office 365 or Microsoft Exchange Online with Eightfold to utilize its scheduling features.

Permission types in Microsoft Graph

Microsoft Graph supports two access scenarios as listed below.

Delegated/scopes access

App can impersonate as a user, and perform only those actions that the user is allowed to perform from the outlook client, with some restrictions based on the APIs provided/admin consent.

For example, app can create a meeting on the user’s behalf, but cannot share/delegate their calendar via an API.

App Access

App can read all/some mailboxes depending on the configuration. For example, an application with the Files.Read.All application permission will be able to read any file in the organization.

Eightfold uses Delegated Access as it requests the user to connect the calendar for performing any actions.

OAuth 2.0 authorization framework

OAuth 2.0 facilitates secure access to Outlook services, allowing Eightfold to perform actions on behalf of a user. It uses tokens instead of user credentials, limiting access to specified scopes.

• Scope: Limits the access of Eightfold to user accounts, defined during the user's consent process.
• Permissions: Managed by Outlook administrators to restrict access to approved resources only.

Permissions/Scope requested by Eightfold Scheduling

Auth type: OAuth2.0

Scheduling uses OAuth2.0 to get the user’s permissions to perform certain activities on behalf of the user, for the purpose of creating/updating/fetching invites and creating Microsoft Teams meetings.

To know more about the Microsoft permissions, read Microsoft Graph permissions reference.

If Email Aliasing is enabled:

• An email alias is an alternative email address that forwards email messages to your primary email account. An email alias is a nickname or an alternate name for your email address that can be used instead of your primary email address. For example, if your primary email address is john.doe@gmail.com, you can create an email alias such as john.doe+work@gmail.com or john.doe+newsletters@gmail.com. Any email sent to these aliases will be automatically forwarded to your primary email account.
• Eightfold needs information about your primary email address to map if the interviewer invites were created successfully.
• For more information, read Email aliases in Scheduling.

If rooms are enabled:

• Rooms need to be enabled in Admin Console if schedulers also want to book meeting rooms when scheduling in-person meetings.
• For more information, read Scheduling workflows.

Data shared with the requested scope

Validity of OAuth/Refresh tokens

During authentication, the following two kinds of tokens are generated:

• Access Token: Validity is a random value between 60-90 minutes. To know more, read Access tokens in the Microsoft identity platform.
• Refresh Token: Validity is 90 days.

Secure storage of OAuth tokens

The secure encryption and storage of OAuth tokens are handled using AWS Key Management Service (KMS), restricting access to Eightfold's production servers and ensuring tokens are decrypted only when required.

• Encryption: Before storage, tokens are encrypted with AWS KMS.
• Decryption: Encrypted tokens are decrypted with AWS KMS when needed, ensuring secure access.

Security and privacy of calendar data

• Query for Availability: Eightfold uses the getSchedule API to check for time slot availability (free or busy), via the authenticated user’s account. Other than availability status, no additional details on non-Eightfold created events are accessed by Eightfold.
• Create/Update Eightfold events only:
  • Eightfold can create events only from the associated user’s authorized calendar account (For example - a user account, or team-shared).
  • Eightfold can update only those events that are created within the Eightfold platform.
• User Information:
  • Eightfold uses the permission User.Read to get the Outlook email address of the associated user only.
  • Eightfold uses the permission User.ReadAll to get the interviewer’s primary email address. No additional information is accessed or stored by Eightfold.

Revoking permissions in Outlook

Administrators can revoke Eightfold's access to Outlook services at any time, ensuring control over the organization's data. To revoke permissions, follow these steps:

1. Login to Azure Portal.
2. Navigate to Enterprise Applications and select Eightfold.
3. Access Permissions under Security.
4. Choose the three-dot menu next to the permission and click Revoke permission.
5. Confirm revocation by clicking Yes, Revoke in the confirmation popup.

Audits

• The calendar vendor’s audit logs capture all requests and edits made by Eightfold, on behalf of users.
• In addition, Eightfold can provide a full audit of all API calls made to your calendar system from Eightfold.
• Eightfold Audit Log attributes include: User account, request made, URL, success/failure, response message (JSON), IP Address.

Outlook technical workflow

Outlook APIs

Technical flow diagrams

1. User authentication using OAuth 2.0 to grant access to Eightfold

2. Meeting creation by Scheduler using different scheduling methods

3. Candidate slot selection if recruiter used “Let Candidate Choose workflow” in the above step

Connect with Eightfold

Prerequisites

Microsoft Outlook 365 calendar is configured as the calendar in scheduling config for Outlook integration. It can be configured in the Calendar Provider dropdown available within the Calendar tab (Admin Console > Talent Acquisition > Scheduling).

Note: If the recruiter’s Microsoft Outlook 365 calendar isn't connected to Eightfold, the system raises a CalendarNotConnectedException as it can't find an active calendar connection for the user managing the schedule. This results in candidates being unable to book interview slots, with an error message displayed as: “Your request could not be completed. Please try contacting the recruiter.”

Configuration options

Eightfold is an unpublished Microsoft application. There are two configurations to set up the connection with Eightfold.

• With admin consent: set up an admin consent flow and provide the admin’s consent to Eightfold (Recommended).
• Direct consent by users: allow users to connect to unpublished applications directly.

For a Microsoft Azure admin, each of the configurations listed below describe the following steps:

1. Set up a consent flow to connect with third party Enterprise Applications
2. Grant consent to permissions requested by Eightfold Enterprise Application

Configuration Option 1: With admin consent

This setup involves the Azure admin as an intermediary for users to connect their calendar. Users can only connect to Eightfold once Eightfold is consented to by the admins.

There are two variants to this approach:

• Variant 1: Admin approval by user request (Recommended)
• Variant 2: Admin approval by Azure admin login

Variant 1: Admin Approval By User Request (Recommended)

In this configuration, a user who is not an Azure Admin and who tries to connect their calendar to Eightfold is asked to request admin approval. Once they send their request, admins can review the permissions and grant permission to this user and other Eightfold users on behalf of the organization.

Setting up a consent flow

Consent and permissions tab within the Azure Active Directory includes settings to consent flow for the organization. To access the User Settings screen, sign in to the Azure portal as an Admin. Go to Azure Active Directory > Enterprise applications. In Enterprise applications, navigate to Consent and permissions under Security.

Follow this step for Consent and permissions > User consent settings:

• Configure whether users are allowed to consent for applications to access your organization's data is set to Do not allow user consent.

Follow these steps for Consent and permissions > Admin consent settings:

1. The setting Users can request admin consent to apps they are unable to consent to is set to Yes

2. The setting Who can review admin consent requests is used to add admins who can review any requests from users trying to grant consent to an app

Once the Azure Admin grants consent, any subsequent user who tries to connect their calendar will be able to directly connect instead of requesting Admin approval.

Grant consent to permissions requested by Eightfold Enterprise Application

Steps to be performed by a recruiter:

1. Log into the Eightfold Sandbox environment as a user who has Eightfold Scheduling Permissions. If you do not see the screen below when you login, please contact Eightfold Support.

2. Navigate to Accounts > My Calendar (https://app.eightfold.ai/account#tab-calendar).

3. Click Connect Microsoft Outlook 365 Calendar.

4. You will be redirected to the Microsoft login page in a new tab for authenticating the Eightfold Scheduling App.

5. After entering the credentials, you are required to request approval for the shared list of permissions (if not globally given to all 3rd party apps).

6. After a successful request, the following message is displayed.

Steps to be performed by Azure admin

1. Once the user requests for approval, the Azure admin can find the request within the Azure Active Directory, review the permissions requested and provide their consent.

   1. From the navigation menu, click Enterprise applications.
   2. Under Activity, select Admin consent requests.
   3. Select Eightfold.
   4. Review details about the request and who the requestors are.
   5. Click Review permissions and consent.

2. Admins will see a page that requests for their consent. Granting admin consent will mean all users in the organization can now grant their calendar access to Eightfold for the specific permissions highlighted above.

Steps to be performed by recruiter after admin approval

1. After admin approval, the recruiter will need to repeat steps 1, 2 and 3.

2. Navigate to Accounts > Calendar (https://app.eightfold.ai/account#tab-calendar).

   1. Click Connect Microsoft Outlook 365 Calendar.
   2. You will be redirected to Microsoft Login Page in a new tab for authenticating the Eightfold Scheduling App.
   3. After credentials are entered, you are required to accept the shared list of permissions.

3. After this, the authentication is completed, and the tab is closed. Once this is done, you are redirected to the Eightfold Calendar tab with the option to select the calendar type.

4. There is only one option for calendar type for outlook, click *Okay *to proceed. This completes the integration process.

Variant 2: Admin Approval By Azure Admin Login

In this configuration setting, users who try to connect their calendars to Eightfold get a message - Need Admin Approval. The only method to integrate with Eightfold in this configuration is for the admin to connect their calendar in Eightfold.

Setting up a consent flow

Consent and permissions tab within the Azure Active Directory includes the settings to the consent flow for the organization. To access the User Settings screen, sign in to the Azure portal as an Admin. Then select Azure Active Directory and then Enterprise applications. In Enterprise applications navigate to Security and select Consent and permissions.

Follow this step for Consent and permissions > User consent settings:

• The setting User consent for applications: Configure whether users are allowed to consent for applications to access your organization's data is set to Do not allow user consent.

Follow these steps for Consent and permissions > Admin consent settings in this configuration:

1. The setting Users can request admin consent to apps they are unable to consent to is set to No

Grant consent to permissions requested by Eightfold Enterprise Application

Steps to be performed by Azure admin

In this configuration, in order to grant consent to Eightfold, *Azure Admins *need to first connect their own calendar. Follow the steps below:

1. If you are an Eightfold user who is also an Azure Admin, log into the Eightfold Sandbox environment. Ensure that you have Eightfold Scheduling Permissions as well in order for the rest of the steps below to work. If you do not see the screen below when you login, please contact Eightfold Support.

2. Go to Accounts > Calendar and click Connect Microsoft Outlook 365 Calendar.

3. Enter your Outlook credentials and consent to the permissions requested by Eightfold. Click on the Consent on behalf of your organization checkbox.

Once you click Accept, Eightfold requested scheduling scopes start appearing within the Eightfold Enterprise Application in the Azure Active Directory.

To review the scopes, sign in to the Azure portal as a Global Administrator, an Application Administrator, or a Cloud Application Administrator. Then select Azure Active Directory and then Enterprise applications. In Enterprise applications search and select Eightfold.

Then navigate to Permissions under Security. The permissions start appearing under Admin Consent.

After the admin has connected their calendar, any user with the right permissions will be able to connect their calendar.

Steps to be performed by recruiter after admin has connected calendar

1. After admin approval, the recruiter needs to follow these steps:

   1. Go to Accounts > Calendar and click Connect Microsoft Outlook 365 Calendar.
   2. You are redirected to Microsoft Login Page in a new tab for authenticating the Eightfold Scheduling App.
   3. After entering the credentials, you are required to accept the shared list of permissions. Click Accept to proceed.

2. After this, the authentication is completed and the tab is closed. Once this is done, you are redirected to the Calendar page with the option to select the calendar type.

3. There is only one option for calendar type for Outlook, click Okay to proceed. And this completes the integration process.

Configuration Option 2: Direct Consent by Users

Eightfold recommends that customers can engage their internal IT/InfoSec admins if they would like to proceed with this option.

Learn more

• Overview of Microsoft Graph permissions
• Access tokens in the Microsoft identity platform
• APIs:
  • Get access on behalf of a user - Microsoft Graph
  • Get a user - Microsoft Graph v1.0
  • Get event - Microsoft Graph v1.0
  • Create event - Microsoft Graph v1.0
  • event: cancel - Microsoft Graph v1.0
  • calendar: getSchedule - Microsoft Graph v1.0
  • Create onlineMeeting - Microsoft Graph v1.0
  • List places - Microsoft Graph v1.0