Microsoft Graph API v1.1.0

About the connector

The Microsoft Graph API is a RESTful web API that enables you to access Microsoft Cloud service resources.

This document provides information about the Microsoft Graph API connector, which facilitates automated interactions using Microsoft Graph API. Add the Microsoft Graph API connector as a step in FortiSOAR™ playbooks and perform automated operations such as retrieving a list of all risky users from Microsoft Graph API, searching for messages based on Subject delivered to the user within the organization using Microsoft Graph API, or deleting a specific message from the specific user's mailbox in Azure.

Version information

Connector Version: 1.1.0

Authored By: Fortinet

Certified: Yes

FortiSOAR™ Version Tested on: 7.3.1-2105

Microsoft Graph API Version Tested on: v1

Release Notes for version 1.1.0

Following enhancements have been made to the Microsoft Graph API Connector in version 1.1.0:

• Added the following new operations and playbooks:
  • Revoke User Session
  • Get All Named Locations
  • Block New IP Ranges
• Upgraded connector dependency from adal to msal.
• Added Page Size and Offset parameters in Search Message in Users Mailbox action.
• removed Update Time Closed parameter from Update Security Alert action.

Getting Access Tokens

You can get authentication tokens to access the security graph APIs using the Without a User- Application Permission method. For more information see, https://docs.microsoft.com/en-us/graph/auth-v2-service.

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:
   • Directory.Read.All
   • Directory.ReadWrite.All
   • GroupMember.Read.All
   • Group.Read.All
   • Group.ReadWrite.All
   • IdentityRiskyUser.Read.All
   • Mail.ReadBasic.All
   • Mail.Read
   • Mail.ReadWrite
   • SecurityEvents.Read.All
   • SecurityEvents.ReadWrite.All
   • Policy.Read.All
   • Policy.ReadWrite.ConditionalAccess of type Application
2. Enter your client ID in the Client ID parameter field.
3. Enter your client secret in the Client Secret parameter field.
4. Enter 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-graph

Prerequisites to configuring the connector

• You must have the Tenant and Client ID for your Azure Active Directory instance to which you will connect and perform automated operations and the Client secret to access that instance.
• Ensure that host login.microsoftonline.com on port 443 is whitelisted.

Minimum Permissions Required

• For minimum permissions required, refer to 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 Graph API connector card. On the connector popup, click the Configurations tab to enter the required configuration details.

Actions supported by the connector

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

operation: Get Risky Users List

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
"value": [
{
"@odata.type": "",
"id": "",
"isDeleted": "",
"isProcessing": "",
"riskLastUpdatedDateTime": "",
"riskLevel": "",
"riskState": "",
"riskDetail": "",
"userDisplayName": "",
"userPrincipalName": ""
}
]
}

operation: Get Risky User Details

Input parameters

Output

The output contains the following populated JSON schema:
{
"value": [
{
"@odata.type": "",
"id": "",
"isDeleted": "",
"isProcessing": "",
"riskLastUpdatedDateTime": "",
"riskLevel": "",
"riskState": "",
"riskDetail": "",
"userDisplayName": "",
"userPrincipalName": ""
}
]
}

operation: Get All Security Alerts

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 (of endpoints) is returned.

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"value": [
{
"id": "",
"azureTenantId": "",
"azureSubscriptionId": "",
"riskScore": "",
"tags": [],
"activityGroupName": "",
"assignedTo": "",
"category": "",
"closedDateTime": "",
"comments": [],
"confidence": "",
"createdDateTime": "",
"description": "",
"detectionIds": [],
"eventDateTime": "",
"feedback": "",
"incidentIds": [],
"lastEventDateTime": "",
"lastModifiedDateTime": "",
"recommendedActions": [],
"severity": "",
"sourceMaterials": [],
"status": "",
"title": "",
"vendorInformation": {
"provider": "",
"providerVersion": "",
"subProvider": "",
"vendor": ""
},
"alertDetections": [],
"cloudAppStates": [],
"fileStates": [],
"hostStates": [],
"historyStates": [],
"investigationSecurityStates": [],
"malwareStates": [],
"messageSecurityStates": [],
"networkConnections": [],
"processes": [],
"registryKeyStates": [],
"securityResources": [],
"triggers": [],
"userStates": [],
"uriClickSecurityStates": [],
"vulnerabilityStates": []
}
]
}

