Microsoft Graph API v2.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: 2.1.0

Authored By: Fortinet

Certified: Yes

FortiSOAR™ Version Tested on: 7.50.4015

Microsoft Graph API Version Tested on: v1

Release Notes for version 2.1.0

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

• Added support for a certificate-based authentication method. Certificate Based Authentication is a new option in the configuration parameter Get Access Token.

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 yum command as a root user to install the connector:

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 Minimum Permissions Table section.

Configuring the connector

For the procedure to configure a connector, click here

Configuration parameters

In FortiSOAR™, on the Connectors page, click the Microsoft Graph API connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab 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:

{
    "@odata.context": "",
    "value": [
        {
            "id": "",
            "isDeleted": "",
            "isProcessing": "",
            "riskLevel": "",
            "riskState": "",
            "riskDetail": "",
            "riskLastUpdatedDateTime": "",
            "userDisplayName": "",
            "userPrincipalName": ""
        }
    ]
}

operation: Get Risky User Details

Input parameters

Output

The output contains the following populated JSON schema:

{
    "@odata.context": "",
    "id": "",
    "isDeleted": "",
    "isProcessing": "",
    "riskLevel": "",
    "riskState": "",
    "riskDetail": "",
    "riskLastUpdatedDateTime": "",
    "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": "",
    "incidentIds": [],
    "lastEventDateTime": "",
    "lastModifiedDateTime": "",
    "recommendedActions": [],
    "severity": "",
    "sourceMaterials": [],
    "status": "",
    "title": "",
    "vendorInformation": {
        "provider": "",
        "providerVersion": "",
        "subProvider": "",
        "vendor": ""
    },
    "alertDetections": [],
    "cloudAppStates": [],
    "fileStates": [],
    "hostStates": [
        {
            "fqdn": "",
            "isAzureAdJoined": "",
            "isAzureAdRegistered": "",
            "isHybridAzureDomainJoined": "",
            "netBiosName": "",
            "os": "",
            "privateIpAddress": "",
            "publicIpAddress": "",
            "riskScore": ""
        }
    ],
    "historyStates": [],
    "investigationSecurityStates": [],
    "malwareStates": [],
    "messageSecurityStates": [],
    "networkConnections": [],
    "processes": [],
    "registryKeyStates": [],
    "securityResources": [],
    "triggers": [],
    "userStates": [],
    "uriClickSecurityStates": [],
    "vulnerabilityStates": []
}

operation: Update 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": "",
    "incidentIds": [],
    "lastEventDateTime": "",
    "lastModifiedDateTime": "",
    "recommendedActions": [],
    "severity": "",
    "sourceMaterials": [],
    "status": "",
    "title": "",
    "vendorInformation": {
        "provider": "",
        "providerVersion": "",
        "subProvider": "",
        "vendor": ""
    },
    "alertDetections": [],
    "cloudAppStates": [],
    "fileStates": [],
    "hostStates": [
        {
            "fqdn": "",
            "isAzureAdJoined": "",
            "isAzureAdRegistered": "",
            "isHybridAzureDomainJoined": "",
            "netBiosName": "",
            "os": "",
            "privateIpAddress": "",
            "publicIpAddress": "",
            "riskScore": ""
        }
    ],
    "historyStates": [],
    "investigationSecurityStates": [],
    "malwareStates": [],
    "messageSecurityStates": [],
    "networkConnections": [],
    "processes": [],
    "registryKeyStates": [],
    "securityResources": [],
    "triggers": [],
    "userStates": [],
    "uriClickSecurityStates": [],
    "vulnerabilityStates": []
}

operation: Get Groups

Input parameters

None.

Output

The output contains the following populated JSON schema:

{
    "@odata.context": "",
    "value": [
        {
            "id": "",
            "deletedDateTime": "",
            "classification": "",
            "createdDateTime": "",
            "creationOptions": [],
            "description": "",
            "displayName": "",
            "expirationDateTime": "",
            "groupTypes": [],
            "isAssignableToRole": "",
            "mail": "",
            "mailEnabled": "",
            "mailNickname": "",
            "membershipRule": "",
            "membershipRuleProcessingState": "",
            "onPremisesDomainName": "",
            "onPremisesLastSyncDateTime": "",
            "onPremisesNetBiosName": "",
            "onPremisesSamAccountName": "",
            "onPremisesSecurityIdentifier": "",
            "onPremisesSyncEnabled": "",
            "preferredDataLocation": "",
            "preferredLanguage": "",
            "proxyAddresses": [],
            "renewedDateTime": "",
            "resourceBehaviorOptions": [],
            "resourceProvisioningOptions": [],
            "securityEnabled": "",
            "securityIdentifier": "",
            "theme": "",
            "visibility": "",
            "onPremisesProvisioningErrors": []
        }
    ]
}

operation: Get Users Within A Group

Input parameters

Output

The output contains the following populated JSON schema:

