Microsoft_Graph_Files

Use the O365 File Management (Onedrive/Sharepoint/Teams) integration to enable your app to get authorized access to files in OneDrive, SharePoint, and MS Teams across your entire organization. This integration requires admin consent.

Authentication

For more details about the authentication used in this integration, see Microsoft Integrations - Authentication.

Required Permissions

The required permission depends on whether you want to access all sites (Sites.ReadWrite.All) or specific sites (Site.Selected):

• Sites.ReadWrite.All: Provides read and write access to all sites.
  Client Credentials Flow - Application permission.
  Authorization Code Flow - Delegated permission.

Note: This permission is sufficient for all the commands, but if you want the least privileged permissions for each command, they are listed for each command definition.

OR

• Sites.Selected - Application: Provides read and write access to specific sites.
  This option is not supported with the Authorization Code Flow according to Microsoft documentation.

Note: Using Site.Selected requires additional configuration steps outlined below.

Steps to use the Site.Selected permission

Two applications and two instances are required, one for the administrator and one for the user.

Configuration:

1. In the Microsoft website:
   1. Create “Admin” application with the Sites.FullControl.All permission.
   2. Create “User” application with the Site.Selected - Application permission.
2. In Cortex XSOAR, navigate to Settings > Integrations.
3. Search for O365 File Management (Onedrive/Sharepoint/Teams).
4. Create an admin instance:
   1. Click Add instance to create and configure a new integration instance.
   2. Enter the admin application credentials.
   3. Click Test to validate the connection.
   4. Use the following commands to give the user application access to specific sites:
      • msgraph-list-site-permissions - Get permissions for a site
      • msgraph-create-site-permissions - Add permissions for a site
      • msgraph-update-site-permissions - Update permissions for a site
      • msgraph-delete-site-permissions - Delete permissions for a site
   5. Delete the admin instance after configuring user access.
5. Create a user instance:
   1. Click Add instance to create and configure a new integration instance.
   2. Enter the user application credentials.
   3. Click Test to validate the connection.

Note: The msgraph-list-sharepoint-sites command cannot be run, as it requires the Sites.Read.All - Application permission.

• YouTube tutorial from Microsoft.
• Microsoft documentation.

Configure O365 File Management (Onedrive/Sharepoint/Teams) on Cortex XSOAR

1. Navigate to Settings > Integrations.
2. Search for O365 File Management (Onedrive/Sharepoint/Teams).

3. Click Add instance to create and configure a new integration instance.

   Parameter	Description	Required
   Server URL		True
   Application ID / Client ID		False
   Token / Tenant ID		False
   Key / Client Secret		False
   Application redirect URI (for Self Deployed - Authorization Code Flow)		False
   Authorization code (for Self Deployed - Authorization Code Flow)		False
   Certificate Thumbprint	Used for certificate authentication. As appears in the “Certificates & secrets” page of the app.	False
   Private Key	Used for certificate authentication. The private key of the registered certificate.	False
   Use a self-deployed Azure Application	Select this checkbox if you are using a self-deployed Azure application.	False
   Use Azure Managed Identities	Relevant only if the integration is running on Azure VM. If selected, authenticates based on the value provided for the Azure Managed Identities Client ID field. If no value is provided for the Azure Managed Identities Client ID field, authenticates based on the System Assigned Managed Identity. For additional information, see the Help tab.	False
   Azure Managed Identities Client ID	The Managed Identities client ID for authentication - relevant only if the integration is running on Azure VM.	False
   Trust any certificate (not secure)		False
   Use system proxy settings		False

4. Click Test to validate the URLs, token, and connection.

Commands

You can execute these commands from the Cortex XSOAR CLI, as part of an automation, or in a playbook.
After you successfully execute a command, a DBot message appears in the War Room with the command details.

msgraph-delete-file

Deletes an item from OneDrive.

Base Command

msgraph-delete-file

Required Permissions

Client Credentials Flow - Files.ReadWrite.All - Application
Authorization Code Flow - Files.ReadWrite.All - Delegated

Input

Context Output

There is no context output for this command.

Command Example

!msgraph-delete-file object_type=drives object_type_id=test item_id=test

Human Readable Output

123
Item was deleted successfully

msgraph-upload-new-file

Uploads a file from Cortex XSOAR to the specified MS Graph resource.

Base Command

msgraph-upload-new-file

Required Permissions

Client Credentials Flow - Sites.ReadWrite.All - Application
Authorization Code Flow - Files.ReadWrite.All - Delegated

Input

Context Output

Command Example

!msgraph-upload-new-file object_type=drives object_type_id=123 parent_id=123 file_name="test.txt" entry_id=123

