Skip to content

Commit

Permalink
Microsoft support of national clouds - Microsoft Graph API (demisto#2…
Browse files Browse the repository at this point in the history 
…7742)

* CIAC-6401
Microsoft Graph API - GCC Support
  • Loading branch information
@kobymeir @xsoar-bot
kobymeir authored and xsoar-bot committed Oct 5, 2023
1 parent 96eb15b commit 9e25c14
Show file tree
Hide file tree
Showing 7 changed files with 86 additions and 48 deletions.
3 changes: 3 additions & 0 deletions Packs/MicrosoftGraphAPI/.pack-ignore
View file
@@ -1,2 +1,5 @@
[file:MicrosoftGraphAPI.yml]
ignore=IN124

[known_words]
GCC
22 changes: 11 additions & 11 deletions Packs/MicrosoftGraphAPI/Integrations/MicrosoftGraphAPI/MicrosoftGraphAPI.py
View file
@@ -1,10 +1,10 @@
import demistomock as demisto
from CommonServerPython import *
from CommonServerUserPython import *
from MicrosoftApiModule import * # noqa: E402

import urllib3
from typing import Any
from MicrosoftApiModule import * # noqa: E402

urllib3.disable_warnings()

Expand All @@ -17,13 +17,13 @@ def __init__(self,
tenant_id: str,
verify: bool,
proxy: bool,
azure_cloud: AzureCloud,
certificate_thumbprint: str | None = None,
private_key: str | None = None,
azure_ad_endpoint: str = 'https://login.microsoftonline.com',
managed_identities_client_id: str | None = None,
):
client_args = {
'base_url': 'https://graph.microsoft.com',
'base_url': azure_cloud.endpoints.microsoft_graph_resource_id.rstrip("/"),
'auth_id': app_id,
'scope': Scopes.graph,
'enc_key': app_secret,
Expand All @@ -33,16 +33,18 @@ def __init__(self,
'self_deployed': True,
'grant_type': CLIENT_CREDENTIALS,
'ok_codes': (200, 201, 204),
'azure_ad_endpoint': azure_ad_endpoint,
'azure_ad_endpoint': azure_cloud.endpoints.active_directory,
'private_key': private_key,
'certificate_thumbprint': certificate_thumbprint,
'managed_identities_client_id': managed_identities_client_id,
'managed_identities_resource_uri': Resources.graph,
'azure_cloud': azure_cloud,
'command_prefix': "msgraph-api",
}
if not (app_secret and tenant_id):
client_args['grant_type'] = DEVICE_CODE
client_args['token_retrieval_url'] = f'{azure_ad_endpoint}/organizations/oauth2/v2.0/token'
client_args['token_retrieval_url'] = urljoin(azure_cloud.endpoints.active_directory,
'/organizations/oauth2/v2.0/token')
client_args['scope'] = scope
self.ms_client = MicrosoftClient(**client_args) # type: ignore[arg-type]

Expand All @@ -56,16 +58,14 @@ def generic_request(
):
url_suffix = urljoin(api_version, resource)
if odata:
url_suffix += '?' + odata
url_suffix += f'?{odata}'
res = self.ms_client.http_request(
method=http_method,
url_suffix=url_suffix,
json_data=request_body,
resp_type='resp',
)
if res.content:
return res.json()
return None
return res.json() if res.content else None


def start_auth(client: MsGraphClient) -> CommandResults: # pragma: no cover
Expand Down Expand Up @@ -147,6 +147,7 @@ def main() -> None: # pragma: no cover
if params.get('scope'):
scope += params.get('scope')

azure_cloud = get_azure_cloud(params, 'MicrosoftGraphAPI')
app_secret = params.get('app_secret') or (params.get('credentials') or {}).get('password')
app_secret = app_secret if isinstance(app_secret, str) else ''
certificate_thumbprint = params.get('creds_certificate', {}).get('identifier') or params.get('certificate_thumbprint')
Expand All @@ -161,8 +162,7 @@ def main() -> None: # pragma: no cover
tenant_id=params.get('tenant_id'),
verify=not params.get('insecure', False),
proxy=params.get('proxy', False),
azure_ad_endpoint=params.get('azure_ad_endpoint',
'https://login.microsoftonline.com') or 'https://login.microsoftonline.com',
azure_cloud=azure_cloud,
certificate_thumbprint=certificate_thumbprint,
private_key=private_key,
managed_identities_client_id=managed_identities_client_id,
Expand Down
34 changes: 23 additions & 11 deletions Packs/MicrosoftGraphAPI/Integrations/MicrosoftGraphAPI/MicrosoftGraphAPI.yml
View file
Expand Up @@ -6,6 +6,22 @@ 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
Expand Down Expand Up @@ -62,18 +78,14 @@ configuration:
section: Connect
advanced: true
required: false
- additionalinfo: Azure AD endpoint associated with a national cloud.
defaultvalue: https://login.microsoftonline.com
- defaultvalue: https://login.microsoftonline.com
display: Azure AD endpoint
name: azure_ad_endpoint
type: 15
options:
- https://login.microsoftonline.com
- https://login.microsoftonline.us
- https://login.microsoftonline.de
- https://login.chinacloudapi.cn
section: Connect
required: false
type: 0
advanced: true
additionalinfo: Use this option when required to customize the URL to the Azure Active Directory endpoint. More information can be found here - https://xsoar.pan.dev/docs/reference/articles/microsoft-integrations---authentication#using-national-cloud
section: Connect
- display: Scope (Required for using Cortex XSOAR Azure app)
name: scope
type: 12
Expand Down Expand Up @@ -140,7 +152,7 @@ script:
- 'false'
description: Run a Microsoft Graph API query.
name: msgraph-api-request
- description: Run this command to start the autorization process and follow the instructions in the command results.
- 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
Expand All @@ -150,7 +162,7 @@ script:
execution: false
name: msgraph-api-auth-reset
arguments: []
dockerimage: demisto/crypto:1.0.0.66562
dockerimage: demisto/crypto:1.0.0.67955
runonce: false
script: '-'
subtype: python3
Expand Down
5 changes: 3 additions & 2 deletions Packs/MicrosoftGraphAPI/Integrations/MicrosoftGraphAPI/MicrosoftGraphAPI_test.py
View file
Expand Up @@ -4,6 +4,7 @@
import pytest

from MicrosoftGraphAPI import MsGraphClient, generic_command
from MicrosoftApiModule import AZURE_WORLDWIDE_CLOUD


def load_test_data(test_data_filename):
Expand All @@ -24,7 +25,7 @@ def client(requests_mock):
tenant_id='tenant_id',
verify=False,
proxy=False,

azure_cloud=AZURE_WORLDWIDE_CLOUD,
)


