Skip to main content
McAfee Enterprise MVISION Cloud

Custom oAuth Application for Office 365 and Azure API Integration

MVISION Cloud allows customers to connect to Office 365 APIs through a custom application with asymmetric authentication instead of requiring a global administrator account with a username and password for Office 365 and a non-administrator account. With this function, you can also run MVISION Cloud for Office 365 in a read-only mode.

IMPORTANT:

  • Before you begin, contact Customer Support to enable the Custom OAuth app for your tenant. 
    • For all CSPs except Azure
      • When you contact support, make sure you ask for custom OAuth support only for the service(s) you do not wish to use the Global Admin account to enable the MVISION Cloud connection. The exception is Microsoft Dynamics which must use the custom OAuth approach.

      • If the Global Administrator role is not available, you can enable a non-global administrator role (make sure you don't have the administrator role) in instances using custom oAuth for all office365 CSPs except Exchange. For exchange, if you are not using response action quarantine then you can use anon-global admin role.

      • If you have already enabled the API connection using a Global Administrator (GA) account for a service, then you do not need to enable custom OAuth support for this service. For example,  if you need to enable custom OAuth support for Microsoft Dynamics which is mandatory, you do not need to re-do the authentication for other services like SharePoint, OneDrive, and Exchange.

      • Microsoft Teams APIs in Microsoft Graph that access sensitive data are considered protected APIs i.e., https://docs.microsoft.com/en-us/gra...protected-apis. Hence, Custom OAuth app Id is being used for this API call in MVISION Cloud Teams need to be approved by Microsoft and you have to raise a request with Microsoft for approval. Once the request is approved by Microsoft then only you can use it in MVISION Cloud.

    • For Azure, Global Administrator is not a requirement for user based OAuth
  • When you contact support, they will request the Instance Id. This can be found in the MVISION Cloud console via the instance setup page. For example, expand this screenshot  --> [clipboard_ed6befbf1fddabf7eb23cdfb7ea18f98e.png]

Configure an Application Registration in the Azure Portal

To register a new application in the Azure portal, perform the following steps:

  1. Log In to the Azure portal at https://portal.azure.com/.
  2. Go to Home > App registrations and click New registration.
    2.png
  3. Configure the following details in the registration form:
    • Enter the name of the application. For example, McAfee Compliance Control.
    • Under Supported account Types, select Accounts in this organizational directory only.
    • Under Redirect URI, select Web and enter one of the following Sign-On URLs depending on the MVISION Cloud backend:

NOTE: A redirect URI step is not required for Dynamics 365 Application.

PROD:  https://www.myshn.net/shndash/extensions/offlinedlp_ret.jsp
EUPROD: https://www.myshn.eu/shndash/extensions/offlinedlp_ret.jsp 

3.png

  1. To create a new application, click Register.
  2. Confirm the new application's properties are configured correctly, as per the last step in this guide.
    clipboard_ee892b75f0303a29551f2501e0eb523b8.png
  3. Perform the following activities using OpenSSL to create a self-signed certificate. 
  • Generate a private key: Key length should be 2048.
    openssl genrsa -out office365OfflineDlpKey.pem 2048
  • Create a certificate Signing request:
    openssl req -new -key office365OfflineDlpKey.pem -out office365OfflineDlp.csr
  • Create a X.509 certificate with generated key and signing request:
    openssl x509 -req -in office365OfflineDlp.csr -signkey office365OfflineDlpKey.pem -out office365OfflineDlp-cert.pem -days 3650
  • Check the start/end date of the certificate:
    openssl x509 -startdate -noout -in office365OfflineDlp-cert.pem
    openssl x509 -enddate -noout -in office365OfflineDlp-cert.pem
  1. Go to Certificates & Secrets in the new app, click Upload certificate and upload office365OfflineDlp-cert.pem to Azure portal.
    5.png
  2. To add the required APIs with the permissions, click API Permissions.

IMPORTANT:

  • Select and add the required APIs with their respective permissions as per the following tables. All permission types should be set to Application Permissions unless otherwise stated.
  • Do not add additional permissions, and do not leave out any permissions. Stick to this list or API enablement will not work.
  • For all CSPs except Azure and Azure Information Protection (AIP), assign the permissions per the tables below
For Activity Monitoring set the following permissions
Exchange Online  OneDrive / SharePoint Teams Dynamics 365

Microsoft Graph:

Read user profile
(User.Read.All)

Office 365 Management API:

Read Activity data of your organization
(ActivityFeed.Read)

Office 365 Exchange Online:

Read and write emails in all mailboxes
(Mail.ReadWrite)

 

Microsoft Graph:

Read items in all site collections (Sites.Read.All)

Office 365 SharePoint Online:  

Read user profile
(User.Read.All)

Office 365 Management API:

Read Activity data of your organization
(ActivityFeed.Read)

(It is not possible to connect MS Teams in "Activity Monitoring only mode", please enable with DLP permission as stated below)

 

Office 365 Management APIs:

Read Activity data of your organization (ActivityFeed.Read)

 

 

For API DLP set the following permissions
Exchange Online OneDrive / SharePoint Teams (Messages) Dynamics 365

Office 365 Exchange Online:

Read and write emails in all mailboxes
(Mail.ReadWrite)

Use Exchange Web Services with full access to all mailboxes (full_access_as_app)

Microsoft Graph:  

Read users profile (User.Read.All)

Read and write mail in all mailboxes (Mail.Readwrite)

Windows Azure Active Directory:

Read directory data

Microsoft Graph: 

Read items in all site collections (Sites.Read.All)

Read directory data (Directory.Read.All)

Read and write Microsoft Intune device configuration (DeviceManagementConfiguration.ReadWrite)

Read all usage reports (Reports.Read.All)

Read your Organization's policies (Policy.Read.All)

Office 365 SharePoint online:

Have full control of all site collection (Sites.FullControl.All)

Read and write items and lists in all site collections Sites (Sites.Manage.All)

Read users profile (User.Read.All)

Office 365 Management APIs:

Read Activity data of your organization (ActivityFeed.Read)

Microsoft Graph:

ChannelMessage.Read.All

ChannelMessage.UpdatePolicyViolation.All

Chat.Read.All

Chat.UpdatePolicyViolation.All

Directory.Read.All

Group.Read.All

Group.ReadWrite.All

User. Read

User.Read.All

ChannelMember.ReadWrite.All

TeamMember.ReadWrite.All

ChatMember.ReadWrite.All

Dynamics CRM (type=delegated)

Access Common Data Service as organization users (user_impersonation)

Microsoft Graph (type=delegated):   

Sign in and read user profile (User.Read)

  • For Azure permissions, see here.
  • For AIP permissions, see here.
  1. For all CSPs except Azure: Once you have added all permissions, click Grant admin consent for Domain.
    clipboard_e5fc1acc7ba0886b252b859be49bffdcd.png

The result looks similar to the below images. Click to enlarge.

Office 365 Microsoft Dynamics

API permission.png


clipboard_eddca298cc9246874a07264f386f00c3d.png
  1. Open the Manifest file, click Manifest. You will be using the information on this page to complete the MVISION Cloud configuration.
    7.png

MVISION Cloud API Connection 

IMPORTANT:

  • If you are setting up Dynamics, pause here, and complete the configuration steps outlined in this guide: Configuring and connecting the Microsoft Dynamics API. Make a note of the appId in the manifest above. You will need this to configure Dynamics.
  • If you have not already, contact Customer Support and request to enable the Custom OAuth app for your tenant. When you contact support please ensure you ask for custom OAuth support only for the service(s) you do not wish to use the Global Admin account to enable the MVISION Cloud connection. The exception is Microsoft Dynamics which must use the custom OAuth approach.
  • If you have already enabled the API connection using a Global Administrator (GA) account for a service, then you do not need to enable custom OAuth support for this service. For example: If you need to enable custom OAuth support for Microsoft Dynamics which is mandatory, you do not need to re-do the authentication for other services like SharePoint, OneDrive and Exchange.
  • When you contact support they will request the Instance Id. This can be found in the MVISION Cloud console via the instance setup page. For example, expand this screenshot --> [clipboard_ed6befbf1fddabf7eb23cdfb7ea18f98e.png]

To enable API access in the MVISION Cloud:

  1. Go to Service Management > O365 Service and click Enable. You should be prompted to provide the custom oAuth credentials. If you are not prompted then contact Customer Support to enable custom oAuth for the applicable service.
  2. Extract the data from the Manifest file to enter the following details:
    • Client ID is the appId from the Manifest (Manifest screen is shown above). Looks like a UUID, for example, 543bd03b-cd6e-417d-b31b-871ba0ef44f1
    • Private Key is the .pem file containing the private key which you created earlier (office365OfflineDlpKey.pem).
    • Thumb Print is the customKeyIdentifier of the keyCredentials of Manifest (Manifest screen is shown above). Looks like a short, base64 encoded string, for example, 4BDBCCC84D81B29D1E6A6E0976A120275B393A7C
    • Resource URL is the URL for the instance:
      • SharePoint. For SharePoint, it is https://<O365TENANTNAME>.sharepoint.com
      • OneDrive. For OneDrive, it is https://<O365TENANTNAME>-my.sharepoint.com
      • Exchange. For Exchange, use https://<O365TENANTNAME>.sharepoint.com.
      • Dynamics. Use your Dynamics custom domain. For example: https://<yourdomain>.crm.dynamics.com.
    • Admin Resource URL is the URL for the SharePoint Admin Portal. Even when the connection is established for OneDrive, enter the SharePoint Admin Portal URL. For example, https://<O365TENANTNAME>-admin.sharepoint.com
    • Admin Email is the email address of an admin user for the services as defined. For example, admin@mycompany.onmicrosoft.com
      • OneDrive.  Provide an admin email to create a quarantine folder. Technically this can be any user (need not be an admin) and do not make it public. But, the best practice is to use an Office 365 account created for MVISION Cloud, as a service account).
      • SharePoint.  Create a quarantine library in each site and make the admin exclusive owner of that library. For this purpose, use an admin email as input, which will be the owner of the Quarantine library in each site. Technically this can be any user (need not be an admin) and do not make it public. But, the best practice is to use an Office 365 account created for MVISION Cloud, as a service account). Since only SharePoint Admin has access to all sites in SharePoint, it’s mandatory to enter the ID of a SharePoint Admin. For ease of use, the best practice is to use a service account for SharePoint similar to OneDrive.
      • Exchange.  You don’t need to take any admin email as input from a requirement perspective as quarantine is not supported. However, MVISION Cloud creates a Quarantine folder in that admin’s mailbox while enabling API access. So for Exchange, it can be any user similar to OneDrive.
      • Dynamics 365. Enter the Application Username. For details, see Configuring and Connecting the Microsoft Dynamics API.
      • Azure IaaS. For Azure IaaS, the value of the admin email is not relevant but should reflect a real user's email address.
        clipboard_e99f8330b1a93f1b2b528529f848fb607.png
  3. Click Submit.

