Microsoft Management Activity API v1.0.1

About the connector

Office 365 Management Activity API is used to retrieve information about user, admin, system, and policy actions and events from Office 365 and Azure AD activity logs.

This document provides information about the Microsoft Management Activity API connector, which facilitates automated interactions with Microsoft Management Activity API using FortiSOAR™ playbooks. Add the Microsoft Management Activity API connector as a step in FortiSOAR™ playbooks and perform automated operations, such as retrieving a list of current subscriptions, starting a subscription for a specified content type, etc.

Use the Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling alerts from Microsoft Defender Office 365. Currently, "Content Data" in Microsoft Management Activity API is mapped to "alerts" in FortiSOAR™. For more information, see the Data Ingestion Support section

Version information

Connector Version: 1.0.1

FortiSOAR™ Version Tested on: 7.3.1-2105

Authored By: Fortinet

Certified: Yes

Release Notes for version 1.0.1

The following enhancements have been made to the Microsoft Management Activity API connector in version 1.0.1:

• Updated the mechanism used by the connector for 'Authentication' by removing the dependent 'ADAL' python library package. This package was used in the previous release to authenticate Azure Active Directory (AAD) for gaining access to AAD-protected web resources.
• Added support for multiple configurations in the Data Ingestion Wizard to ensure that the respective global variables based on the selected configuration are used while ingesting data. Earlier, even when there were multiple configurations, only one global variable was used.
• Updated the field type of the 'Workload Filter' input parameter from "text" to "multi-select list" in the 'MS Management Activity List Content' action.
  Note: If you used the Microsoft Management Activity API connector v1.0.0 and manually added values to the 'Workload Filter' field, and you upgrade your connector to v1.0.1, then the values added to the 'Workload Filter' field get reset, and you require to re-select the values from the "multi-select list".

Getting Access Tokens

You can get authentication tokens to access the management activity APIs using two methods:

• On behalf of the User – Delegated Permission.
• Without a User - Application Permission.

For more information see, https://docs.microsoft.com/en-us/office/office-365-management-api/get-started-with-office-365-management-apis

Getting Access Tokens using the On behalf of the user – Delegated Permission method

1. Ensure that the required permissions are granted for the registration of the application.
   For example, for a Microsoft Graph User: API/Permission name that should be granted is:
   • ActivityFeed.Read,
   • ServiceHealth.Read
   • ActivityFeed.ReadDlp (this permission is required if you want to read data loss prevention or sensitive data) of type 'Delegated'.
2. The Redirect URL can be directed to any web application in which you want to receive responses from Azure AD. If you are unsure about what to set as a redirect URL, you can use https://localhost/myapp.
3. Copy the following URL and replace the TENANT_ID, CLIENT_ID, and REDIRECT_URI with your own tenant ID, client ID, and redirect URL:
   https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/authorize?response_type=code&scope=offline_access https://manage.office.com/ActivityFeed.Read https://manage.office.com/ActivityFeed.ReadDlp https://manage.office.com/ServiceHealth.Read&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI
4. Enter the above link with the replaced values and you will be prompted to grant permissions for your Azure Service Management. You will be automatically redirected to a link with the following structure: REDIRECT_URI?code=AUTH_CODE&session_state=SESSION_STATE
5. Enter the following details in the Connector Configuration dialog in your FortiSOAR instance:
   1. Copy the AUTH_CODE (without the "code=" prefix) and paste it into your instance configuration in the 'Authorization Code' parameter.
   2. Copy your client ID in the 'Client ID' parameter field.
   3. Copy your client secret in the 'Client Secret' parameter field.
   4. Copy your tenant ID in the 'Tenant ID' parameter field.
   5. Copy your redirect URI in the 'Redirect URL' parameter field. By default, it is set to https://localhost/myapp.

Getting Access Tokens using the Without a User - Application Permission method

1. Ensure that the required permissions are granted for the registration of the application.
   For example, for a Microsoft Graph User: API/Permission name that should be granted is:
   • ActivityFeed.Read,
   • ServiceHealth.Read
   • ActivityFeed.ReadDlp (this permission is required if you want to read data loss prevention or sensitive data) of type 'Application'.
2. Enter the following details in the Connector Configuration dialog in your FortiSOAR instance:
   1. Copy your client ID in the 'Client ID' parameter field.
   2. Copy your client secret in the 'Client Secret' parameter field.
   3. Copy your tenant ID in the 'Tenant ID' parameter field.

Installing the connector

Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.

You can also use the following yum command as a root user to install connectors from an SSH session:
yum install cyops-connector-microsoft-management-activity-api