Context Example

{
    "MsGraphFiles.UploadedFiles": {
        "ParentReference": {
            "DriveId": "test",
            "DriveType": "documentLibrary",
            "ID": "test",
            "Path": "test"
        },
        "LastModifiedBy": {
            "Type": "Application",
            "DisplayName": "Microsoft Graph",
            "ID": "test"
        },
        "LastModifiedDateTime": "2020-01-22T20:03:00Z",
        "CreatedBy": {
            "Type": "Application",
            "DisplayName": "Microsoft Graph",
            "ID": "test"
        },
        "CreatedDateTime": "2020-01-22T20:03:00Z",
        "WebUrl": "test",
        "FileSystemInfo": {
            "CreatedDateTime": "2020-01-22T20:03:00Z",
            "LastModifiedDateTime": "2020-01-22T20:03:00Z"
        },
        "DownloadUrl": "test",
        "File": {
            "MimeType": "text/plain",
            "Hashes": {
                "QuickXorHash": "test"
            }
        },
        "OdataContext": "test",
        "Size": 15,
        "ID": "test",
        "Name": "test.txt"
    }
}

Human Readable Output

CreatedBy	CreatedDateTime	ID	LastModifiedBy	Name	Size	WebUrl
Microsoft Graph	2020-01-22T20:03:00Z	Test	Microsoft Graph	test.txt	15	Test

msgraph-replace-existing-file

Replaces the content of the file in the specified MS Graph resource.

Base Command

msgraph-replace-existing-file

Required Permissions

Client Credentials Flow - Sites.ReadWrite.All - Application
Authorization Code Flow - Files.ReadWrite.All - Delegated

Input

Context Output

Command Example

!msgraph-replace-existing-file object_type=drives entry_id=test item_id=test object_type_id=test

Context Example

{
    "MsGraphFiles.ReplacedFiles": {
        "ParentReference": {
            "DriveId": "test",
            "DriveType": "documentLibrary",
            "ID": "test",
            "Path": "test"
        },
        "LastModifiedBy": {
            "Type": "Application",
            "DisplayName": "Microsoft Graph",
            "ID": "test"
        },
        "LastModifiedDateTime": "2020-01-22T20:03:06Z",
        "CreatedBy": {
            "Type": "Application",
            "DisplayName": "SharePoint DEV",
            "ID": "test"
        },
        "CreatedDateTime": "2020-01-05T15:30:21Z",
        "WebUrl": "test",
        "FileSystemInfo": {
            "CreatedDateTime": "2020-01-05T15:30:21Z",
            "LastModifiedDateTime": "2020-01-22T20:03:06Z"
        },
        "DownloadUrl": "test",
        "File": {
            "MimeType": "text/plain",
            "Hashes": {
                "QuickXorHash": "test"
            }
        },
        "OdataContext": "test",
        "Size": 15,
        "ID": "test",
        "Name": "test.txt"
    }
}

Human Readable Output

MsGraphFiles - File information

Created By	Created Date Time	ID	Last Modified By	Name	Size	Web Url
SharePoint DEV	2020-01-05T15:30:21Z	123	Microsoft Graph	yaya.txt	15	123

msgraph-create-new-folder

Creates a new folder in a drive with the specified parent item or path.

Base Command

msgraph-create-new-folder

Required Permissions

Client Credentials Flow - Files.ReadWrite.All - Application
Authorization Code Flow - Files.ReadWrite.All - Delegated

Input

Context Output

Command Example

!msgraph-create-new-folder object_type=drives object_type_id=123 parent_id=123 folder_name=test11

Context Example

{
    "MsGraphFiles.CreatedFolders": {
        "ParentReference": {
            "DriveId": "test",
            "DriveType": "documentLibrary",
            "ID": "test",
            "Path": "test"
        },
        "OdataContext": "test",
        "LastModifiedDateTime": "2020-01-22T20:03:09Z",
        "Name": "test11 19",
        "CreatedDateTime": "2020-01-22T20:03:09Z",
        "WebUrl": "test",
        "FileSystemInfo": {
            "CreatedDateTime": "2020-01-22T20:03:09Z",
            "LastModifiedDateTime": "2020-01-22T20:03:09Z"
        },
        "LastModifiedBy": {
            "Type": "Application",
            "DisplayName": "Microsoft Graph",
            "ID": "test"
        },
        "CreatedBy": {
            "Type": "Application",
            "DisplayName": "Microsoft Graph",
            "ID": "test"
        },
        "Folder": {
            "ChildCount": 0
        },
        "ID": "test",
        "Size": 0
    }
}

Human Readable Output

