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
Connector Version: 1.0.1
FortiSOAR™ Version Tested on: 7.3.1-2105
Authored By: Fortinet
Certified: Yes
The following enhancements have been made to the Microsoft Management Activity API connector in version 1.0.1:
You can get authentication tokens to access the management activity APIs using two methods:
For more information see, https://docs.microsoft.com/en-us/office/office-365-management-api/get-started-with-office-365-management-apis
ActivityFeed.Read
,ServiceHealth.Read
ActivityFeed.ReadDlp
(this permission is required if you want to read data loss prevention or sensitive data) of type 'Delegated'.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
REDIRECT_URI?code=AUTH_CODE&session_state=SESSION_STATE
AUTH_CODE
(without the "code=" prefix) and paste it into your instance configuration in the 'Authorization Code' parameter.ActivityFeed.Read
,ServiceHealth.Read
ActivityFeed.ReadDlp
(this permission is required if you want to read data loss prevention or sensitive data) of type 'Application'.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
For the procedure to configure a connector, click here.
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 . |
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 |
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. |
The output contains the following populated JSON schema:
{
"contentType": "",
"status": "",
"webhook": ""
}
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. |
The output contains the following populated JSON schema:
{
"contentType": "",
"status": "",
"webhook": ""
}
None.
The output contains the following populated JSON schema:
{
"contentType": "",
"status": "",
"webhook": ""
}
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. |
The output contains the following populated JSON schema:
{
"contentUri": "",
"contentId": "",
"contentType": "",
"contentCreated": "",
"contentExpiration": ""
}
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.
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.
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.
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.
*/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.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
Connector Version: 1.0.1
FortiSOAR™ Version Tested on: 7.3.1-2105
Authored By: Fortinet
Certified: Yes
The following enhancements have been made to the Microsoft Management Activity API connector in version 1.0.1:
You can get authentication tokens to access the management activity APIs using two methods:
For more information see, https://docs.microsoft.com/en-us/office/office-365-management-api/get-started-with-office-365-management-apis
ActivityFeed.Read
,ServiceHealth.Read
ActivityFeed.ReadDlp
(this permission is required if you want to read data loss prevention or sensitive data) of type 'Delegated'.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
REDIRECT_URI?code=AUTH_CODE&session_state=SESSION_STATE
AUTH_CODE
(without the "code=" prefix) and paste it into your instance configuration in the 'Authorization Code' parameter.ActivityFeed.Read
,ServiceHealth.Read
ActivityFeed.ReadDlp
(this permission is required if you want to read data loss prevention or sensitive data) of type 'Application'.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
For the procedure to configure a connector, click here.
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 . |
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 |
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. |
The output contains the following populated JSON schema:
{
"contentType": "",
"status": "",
"webhook": ""
}
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. |
The output contains the following populated JSON schema:
{
"contentType": "",
"status": "",
"webhook": ""
}
None.
The output contains the following populated JSON schema:
{
"contentType": "",
"status": "",
"webhook": ""
}
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. |
The output contains the following populated JSON schema:
{
"contentUri": "",
"contentId": "",
"contentType": "",
"contentCreated": "",
"contentExpiration": ""
}
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.
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.
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.
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.
*/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.