NOTE: For Dynamics 365  STOP HERE.

Microsoft Azure API Connection

To enable Custom Oauth ( Service Principal) connection for Azure, please follow these steps to create the new service principal. Please use "Option 1: Upload a Certificate" as authentication option. https://docs.microsoft.com/en-us/azu...on-two-options  

To enable custom oAuth for Azure, the form has slightly different parameters.

For commercial Azure and for Gov Cloud Commercial, the Resource URL is populated by default.

NOTES:

  • For Gov cloud configured with Azure Gov, the Resource URL will be "https://management.core.usgovcloudapi.net/"
  • Admin Resource URL is not editable. 
  • If you are configuring Gov cloud with commercial Azure, then please reach out to MVISION Cloud Support to complete the configuration.
    clipboard_e407952288dcbd8cb27d6f6a17bc93dbe.png

NOTES FOR AZURE: 

  • “No valid subscriptions found. Please retry with valid input” error implies that the Reader role is missing.
  • “No valid subscriptions to enable DLP on Azure. Please retry with valid input” error implies that Reader and Data Access role is missing.

Azure Information Protection (AIP) Connection

To enable API access in the MVISION Cloud for AIP:

  1. Log in to MVISION Cloud and go to Settings > Data Classification AIP Service instance and click Enable. You should be prompted to provide the custom oAuth credentials. If you are not prompted then contact Customer Support to enable custom oAuth for the applicable service.
  2. Extract the data from the Manifest file to enter the details of the parameters. The details of the parameters are similar to MVISION CloudAPIconnection except for Admin Email.
    • Admin Email. The email of the user must have Azure Right management and Azure Information and Information Protection permissions.
      clipboard_eda56ece8395badde22649d23a34079e7.png