{
    "@odata.context": "",
    "value": [
        {
            "@odata.type": "",
            "id": "",
            "businessPhones": [],
            "displayName": "",
            "givenName": "",
            "jobTitle": "",
            "mail": "",
            "mobilePhone": "",
            "officeLocation": "",
            "preferredLanguage": "",
            "surname": "",
            "userPrincipalName": ""
        }
    ]
}

operation: Search Message in Users Mailbox

Input parameters

Output

The output contains the following populated JSON schema:

{
    "Message_Found_List": [
        {
            "@odata.context": "",
            "value": [
                {
                    "@odata.etag": "",
                    "id": "",
                    "createdDateTime": "",
                    "lastModifiedDateTime": "",
                    "changeKey": "",
                    "categories": [],
                    "receivedDateTime": "",
                    "sentDateTime": "",
                    "hasAttachments": "",
                    "internetMessageId": "",
                    "subject": "",
                    "bodyPreview": "",
                    "importance": "",
                    "parentFolderId": "",
                    "conversationId": "",
                    "conversationIndex": "",
                    "isDeliveryReceiptRequested": "",
                    "isReadReceiptRequested": "",
                    "isRead": "",
                    "isDraft": "",
                    "webLink": "",
                    "inferenceClassification": "",
                    "body": {
                        "contentType": "",
                        "content": ""
                    },
                    "sender": {
                        "emailAddress": {
                            "name": "",
                            "address": ""
                        }
                    },
                    "from": {
                        "emailAddress": {
                            "name": "",
                            "address": ""
                        }
                    },
                    "toRecipients": [
                        {
                            "emailAddress": {
                                "name": "",
                                "address": ""
                            }
                        }
                    ],
                    "ccRecipients": [],
                    "bccRecipients": [],
                    "replyTo": [],
                    "flag": {
                        "flagStatus": ""
                    }
                }
            ],
            "user_id": ""
        }
    ],
    "Message_Not_Found_List": [
        {
            "@odata.context": "",
            "value": [],
            "user_id": ""
        }
    ],
    "Run_Time": "",
    "Total_Users_Processed": ""
}

operation: Delete Message

Input parameters

Output

The output contains the following populated JSON schema:

{
    "status_code": ""
}

operation: Delete Message Bulk

Input parameters

    [
        {
            'user_id':"",
            'message_id':""
        },
        {
            'user_id':"",
            'message_id':""
        }
    ]
                

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": ""
        }
    ]
}

operation: Unblock 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": ""
        }
    ]
}

operation: Create IP Named Location

Input parameters

Output

The output contains the following populated JSON schema:

{
    "@odata.context": "",
    "@odata.type": "",
    "id": "",
    "displayName": "",
    "modifiedDateTime": "",
    "createdDateTime": "",
    "isTrusted": "",
    "ipRanges": []
}

Included playbooks

The Sample - Microsoft Graph API - 2.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
• Create IP Named Location
• 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
• Revoke User Session
• Search Message in Users Mailbox
• Unblock IP Ranges
• 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.

Getting Access Tokens

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

• On behalf of the User – Delegate Permission. For more information see, https://docs.microsoft.com/en-us/graph/auth-v2-user
• Without a User – Application Permission. For more information see, https://docs.microsoft.com/en-us/graph/auth-v2-service

Getting Access Tokens using the On behalf of the User – Delegate Permission method

1. Ensure that the required permissions are granted for the registration of the application. Select API Permissions > Add permission > Microsoft Graph > Delegated Permissions.
2. NOTE: The API Permission that should be granted to the registered application is mentioned in the Minimum permissions required for the 'Delegate-type' permission table.
3. The Redirect URL can be directed to any web application in which to receive responses from Azure AD. If you are unsure about what to set as a redirect URL, you can use https://localhost/myapp.
4. Copy the following URL and replace the TENANT_ID, CLIENT_ID, and REDIRECT_URI with your tenant ID, client ID, and the following redirect URL:
   https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/authorize?response_type=code&scope=offline_access https://graph.microsoft.com/.default&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI
5. 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
6. Copy the AUTH_CODE (without the code= prefix) and paste it in your instance configuration in the Authorization Code parameter.
7. Enter your client ID in the Client ID parameter field.
8. Enter your client secret in the Client Secret parameter field.
9. Enter your tenant ID in the Tenant ID parameter field.
10. Enter your redirect URL 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:
   • 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.

Getting Access Tokens using the Certificate Based Authentication method

1. Register an application with the Microsoft identity platform. To know about creating a application, refer https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app#register-an-application.
2. Upload a CA certificate to the Azure portal. To know about uploading the CA certificate, refer Uploading a CA certificate.
3. Note the thumbprint, start date, and expiration values once the certificate is uploaded.
4. Enter the certificate thumbprint and upload the corresponding private key in the Configuration Parameters.

Minimum Permissions Table

To call the Microsoft Graph API, to perform any action, you must be assigned specific permissions as defined in this section. To learn more, including how to choose permissions, see Microsoft Graph's permissions reference.