Expand Down Expand Up @@ -136,7 +137,7 @@ def test_test_module(mocker, params):
When:
- Running the test-module command.
Then:
- Ensure the command doesn't fails on ValueError (as for device-flow mode).
- Ensure the command doesn't fail on ValueError (as for device-flow mode).
"""
from MicrosoftGraphAPI import demisto, main, MicrosoftClient

Expand Down
61 changes: 38 additions & 23 deletions Packs/MicrosoftGraphAPI/Integrations/MicrosoftGraphAPI/README.md
View file
Expand Up @@ -51,21 +51,36 @@ The integration supports only Application permission type, and does not support
2. Search for Microsoft Graph API.
3. Click **Add instance** to create and configure a new integration instance.

| **Parameter** | **Description** | **Required** |
| --- | --- | --- |
| app_id | Application ID | False |
| scope | Scope (Required for using Cortex XSOAR Azure app) | False |
| app_secret | Application Secret (Required for using self deployed Azure app) | 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 |
| tenant_id | Tenant ID (Required for using self deployed Azure app) | 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 | False |
| insecure | Trust any certificate \(not secure\) | False |
| proxy | Use system proxy settings | False |

1. Click **Test** to validate the URLs, token, and connection.
| **Parameter** | **Description** | **Required** |
|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| Azure Cloud | See option table below. | False |
| app_id | Application ID | False |
| scope | Scope (Required for using Cortex XSOAR Azure app) | False |
| app_secret | Application Secret (Required for using self deployed Azure app) | 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 |
| tenant_id | Tenant ID (Required for using self deployed Azure app) | 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 |
| insecure | Trust any certificate \(not secure\) | False |
| proxy | 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.

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

## Commands
You can execute the command from the Cortex XSOAR CLI, as part of an automation, or in a playbook.
Expand Down Expand Up @@ -94,14 +109,14 @@ Run a Microsoft Graph API query.
`msgraph-api`
#### 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", 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. 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. Default is "true". | Optional |
| **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", 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. 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. Default is "true". | Optional |

#### Context Output

Expand Down
7 changes: 7 additions & 0 deletions Packs/MicrosoftGraphAPI/ReleaseNotes/1_1_25.md
View file
@@ -0,0 +1,7 @@

#### Integrations

##### Microsoft Graph API

- Added support for All Azure Cloud environments: Public, GCC, GCC-High, DoD, Germany, China.
- Updated the Docker image to: *demisto/crypto:1.0.0.67955*.
2 changes: 1 addition & 1 deletion Packs/MicrosoftGraphAPI/pack_metadata.json
View file
Expand Up @@ -2,7 +2,7 @@
"name": "Microsoft Graph API",
"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.",
"support": "xsoar",
"currentVersion": "1.1.24",
"currentVersion": "1.1.25",
"author": "Cortex XSOAR",
"url": "https://www.paloaltonetworks.com/cortex",
"email": "",
Expand Down

0 comments on commit 9e25c14

Please sign in to comment.