Microsoft Graph API v1.0.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.0.0

Authored By: Community

Certified: No

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 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

• Not applicable

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 a non-dictionary value.

Included playbooks

The Sample - Microsoft Graph API - 1.0.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.

• Delete Message
• Delete Message Bulk
• 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

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.