Office 365 Government Community Cloud (GCC) Support

Add the LD flags for Office365 GCC accounts in GovCloud to select the endpoint for Microsoft. These LD flags can be set in the Tenant / Tenant-CSP / instance /tenant-CSP-instance level.

  • To customize graph API endpoint https://graph.microsoft.us, enable "office365-oauth-v2-config-graphapi-endpoint" LD flag.
  • To customize the outlook endpoint https://outlook.office365.us,  enable "office365-oauth-v2-config-exchangeapi-endpoint" LD flag.
  • To customize management activity endpoint https://manage.office.us,  enable "office365-oauth-v2-config-managementactivityapi-endpoint" LD flag.
  • To customize Azure AD Graph API endpoint https://graph.windows.us, enable "office365-oauth-v2-config-azureadgraphapi-endpoint" LD flag.
  • To customize the authorization URL prefix https://login.microsoftonline.us, enable "office365-oauth-v2-config-azuread-endpoint"LD flag.

User Account Requirements for Office 365

As described in the section MVISION Cloud API Connection it is best practice to create a user account/service account for MVISION Cloud in your Office 365 environment that is used to install the MVISION Cloud SharePoint Integrator app and keeps the Quarantine folders for the several products.

The best practice is to create an Office 365 user, for example, with the name MVISION Cloud Integration User and username like skyhigh_integration_user@company.onmicrosoft.com. In this case, enter skyhigh_integration_user@company.onmicrosoft.com as the Admin Email when enabling API access.