operation: Get Security Alert

Input parameters

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"id": "",
"azureTenantId": "",
"azureSubscriptionId": "",
"riskScore": "",
"tags": "",
"activityGroupName": "",
"assignedTo": "",
"category": "",
"closedDateTime": "",
"comments": "",
"confidence": "",
"createdDateTime": "",
"description": "",
"detectionIds": "",
"eventDateTime": "",
"feedback": "",
"lastModifiedDateTime": "",
"recommendedActions": "",
"severity": "",
"sourceMaterials": "",
"status": "",
"title": "",
"vendorInformation": {
"provider": "",
"providerVersion": "",
"subProvider": "",
"vendor": ""
},
"cloudAppStates": "",
"fileStates": "",
"hostStates": "",
"historyStates": "",
"malwareStates": "",
"networkConnections": "",
"processes": "",
"registryKeyStates": "",
"triggers": "",
"userStates": "",
"vulnerabilityStates": ""
}

operation: Update Security Alert

Input parameters

Output

The output contains a non-dictionary value.

operation: Get Groups

Input parameters

None.

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"value": [
{
"id": "",
"deletedDateTime": "",
"classification": "",
"createdDateTime": "",
"description": "",
"displayName": "",
"expirationDateTime": "",
"groupTypes": [],
"isAssignableToRole": "",
"mail": "",
"mailEnabled": "",
"mailNickname": "",
"membershipRule": "",
"membershipRuleProcessingState": "",
"onPremisesLastSyncDateTime": "",
"onPremisesSecurityIdentifier": "",
"onPremisesSyncEnabled": "",
"preferredDataLocation": "",
"preferredLanguage": "",
"proxyAddresses": [],
"renewedDateTime": "",
"resourceBehaviorOptions": [],
"resourceProvisioningOptions": [],
"securityEnabled": "",
"theme": "",
"visibility": "",
"onPremisesProvisioningErrors": []
}
]
}

operation: Get Users Within A Group

Input parameters

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"value": [
{
"id": "",
"mail": ""
}
]
}

operation: Search Message in Users Mailbox

Input parameters

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"value": [
{
"@odata.etag": "",
"id": "",
"subject": "",
"sender": {
"emailAddress": {
"name": "",
"address": ""
}
}
}
]
}

operation: Delete Message

Input parameters

Output

The output contains the following populated JSON schema:
{
"status_code": ""
}

operation: Delete Message Bulk

Input parameters

Output

The output contains the following populated JSON schema:
{
"Error_List": [
{
"error_msg": "",
"user_id": {
"user_id": "",
"message_id": ""
}
}
],
"Message_Deleted_List": [
{
"msg_deleted": "",
"user_id": {
"user_id": "",
"message_id": ""
}
}
],
"Run_Time": "",
"Total_Users_Processed": ""
}

operation: Revoke User Session

Input parameters

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"value": ""
}

operation: Get All Named Locations

Input parameters

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"value": [
{
"@odata.type": "",
"id": "",
"displayName": "",
"modifiedDateTime": "",
"createdDateTime": "",
"isTrusted": false,
"ipRanges": [
{
"@odata.type": "",
"cidrAddress": ""
}
]
}
]
}

operation: Block New IP Ranges

Input parameters

Output

The output contains the following populated JSON schema:
{
"@odata.context": "",
"@odata.type": "",
"id": "",
"displayName": "",
"modifiedDateTime": "",
"createdDateTime": "",
"isTrusted": "",
"ipRanges": [
{
"@odata.type": "",
"cidrAddress": ""
}
]
}

Included playbooks

The Sample - Microsoft Graph API - 1.1.0 playbook collection comes bundled with the Microsoft Graph API connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Microsoft Graph API connector.

• Block New IP Ranges
• Delete Message
• Delete Message Bulk
• Get All Named Locations
• Get All Security Alerts
• Get Groups
• Get Risky User Details
• Get Risky Users List
• Get Security Alert
• Get Users Within A Group
• Search Message in Users Mailbox
• Update Security Alert
• Revoke User Session

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 connector upgrade and delete.