Microsoft Graph API

Details

ID	`Microsoft Graph API`
Provider	Microsoft
Category	Utilities
From Version	5.0.0
Docker Image	`demisto/crypto:1.0.0.10120494`
Supported Modules	Agentix Cloud Runtime Security Cloud Posture Security XSIAM EDR Cortex Cloud

README

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.

Authorization

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.

Cortex XSOAR Azure app

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 Application.Read.All scope.
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.

Self Deployed Azure app

For more information, refer to the following article.

Configure the Azure app

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.

Configure Microsoft Graph API on Cortex XSOAR

Navigate to Settings > Integrations > Servers & Services.
Search for Microsoft Graph API.

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

Parameter	Description	Required
Azure Cloud	See option table below.	False
Application ID		False
Application Secret (Required for using Self Deployed Azure app)		False
Tenant ID (Required for using Self Deployed Azure app)		False
Application redirect URI (for Self Deployed - Authorization Code Flow)		False
Authorization code (for Self Deployed - Authorization Code Flow)		False
Certificate Thumbprint		False
Private Key		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
Azure AD endpoint	Azure AD endpoint associated with a national cloud. See note below.	False
Scope (Required for using Cortex XSOAR Azure app)	A space-separated list of scopes that you want to consent to.	False
Trust any certificate (not secure)		False
Use system proxy settings		False

Azure cloud options

Azure Cloud	Description
Worldwide	The publicly accessible Azure Cloud
US GCC	Azure cloud for the USA Government Cloud Community (GCC)
US GCC-High	Azure cloud for the USA Government Cloud Community High (GCC-High)
DoD	Azure cloud for the USA Department of Defense (DoD)
Germany	Azure cloud for the German Government
China	Azure cloud for the Chinese Government
Custom	Custom endpoint configuration to the Azure cloud. See note below.

Note: In most cases, setting Azure cloud is preferred to setting Azure AD endpoint. Only use it in cases where a custom URL is required for accessing a national cloud.

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-api-auth-start

Run this command to start the authorization process and follow the instructions in the command results.

msgraph-api-auth-complete

Run this command to complete the authorization process.
Should be used after running the msgraph-api-auth-start command.

msgraph-api-test

Tests connectivity to Microsoft.

msgraph-api-request

Run a Microsoft Graph API query.

Base Command

msgraph-api-request

Input

Argument Name	Description	Required
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, PATCH. Default is GET.	Optional
api_version	The version of the Microsoft Graph API to use. Possible values are: v1.0, 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. It is recommended to use the $top query option to limit the result.	Optional
populate_context	If “true” will populate the API response to the context data. Possible values are: true, false. Default is true.	Optional
headers	A comma-separated list of headers to send in the GET request, for example: ConsistencyLevel:eventual,User-Agent:MyApp/1.0.	Optional

Context Output

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.

msgraph-api-auth-reset

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

Base Command

msgraph-api-auth-reset

Input

There are no input arguments for this command.

Context Output

There is no context output for this command.

msgraph-api-generate-login-url

Generate the login URL used for Authorization code flow.

Base Command

msgraph-api-generate-login-url

Input

There are no input arguments for this command.

Context Output

There is no context output for this command.

Command Example

msgraph-api-generate-login-url

Human Readable Output

Authorization instructions

Click on the login URL to sign in and grant Cortex XSOAR 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

Copy the AUTH_CODE (without the code= prefix, and the session_state parameter)
and paste it in your instance configuration under the Authorization code parameter.

Usage

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

Configuration parameters

azure_cloud — Azure Cloud
app_id — Application ID
credentials —
tenant_id — Tenant ID (Required for using Self Deployed Azure app)
redirect_uri — Application redirect URI (for Self Deployed - Authorization Code Flow)
auth_code —
creds_certificate — Certificate Thumbprint
certificate_thumbprint — Certificate Thumbprint
private_key — Private Key
self_deployed — Use a self-deployed Azure Application
use_managed_identities — Use Azure Managed Identities
managed_identities_client_id —
azure_ad_endpoint — Azure AD endpoint
scope — Scope (Required for using Cortex XSOAR Azure app)
insecure — Trust any certificate (not secure)
proxy — Use system proxy settings
app_secret — Application Secret (Deprecated)

Commands (6)

msgraph-api-auth-complete
Run this command to complete the authorization process. Should be used after running the msgraph-auth-start command.
msgraph-api-auth-reset
Run this command if for some reason you need to rerun the authentication process.
msgraph-api-auth-start
Run this command to start the authorization process and follow the instructions in the command results.
msgraph-api-generate-login-url
Generate the login URL used for Authorization code flow.
msgraph-api-request
Run a Microsoft Graph API query.
msgraph-api-test
Tests connectivity to Microsoft.

Source

MicrosoftGraphAPI.py MicrosoftGraphAPI_test.py MicrosoftGraphAPI.yml MicrosoftGraphAPI_description.md

Download History Raw

category: Utilities
provider: Microsoft
sectionorder:
- Connect
- Collect
commonfields:
  id: Microsoft Graph API
  version: -1
configuration:
- defaultvalue: Worldwide
  display: Azure Cloud
  name: azure_cloud
  required: false
  type: 15
  options:
  - Worldwide
  - US GCC
  - US GCC-High
  - DoD
  - Germany
  - China
  - Custom
  additionalinfo: When selecting the Custom option, the Azure AD endpoint parameter must be filled. More information about National clouds can be found here - https://xsoar.pan.dev/docs/reference/articles/microsoft-integrations---authentication#using-national-cloud
  section: Connect
  advanced: true