MsGraphFiles - Folder information

Child Count	Created By	Created Date Time	ID	Last Modified By	Name	Size	Web Url
ChildCount: 0	Microsoft Graph	2020-01-22T20:03:09Z	123	Microsoft Graph	test11 19	0	123

msgraph-list-drives-in-site

Returns the list of document libraries (drives) available for a target site.

Base Command

msgraph-list-drives-in-site

Required Permissions

Client Credentials Flow - Files.Read.All - Application
Authorization Code Flow - Files.Read - Delegated

Input

Context Output

Command Example

!msgraph-list-drives-in-site limit=1 site_id=test limit=1

Context Example

{
    "MsGraphFiles.ListDrives": {
        "OdataContext": "test",
        "Value": [
            {
                "LastModifiedDateTime": "2019-09-21T08:17:20Z",
                "Description": "",
                "CreatedDateTime": "2019-09-21T08:17:20Z",
                "WebUrl": "test",
                "CreatedBy": {
                    "Type": "User",
                    "DisplayName": "System Account"
                },
                "Owner": {
                    "Group": {
                        "DisplayName": "site_test2 Owners",
                        "Email": "test",
                        "ID": "a6975ca6-9adf-40e9-bf1e-3f574e7510ae"
                    }
                },
                "DriveType": "documentLibrary",
                "ID": "test",
                "Name": "Documents"
            }
        ]
    }
}

Human Readable Output

MsGraphFiles - Drives information

Created By	Created Date Time	Description	Drive Type	ID	Last Modified Date Time	Name	Web Url
System Account	2019-09-21T08:17:20Z		documentLibrary	Test	2019-09-21T08:17:20Z	Documents	Test

msgraph-list-drive-content

Returns a list of files and folders in the specified drive.

Base Command

msgraph-list-drive-content

Required Permissions

Client Credentials Flow - Files.Read.All - Application
Authorization Code Flow - Files.Read - Delegated

Input

Context Output

Command Example

!msgraph-list-drive-content object_type=drives limit=1 object_type_id=test parent_id=test

Context Example

{
    "MsGraphFiles.ListChildren": {
        "Children": {
            "OdataContext": "test",
            "Value": [
                {
                    "ParentReference": {
                        "DriveId": "test",
                        "DriveType": "documentLibrary",
                        "ID": "test",
                        "Path": "test"
                    },
                    "LastModifiedDateTime": "2019-12-29T11:57:41Z",
                    "Name": "Attachments",
                    "CreatedDateTime": "2019-12-29T11:57:41Z",
                    "WebUrl": "test",
                    "FileSystemInfo": {
                        "CreatedDateTime": "2019-12-29T11:57:41Z",
                        "LastModifiedDateTime": "2019-12-29T11:57:41Z"
                    },
                    "LastModifiedBy": {
                        "Type": "Application",
                        "DisplayName": "MS Graph Files",
                        "ID": "test"
                    },
                    "CreatedBy": {
                        "Type": "Application",
                        "DisplayName": "MS Graph Files Dev",
                        "ID": "test"
                    },
                    "Folder": {
                        "ChildCount": 2
                    },
                    "ID": "test",
                    "Size": 0
                }
            ]
        },
        "ParentID": "root"
    }
}

Human Readable Output

MsGraphFiles - drivesItems information

Created By	Created Date Time	Description	ID	Last Modified Date Time	Name	Size	Web Url
MS Graph Files Dev	2019-12-29T11:57:41Z		123	2019-12-29T11:57:41Z	Attachments	0	123

msgraph-list-sharepoint-sites

Returns a list of the tenant sites.

Base Command

msgraph-list-sharepoint-sites

Required Permissions

Client Credentials Flow - Sites.Read.All - Application
Authorization Code Flow - Sites.Read.All - Delegated

Input

Context Output

Command Example

!msgraph-list-share-point-sites site_id=123

Context Example

{
    "MsGraphFiles.ListSites": {
        "OdataContext": "123",
        "Value": [
            {
                "LastModifiedDateTime": "2016-09-14T11:13:53Z",
                "DisplayName": "XSOAR Team",
                "Name": "123",
                "CreatedDateTime": "2016-09-14T11:12:59Z",
                "WebUrl": "123",
                "SiteCollection": {
                    "Hostname": "123"
                },
                "Root": {},
                "ID": "123"
            }
        ]
    }
}

Human Readable Output

Created Date Time	ID	Last Modified Date Time	Name	Web Url
2016-09-14T11:12:59Z	123	2016-09-14T11:13:53Z	123	123

msgraph-download-file

Downloads the file contents of the drive item.

Base Command

