Use the Microsoft Graph API integration to interact with Microsoft APIs that do not have dedicated integrations in Cortex XSOAR, for example, Mail Single-User, etc.
Note: In this documentation, we will use the Application resource type as an example.
In order to use the integration, there are 2 application authentication methods available.
Note: Depending on the authentication method that you use, the integration parameters might change.
In this method, the device authorization grant flow is used.
To configure the integration:
The Application ID integration parameter should be set to
8922dd2d-7539-4711-b839-374f86083959(the Cortex XSOAR Azure app ID).
The Scope integration parameter should be set according to the requested OAuth2 permissions types to grant access to in Microsoft identity platform, for more details see the Microsoft documentation. For example, if we wish to use the List applications API, we need at least the
The Application Secret and the Tenant ID integration parameters should be left blank.
Run the msgraph-api-auth-start command - you will be prompted to open the page https://microsoft.com/devicelogin and enter the generated code.
Run the msgraph-api-auth-complete command
Run the msgraph-api-test command to ensure connectivity to Microsoft.
For more information, refer to the following article.
The Application Secret and the Tenant ID integration parameters are required for this method.
The integration supports only Application permission type, and does not support Delegated permission type.
- Register the app.
- Add the requested API permissions according to the APIs you wish to use. For example, according to the Create application API documentation in order to create applications we need the Application.ReadWrite.All application permission.
- Grant admin consent for the chosen permissions.
Note: The integration stores in cache the API access token based on the permissions it is first run with, so if the permissions are modified, it is recommended to create a new instance of the integration.
- Navigate to Settings > Integrations > Servers & Services.
- Search for Microsoft Graph API.
- Click Add instance to create and configure a new integration instance.
|scope||Scope (Required for using Cortex XSOAR Azure app)||False|
|app_secret||Application Secret (Required for using self deployed Azure app)||False|
|tenant_id||Tenant ID (Required for using self deployed Azure app)||False|
|azure_ad_endpoint||Azure AD endpoint associated with a national cloud||False|
|insecure||Trust any certificate (not secure)||False|
|proxy||Use system proxy settings||False|
- Click Test to validate the URLs, token, and connection.
You can execute the command 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.
Run a Microsoft Graph API query.
|resource||The resource in Microsoft Graph to refer.||Required|
|http_method||The HTTP method used for the request to Microsoft Graph. Possible values are: "GET", "POST", "DELETE", "PUT", or "PATCH". Default is "GET".||Optional|
|api_version||The version of the Microsoft Graph API to use. Possible values are: "v1.0" or "beta". Default is "v1.0".||Optional|
|request_body||The request body (required for POST queries).||Optional|
|odata||OData system query options, e.g. $filter=startswith(givenName, 'J'). For more details see https://docs.microsoft.com/en-us/graph/query-parameters. Default is "$top=10".||Optional|
|populate_context||If "true", will populate the API response to the context data. Default is "true".||Optional|
The context data output depends on the resource executed. The populate_context argument sets whether to output to the context data, under the path MicrosoftGraph. For resources which return a large response, we recommend to narrow the results by using the odata argument or outputting to the context data using Extend Context.
Let's say we want to list all the applications.
We can see that according to the HTTP request:
- The HTTP method is GET
- The resource is /applications
So in order to list all the applications using the integration, we would run the command:
!msgraph-api resource=/applications http_method=GET
- In order to limit the number of results returned from Microsoft Graph API, the default value of the odata command argument is
$top=10. Some of the Graph APIs do not support the
topresource, and in that case the following error message will be returned:
This resource does not support custom page sizes. Please retry without a page size argument.In this case, you can modify the odata command argument to not include the
topresource. For example, run the command with the odata command argument set to
$count=trueto include a count of the total number of items in a collection alongside the page of data values returned from Microsoft Graph.