- defaultvalue: 8922dd2d-7539-4711-b839-374f86083959
  display: Application ID
  name: app_id
  type: 0
  section: Connect
  required: false
- displaypassword: Application Secret (Required for using Self Deployed Azure app)
  name: credentials
  type: 9
  hiddenusername: true
  section: Connect
  required: false
- display: Tenant ID (Required for using Self Deployed Azure app)
  name: tenant_id
  type: 0
  section: Connect
  advanced: true
  required: false
- display: Application redirect URI (for Self Deployed - Authorization Code Flow)
  name: redirect_uri
  type: 0
  section: Connect
  required: false
- display: ''
  name: auth_code
  type: 9
  section: Connect
  required: false
  displaypassword: Authorization code (for Self Deployed - Authorization Code Flow)
  hiddenusername: true
- display: Certificate Thumbprint
  name: creds_certificate
  type: 9
  section: Connect
  advanced: true
  required: false
  displaypassword: Private Key
- additionalinfo: Used for certificate authentication. As appears in the "Certificates & secrets" page of the app.
  display: Certificate Thumbprint
  name: certificate_thumbprint
  type: 4
  section: Connect
  advanced: true
  required: false
  hidden: true
- additionalinfo: Used for certificate authentication. The private key of the registered certificate.
  name: private_key
  type: 14
  section: Connect
  advanced: true
  required: false
  display: Private Key
  hidden: true
- display: Use a self-deployed Azure Application
  name: self_deployed
  section: Connect
  required: false
  type: 8
  additionalinfo: Select this checkbox if you are using a self-deployed Azure application.
- display: Use Azure Managed Identities
  name: use_managed_identities
  type: 8
  additionalinfo: 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.
  section: Connect
  advanced: true
  required: false
- name: managed_identities_client_id
  type: 9
  section: Connect
  advanced: true
  required: false
  additionalinfo: The Managed Identities client ID for authentication - relevant only if the integration is running on Azure VM.
  displaypassword: Azure Managed Identities Client ID
  hiddenusername: true
- display: Azure AD endpoint
  name: azure_ad_endpoint
  type: 0
  section: Connect
  advanced: true
  required: false
  defaultvalue: https://login.microsoftonline.com
  additionalinfo: Use this option when required to customize the URL to the Entra ID endpoint. More information can be found here - https://xsoar.pan.dev/docs/reference/articles/microsoft-integrations---authentication#using-national-cloud
- display: Scope (Required for using Cortex XSOAR Azure app)
  name: scope
  type: 12
  section: Connect
  advanced: true
  required: false
  additionalinfo: A space-separated list of scopes that you want to consent to.
  defaultvalue: User.Read
- display: Trust any certificate (not secure)
  name: insecure
  type: 8
  section: Connect
  advanced: true
  required: false
- display: Use system proxy settings
  name: proxy
  type: 8
  section: Connect
  advanced: true
  required: false
- display: Application Secret (Deprecated)
  name: app_secret
  type: 4
  hidden: true
  section: Connect
  advanced: true
  required: false
description: 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.
display: Microsoft Graph API
name: Microsoft Graph API
script:
  commands:
  - arguments:
    - description: The resource in Microsoft Graph to refer.
      name: resource
      required: true
    - auto: PREDEFINED
      defaultValue: GET
      description: 'The HTTP method used for the request to Microsoft Graph. Possible values are: "GET", "POST", "DELETE", "PUT", or "PATCH".'
      name: http_method
      predefined:
      - GET
      - POST
      - DELETE
      - PUT
      - PATCH
    - auto: PREDEFINED
      defaultValue: v1.0
      description: 'The version of the Microsoft Graph API to use. Possible values are: "v1.0" or "beta". Default is "v1.0.'
      name: api_version
      predefined:
      - v1.0
      - beta
    - description: The request body (required for POST queries).
      name: request_body
    - description: OData system query options, e.g. $filter=startswith(givenName, 'J'). For more details see https://docs.microsoft.com/en-us/graph/query-parameters. It is recommended to use the $top query option to limit the result.
      name: odata
    - auto: PREDEFINED
      defaultValue: 'true'
      description: If "true" will populate the API response to the context data. Possible values are "true" or "false". Default is "true".
      name: populate_context
      predefined:
      - 'true'
      - 'false'
    - name: headers
      description: 'A comma-separated list of headers to send in the request, for example: ConsistencyLevel:eventual,User-Agent:MyApp/1.0.'
      isArray: true
    description: Run a Microsoft Graph API query.
    name: msgraph-api-request
  - description: Run this command to start the authorization process and follow the instructions in the command results.
    name: msgraph-api-auth-start
  - description: Run this command to complete the authorization process. Should be used after running the msgraph-auth-start command.
    name: msgraph-api-auth-complete
  - description: Tests connectivity to Microsoft.
    name: msgraph-api-test
  - description: Run this command if for some reason you need to rerun the authentication process.
    execution: false
    name: msgraph-api-auth-reset
    arguments: []
  - description: Generate the login URL used for Authorization code flow.
    name: msgraph-api-generate-login-url
    arguments: []
  dockerimage: demisto/crypto:1.0.0.10120494
  runonce: false
  script: '-'
  subtype: python3
  type: python
fromversion: 5.0.0
tests:
- Microsoft Graph API - Test