msgraph-download-file

Required Permissions

Client Credentials Flow - Files.Read.All - Application
Authorization Code Flow - Files.Read - Delegated

Input

Context Output

Command Example

!msgraph-download-file object_type=drives object_type_id=123 item_id=123

msgraph-list-site-permissions

List of apps with permissions for the site. If permission_id is provided, it will return the details of that permission.

Required Permissions

Sites.FullControl.All
The command only runs from admin instance.

Base Command

msgraph-list-site-permissions

Input

Context Output

Command example

!msgraph-list-site-permissions site_name=Test

Context Example

{
    "MsGraphFiles": {
        "SitePermission": [
            {
                "grantedToIdentities": [
                    {
                        "application": {
                            "displayName": "MS Graph Files",
                            "id": "test_id"
                        }
                    }
                ],
                "grantedToIdentitiesV2": [
                    {
                        "application": {
                            "displayName": "MS Graph Files",
                            "id": "test_id"
                        }
                    }
                ],
                "id": "test_id"
            },
            {
                "grantedToIdentities": [
                    {
                        "application": {
                            "displayName": "test_admin",
                            "id": "test_id"
                        }
                    }
                ],
                "grantedToIdentitiesV2": [
                    {
                        "application": {
                            "displayName": "test_admin",
                            "id": "test_id"
                        }
                    }
                ],
                "id": "test_id"
            }
        ]
    }
}

Human Readable Output

Site Permission

Application ID	Application Name	ID
test_id	MS Graph Files	test_id
test_id	test_sk_1_admin	test_id

msgraph-create-site-permissions

Create a new application permission for a site.

Required Permissions

Sites.FullControl.All
The command only runs from admin instance.

Base Command

msgraph-create-site-permissions

Input

Context Output

There is no context output for this command.

Command example

!msgraph-create-site-permissions site_name=Test role=write app_id=test_id display_name=test

Context Example

{
    "MsGraphFiles": {
        "SitePermission": {
            "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#sites(test)/permissions/$entity",
            "grantedToIdentities": [
                {
                    "application": {
                        "displayName": "test",
                        "id": "test_id"
                    }
                }
            ],
            "grantedToIdentitiesV2": [
                {
                    "application": {
                        "displayName": "test",
                        "id": "test_id"
                    }
                }
            ],
            "id": "test_id",
            "roles": [
                "write"
            ]
        }
    }
}

Human Readable Output

Site Permission

Application ID	Application Name	ID	Roles
test	test	test	write

msgraph-update-site-permissions

Updates an existing permission for a site.

Required Permissions

Sites.FullControl.All
The command only runs from admin instance.

Base Command

msgraph-update-site-permissions

Input

Context Output

There is no context output for this command.

Command example

!msgraph-update-site-permissions permission_id=test role=read site_name=Test

Human Readable Output

Permission test_id of site site_id was updated successfully with new role [‘read’].

msgraph-delete-site-permissions

Deletes an app permission from a site.

Required Permissions

Sites.FullControl.All
The command only runs from admin instance.

Base Command

msgraph-delete-site-permissions

Input

Context Output

There is no context output for this command.

Command example

!msgraph-delete-site-permissions site_name=Test permission_id=test_id

Human Readable Output

Site permission was deleted.

msgraph-files-auth-test

Tests connectivity to Microsoft.

Base Command

msgraph-files-auth-test

Input

There are no input arguments for this command.

Context Output

There is no context output for this command.

msgraph-files-generate-login-url

Generate the login URL used for Authorization code flow.

Base Command

msgraph-files-generate-login-url

Input

There are no input arguments for this command.

Context Output

There is no context output for this command.

msgraph-files-auth-reset

Run this command if for some reason you need to rerun the authentication process.

Base Command

msgraph-files-auth-reset

Input

There are no input arguments for this command.

Context Output

There is no context output for this command.

msgraph-get-sensitivity-label

Retrieves the sensitivity label currently assigned to a drive item. Returns the label ID, display name, and protection state regardless of whether the label has encryption enabled.

Base Command

msgraph-get-sensitivity-label

Input

Context Output

Command example

!msgraph-get-sensitivity-label object_type=drives object_type_id=b!example item_id=01EXAMPLE

Human Readable Output

Sensitivity Label

Item Id	Display Name	Id	Protection Enabled
01EXAMPLE	Confidential	08973045-2fd6-4014-9177-9f2a3e55c29e	false

msgraph-assign-sensitivity-label

Assigns a sensitivity label to a drive item. Microsoft Graph treats this call as a long-running operation and returns the operation status URL in the Location response header; poll that URL to track completion. HTTP error responses from Microsoft Graph are surfaced verbatim as a command error.