If you intend to enable API access for all Office 365 products, OneDrive, SharePoint, and Exchange, make sure the user account has the following permissions and functions:

  • Licensed for OneDrive, SharePoint, and Exchange.
  • The user has an email address (preferably the same as the user login name).
  • The user has an Exchange mailbox (For Exchange).
  • The user has "SharePoint Admin" permissions (for SharePoint Quarantine library) (see "MVISION Cloud API Connection" above for more detail).
  • The user has an OneDrive provisioned (for OneDrive Quarantine Library).
  • Using the Email Address of the admin/service user you plan to use, log in to Office 365 and open OneDrive, SharePoint and Mail at least once to make sure the services are initialized.
  • If enabling only for Activity Monitoring, log in using the Email Address of the admin/service user and create a Quarantine folder in the user's OneDrive base directory and the base SharePoint site.

To provision OneDrive, you can log in with this user once and open the OneDrive. It is provisioned on first use. or you can use PowerShell to provision OneDrive as described in this article: https://technet.microsoft.com/en-us/library/dn800987.aspx

IP Allow List

In rare cases, when using IP restrictions in Office 365 vNext and SharePoint the following MVISION Cloud IP addresses/address ranges need to be added to an Allow List in Office 365:

  • 13.57.135.0/25
  • 52.8.140.255
  • 52.52.211.25