Prerequisites to configuring the connector

• You must have acquired authentication tokens to access the management activity graph APIs using 'Delegated' or 'Application' Permissions. For more information see the Getting Access Tokens section.
• Ensure that host login.microsoftonline.com on port 443 is in the allowlist of your Firewall or Proxy servers.

Minimum Permissions Required

• As defined in the Getting Access Tokens section.

Configuring the connector

For the procedure to configure a connector, click here.

Configuration parameters

In FortiSOAR™, on the Content Hub (or Connector Store) page, click the Manage tab, and then click the Microsoft Management Activity API connector card. On the connector popup, click the Configurations tab to enter the required configuration details.

Parameter	Description
Get Access Token	Select the method using which you will get access tokens used to access the management activity APIs. You can choose between On behalf of User – Delegated Permission or Without a User - Application Permission. For more information, see the Getting Access Tokens section.
Server URL	The service-based URL to which you will connect and perform the automated operations.
Client ID	Unique ID of the Azure Active Directory application that is used to create an authentication token required to access the API.
Client Secret	Unique Client Secret of the Azure Active Directory application that is used to create an authentication token required to access the API. For information on how to get the secret key, see https://docs.microsoft.com/en-us/windows/security/threat-protection/microsoft-defender-atp/exposed-apis-create-app-webapp.
Tenant ID	ID of the tenant that you have been provided for your Azure Active Directory instance.
Authorization Code	(Only Applicable to On behalf of User – Delegated Permission) The authorization code that you acquired during the authorization step. For more information, see the Getting Access Tokens using the Delegated Permissions method section.
Redirect URL	(Only Applicable to On behalf of User – Delegated Permission) The redirect_url of your app, where authentication responses can be sent and received by your app. The redirect URL that you specify here must exactly match one of the redirect_url's you have registered in your app registration portal.
Verify SSL	Specifies whether the SSL certificate for the server is to be verified or not. By default, this option is set as True.

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations from FortiSOAR™:

Function	Description	Annotation and Category
MS Management Activity Start Subscription	Starts a subscription in Microsoft Management Activity API for the content type you have specified.	start_subscription Investigation
MS Management Activity Stop Subscription	Stops a subscription from Microsoft Management Activity API for the content type you have specified.	stop_subscription Investigation
MS Management Activity List Subscription	Retrieves a list of current subscriptions from Microsoft Management Activity API	list_subscription Investigation
MS Management Activity List Content	Retrieves content from Microsoft Management Activity API based on the content type and other parameters you have specified. Note: If you do not specify any content type then content from all the content types to which you are subscribed is returned.	list_content Investigation

operation: MS Management Activity Start Subscription

Input parameters

Parameter	Description
Content Type	The content type for which you want to start a subscription in Microsoft Management Activity API. You can choose from the following options: Audit.AuzureActiveDirectory, Audit.Exchange, Audit.Sharepoint, or Audit.General.

Output

The output contains the following populated JSON schema:
{
"contentType": "",
"status": "",
"webhook": ""
}

operation: MS Management Activity Stop Subscription

Input parameters

Parameter	Description
Content Type	The content type for which you want to stop a subscription from Microsoft Management Activity API. You can choose from the following options: Audit.AuzureActiveDirectory, Audit.Exchange, Audit.Sharepoint, or Audit.General.

Output

The output contains the following populated JSON schema:
{
"contentType": "",
"status": "",
"webhook": ""
}

operation: MS Management Activity List Subscription

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
"contentType": "",
"status": "",
"webhook": ""
}

operation: MS Management Activity List Content

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.

Parameter	Description
Content Type	The content type for which you want to retrieve content from Microsoft Management Activity API.
Start Time	The earliest time from when you want to retrieve content from Microsoft Management Activity API. If you specify this parameter, then you must also specify the End Time parameter. Also, the Start Time must be before the End Time, and can be at the most 7 days ago, and has to be within 24 hours from the End Time.
End Time	The latest time till when you want to retrieve content from Microsoft Management Activity API. If you specify this parameter, then you must also specify the Start Time parameter. Also, the Start Time must be before the End Time, and can be at the most 7 days ago, and has to be within 24 hours from the End Time.
Record Type Filter	Select the values of the record type whose content you want to fetch from Microsoft Management Activity API. This filter matches the record type specified in this parameter with the content records in Microsoft Management Activity API. If you do not specify any value for this parameter, then records do not get filtered for record types. You can choose from options such as ExchangeAdmin, Sharepoint, PowerBIAudit, etc.
Workload Filter	Select the values of the workloads whose content you want to fetch from Microsoft Management Activity API. This filter matches the workload specified in this parameter with the content records in Microsoft Management Activity API. If you do not specify any value for this parameter, then records do not get filtered for workloads. You can choose from options such as Aip, AppGovernance, AirInvestigation, etc.
Operation Filter	Specify the CSV value that contains operation types to fetch content from Microsoft Management Activity API. This filter matches the operation specified in this parameter with the content records in Microsoft Management Activity API. If you do not specify any value for this parameter, then records do not get filtered for operations.