Base Command

msgraph-assign-sensitivity-label

Input

Context Output

Command example

!msgraph-assign-sensitivity-label object_type=drives object_type_id=b!example item_id=01EXAMPLE sensitivity_label_id=08973045-2fd6-4014-9177-9f2a3e55c29e

Human Readable Output

Assigned Sensitivity Label

Item Id	Sensitivity Label Id	Location
01EXAMPLE	08973045-2fd6-4014-9177-9f2a3e55c29e	https://contoso.sharepoint.com/_api/v2.0/monitor/MyMonitorJobId

msgraph-driveitem-update

Updates a driveItem (move within or across drives, rename, or update metadata) by issuing PATCH on the driveItem.
At least one of new_parent_id, new_parent_drive_id, new_name, description, or conflict_behavior must be provided.

Base Command

msgraph-driveitem-update

Input

Context Output

msgraph-driveitem-copy

Initiates an asynchronous copy of a driveItem (file or folder) within or across drives. Microsoft Graph processes the copy asynchronously and responds 202 Accepted with a monitor URL. Poll the returned MonitorUrl directly against Microsoft Graph (using the same access token) until the body reports status completed or failed.

Base Command

msgraph-driveitem-copy

Input

Context Output

msgraph-driveitem-permissions-list

Lists the sharing permissions on a driveItem. Returns both link-style permissions (anyone-with-link, organization-wide-link, scoped link) and direct grants (per-user / per-group / per-application). The InheritedFrom field is non-null when the permission is inherited from a parent folder.

Base Command

msgraph-driveitem-permissions-list

Input

Context Output

msgraph-driveitem-permission-delete

Deletes (revokes) a single sharing permission from a driveItem. Returns success when Microsoft Graph responds 204. For bulk-delete loops where intermittent 404s (already removed) are acceptable, enable “Continue on error” on the calling task.

Base Command

msgraph-driveitem-permission-delete

Input

Context Output

msgraph-driveitem-activities-list

Retrieves the recent activities that took place on a file or folder (driveItem), such as who accessed it and when.
Activities are stored against the SharePoint list representation of the item, so the command first resolves the item’s SharePoint list identifiers and then reads the activities from the list item. This resolution is internal - only site_id and item_id are needed.
Note: Activity data is not available in all national deployments and is not supported for personal Microsoft accounts. When no activity has been recorded for the item, Microsoft Graph returns an empty result rather than an error.

Required Permissions

Client Credentials Flow - Sites.Read.All - Application or Sites.ReadWrite.All - Application
Authorization Code Flow - Sites.Read.All - Delegated or Sites.ReadWrite.All - Delegated

Base Command

msgraph-driveitem-activities-list

Input

Context Output

msgraph-driveitem-metadata-get

Retrieves the metadata of a file or folder (driveItem). The item can be addressed by ID, by path relative to the drive root, or by a sharing URL. Exactly one of item_id, item_path, or share_url must be provided.
The returned ItemID is scoped to the drive that stores the item, which is returned as DriveId. A sharing URL that points to a personal file resolves against that user’s OneDrive, so the ItemID it returns differs from the ID the same file has under a SharePoint site library.
Note: addressing the item by share_url requires the Files.ReadWrite.All application permission (or Files.ReadWrite delegated), which is higher than the Files.Read.All required by the item_id and item_path options, even though this command only reads data.

Required Permissions

Client Credentials Flow - Files.Read.All - Application or Files.ReadWrite.All - Application (Note: addressing the item by share_url requires Files.ReadWrite.All - Application)
Authorization Code Flow - Files.Read.All - Delegated or Files.ReadWrite.All - Delegated (Note: addressing the item by share_url requires Files.ReadWrite - Delegated)

Base Command

msgraph-driveitem-metadata-get

Input

Context Output

msgraph-driveitem-analytics-get

Retrieves activity statistics for a file or folder (driveItem), such as how many times it was viewed and by how many people.
Analytics are stored against the SharePoint list representation of the item, so the command first resolves the item’s SharePoint list identifiers and then reads the analytics from the list item. This resolution is internal - only site_id and item_id are needed.
Note: Analytics data is not available in all national deployments and is not supported for personal Microsoft accounts. When no analytics data has been collected for the item, Microsoft Graph returns an empty result rather than an error.

Required Permissions

Client Credentials Flow - Sites.Read.All - Application or Sites.ReadWrite.All - Application
Authorization Code Flow - Sites.Read.All - Delegated or Sites.ReadWrite.All - Delegated

Base Command

msgraph-driveitem-analytics-get

Input

Context Output