Output

The output contains the following populated JSON schema:
{
"contentUri": "",
"contentId": "",
"contentType": "",
"contentCreated": "",
"contentExpiration": ""
}

Included playbooks

The Sample - Microsoft Management Activity API- 1.0.1 playbook collection comes bundled with the Microsoft Management Activity API connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Microsoft Management Activity API connector.

• > Microsoft Management Activity API > Fetch and Create
• Microsoft Management Activity API > Ingest
• MS Management Activity List Content
• MS Management Activity List Subscription
• MS Management Activity Start Subscription
• MS Management Activity Stop Subscription

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.

Data Ingestion Support

Use the Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling alerts from Microsoft Defender Office 365. Currently, "Content Data" is ingested from Microsoft Management Activity API is mapped to "alerts" in FortiSOAR™. For more information on the Data Ingestion Wizard, see the "Connectors Guide" in the FortiSOAR™ product documentation.

Configure Data Ingestion

You can configure data ingestion using the “Data Ingestion Wizard” to seamlessly map the incoming Microsoft Management Activity API "Content Data" to FortiSOAR™ "Alerts".

The Data Ingestion Wizard enables you to configure scheduled pulling of data from Microsoft Management Activity API into FortiSOAR™. It also lets you pull some sample data from Microsoft Management Activity API using which you can define the mapping of data between Microsoft Management Activity API and FortiSOAR™. The mapping of common fields is generally already done by the Data Ingestion Wizard; users mostly require to only map any custom fields that are added to Microsoft Management Activity API alerts.

1. To begin configuring data ingestion, click Configure Data Ingestion on the Microsoft Management Activity API connector’s "Configurations" page.
   Click Let’s Start by fetching some data, to open the “Fetch Sample Data” screen.
   
   Sample data is required to create a field mapping between the Microsoft Management Activity API data and FortiSOAR™. The sample data is pulled from connector actions or ingestion playbooks.
2. On the Fetch Data screen, provide the configurations required to fetch data from Microsoft Management Activity API.
   Users can choose to pull data from Microsoft Management Activity API specifying the last X minutes in which the alerts were created in Microsoft Management Activity API. You can select the content type for which you want to retrieve content from Microsoft Management Activity API and you can also specify additional filters such as record type, operation type, or workload type that you want to apply to the content to be retrieved from Microsoft Management Activity API. The fetched data is used to create a mapping between the Microsoft Management Activity API data and FortiSOAR™ alerts.
   
   Once you have completed specifying the configurations, click Fetch Data.
3. On the Field Mapping screen, map the fields of the data ingested from Microsoft Management Activity API to the fields of an alert present in FortiSOAR™.
   To map a field, click the key in the sample data to add the “jinja” value of the field. For example, to map the workload parameter of data ingested from Microsoft Management Activity API to the Source Process parameter of a FortiSOAR™ alert, click the Source Process field and then click the workload field to populate its keys.
   
   For more information on field mapping, see the Data Ingestion chapter in the "Connectors Guide" in the FortiSOAR™ product documentation. Once you have completed the mapping fields, click Save Mapping & Continue.
4. Use the Scheduling screen to configure schedule-based ingestion, i.e., specify the polling frequency to Microsoft Management Activity API, so that the content gets pulled from the Microsoft Management Activity API integration into FortiSOAR™.
   On the Scheduling screen, from the Do you want to schedule the ingestion? drop-down list, select Yes.
   In the “Configure Schedule Settings” section, specify the Cron expression for the schedule. For example, if you want to pull data from Microsoft Management Activity API every 5 minutes, click Every X Minute, and in the minute box enter */5. This would mean that based on the configuration you have set up, data will be pulled from Microsoft Management Activity API every 5 minutes.
   
   Once you have completed scheduling, click Save Settings & Continue.
5. The Summary screen displays a summary of the mapping done, and it also contains links to the Ingestion playbooks. Click Done to complete the data ingestion and exit the Data Ingestion Wizard.