Connectors - List

Reference

Service:: Defender for Cloud

API Version:: 2020-01-01-preview

Cloud accounts connectors of a subscription

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Security/connectors?api-version=2020-01-01-preview

URI Parameters

Name In Required Type Description

Name	In	Required	Type	Description
subscriptionId	path	True	string	Azure subscription ID Regex pattern: `^[0-9A-Fa-f]{8}-([0-9A-Fa-f]{4}-){3}[0-9A-Fa-f]{12}$`
api-version	query	True	string	API version for the operation

subscriptionId

path

True

string

Azure subscription ID

Regex pattern: ^[0-9A-Fa-f]{8}-([0-9A-Fa-f]{4}-){3}[0-9A-Fa-f]{12}$

api-version

query

True

string

API version for the operation

Responses

Name	Type	Description
200 OK	ConnectorSettingList	OK
Other Status Codes	CloudError	Error response describing why the operation failed

Security

azure_auth

Azure Active Directory OAuth2 Flow

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
user_impersonation	impersonate your user account

Examples

Get all cloud accounts connectors of a subscription

Sample Request

GET https://management.azure.com/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/providers/Microsoft.Security/connectors?api-version=2020-01-01-preview

/** Samples for Connectors List. */
public final class Main {
    /*
     * x-ms-original-file: specification/security/resource-manager/Microsoft.Security/preview/2020-01-01-preview/examples/Connectors/GetListConnectorSubscription_example.json
     */
    /**
     * Sample code: Get all cloud accounts connectors of a subscription.
     *
     * @param manager Entry point to SecurityManager.
     */
    public static void getAllCloudAccountsConnectorsOfASubscription(
        com.azure.resourcemanager.security.SecurityManager manager) {
        manager.connectors().list(com.azure.core.util.Context.NONE);
    }
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

package armsecurity_test

import (
	"context"
	"log"

	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/security/armsecurity"
)

// Generated from example definition: https://github.com/Azure/azure-rest-api-specs/blob/b43974e07d3204c4b6f8396627f5430994a7f7c9/specification/security/resource-manager/Microsoft.Security/preview/2020-01-01-preview/examples/Connectors/GetListConnectorSubscription_example.json
func ExampleAccountConnectorsClient_NewListPager() {
	cred, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Fatalf("failed to obtain a credential: %v", err)
	}
	ctx := context.Background()
	clientFactory, err := armsecurity.NewClientFactory("<subscription-id>", cred, nil)
	if err != nil {
		log.Fatalf("failed to create client: %v", err)
	}
	pager := clientFactory.NewAccountConnectorsClient().NewListPager(nil)
	for pager.More() {
		page, err := pager.NextPage(ctx)
		if err != nil {
			log.Fatalf("failed to advance page: %v", err)
		}
		for _, v := range page.Value {
			// You could use page here. We use blank identifier for just demo purposes.
			_ = v
		}
		// If the HTTP response code is 200 as defined in example definition, your page structure would look as follows. Please pay attention that all the values in the output are fake values for just demo purposes.
		// page.ConnectorSettingList = armsecurity.ConnectorSettingList{
		// 	Value: []*armsecurity.ConnectorSetting{
		// 		{
		// 			Name: to.Ptr("aws_dev1"),
		// 			Type: to.Ptr("Microsoft.Security/connectors"),
		// 			ID: to.Ptr("/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/providers/Microsoft.Security/connectors/aws_dev1"),
		// 			Properties: &armsecurity.ConnectorSettingProperties{
		// 				AuthenticationDetails: &armsecurity.AwsCredsAuthenticationDetailsProperties{
		// 					AuthenticationProvisioningState: to.Ptr(armsecurity.AuthenticationProvisioningStateValid),
		// 					AuthenticationType: to.Ptr(armsecurity.AuthenticationTypeAwsCreds),
		// 					GrantedPermissions: []*armsecurity.PermissionProperty{
		// 						to.Ptr(armsecurity.PermissionPropertyAWSAWSSecurityHubReadOnlyAccess),
		// 						to.Ptr(armsecurity.PermissionPropertyAWSSecurityAudit),
		// 						to.Ptr(armsecurity.PermissionPropertyAWSAmazonSSMAutomationRole)},
		// 						AccountID: to.Ptr("922315681122"),
		// 						AwsAccessKeyID: to.Ptr(""),
		// 						AwsSecretAccessKey: to.Ptr(""),
		// 					},
		// 					HybridComputeSettings: &armsecurity.HybridComputeSettingsProperties{
		// 						AutoProvision: to.Ptr(armsecurity.AutoProvisionOn),
		// 						HybridComputeProvisioningState: to.Ptr(armsecurity.HybridComputeProvisioningStateValid),
		// 						ProxyServer: &armsecurity.ProxyServerProperties{
		// 							IP: to.Ptr("287.221.107.152"),
		// 							Port: to.Ptr("34"),
		// 						},
		// 						Region: to.Ptr("West US 2"),
		// 						ResourceGroupName: to.Ptr("AwsConnectorRG"),
		// 						ServicePrincipal: &armsecurity.ServicePrincipalProperties{
		// 							ApplicationID: to.Ptr("ad9bcd79-be9c-45ab-abd8-80ca1654a7d1"),
		// 						},
		// 					},
		// 				},
		// 			},
		// 			{
		// 				Name: to.Ptr("aws_dev2"),
		// 				Type: to.Ptr("Microsoft.Security/connectors"),
		// 				ID: to.Ptr("/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/providers/Microsoft.Security/connectors/aws_dev2"),
		// 				Properties: &armsecurity.ConnectorSettingProperties{
		// 					AuthenticationDetails: &armsecurity.AwAssumeRoleAuthenticationDetailsProperties{
		// 						AuthenticationProvisioningState: to.Ptr(armsecurity.AuthenticationProvisioningStateValid),
		// 						AuthenticationType: to.Ptr(armsecurity.AuthenticationTypeAwsAssumeRole),
		// 						GrantedPermissions: []*armsecurity.PermissionProperty{
		// 							to.Ptr(armsecurity.PermissionPropertyAWSAWSSecurityHubReadOnlyAccess),
		// 							to.Ptr(armsecurity.PermissionPropertyAWSSecurityAudit),
		// 							to.Ptr(armsecurity.PermissionPropertyAWSAmazonSSMAutomationRole)},
		// 							AccountID: to.Ptr("81231569658"),
		// 							AwsAssumeRoleArn: to.Ptr("arn:aws:iam::81231569658:role/AscConnector"),
		// 							AwsExternalID: to.Ptr("20ff7fc3-e762-44dd-bd96-b71116dcdc23"),
		// 						},
		// 						HybridComputeSettings: &armsecurity.HybridComputeSettingsProperties{
		// 							AutoProvision: to.Ptr(armsecurity.AutoProvisionOn),
		// 							HybridComputeProvisioningState: to.Ptr(armsecurity.HybridComputeProvisioningStateValid),
		// 							ProxyServer: &armsecurity.ProxyServerProperties{
		// 								IP: to.Ptr("167.210.187.160"),
		// 								Port: to.Ptr("34"),
		// 							},
		// 							Region: to.Ptr("West US 2"),
		// 							ResourceGroupName: to.Ptr("AwsConnectorRG"),
		// 							ServicePrincipal: &armsecurity.ServicePrincipalProperties{
		// 								ApplicationID: to.Ptr("ad9bcd79-be9c-45ab-abd8-80ca1654a7d1"),
		// 							},
		// 						},
		// 					},
		// 				},
		// 				{
		// 					Name: to.Ptr("gcp_dev"),
		// 					Type: to.Ptr("Microsoft.Security/connectors"),
		// 					ID: to.Ptr("/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/providers/Microsoft.Security/connectors/gcp_dev"),
		// 					Properties: &armsecurity.ConnectorSettingProperties{
		// 						AuthenticationDetails: &armsecurity.GcpCredentialsDetailsProperties{
		// 							AuthenticationProvisioningState: to.Ptr(armsecurity.AuthenticationProvisioningStateValid),
		// 							AuthenticationType: to.Ptr(armsecurity.AuthenticationTypeGcpCredentials),
		// 							GrantedPermissions: []*armsecurity.PermissionProperty{
		// 								to.Ptr(armsecurity.PermissionPropertyGCPSecurityCenterAdminViewer)},
		// 								Type: to.Ptr(""),
		// 								AuthProviderX509CertURL: to.Ptr(""),
		// 								AuthURI: to.Ptr(""),
		// 								ClientEmail: to.Ptr(""),
		// 								ClientID: to.Ptr(""),
		// 								ClientX509CertURL: to.Ptr(""),
		// 								OrganizationID: to.Ptr("AscDemoOrg"),
		// 								PrivateKey: to.Ptr(""),
		// 								PrivateKeyID: to.Ptr(""),
		// 								ProjectID: to.Ptr(""),
		// 								TokenURI: to.Ptr(""),
		// 							},
		// 							HybridComputeSettings: &armsecurity.HybridComputeSettingsProperties{
		// 								AutoProvision: to.Ptr(armsecurity.AutoProvisionOff),
		// 								HybridComputeProvisioningState: to.Ptr(armsecurity.HybridComputeProvisioningStateInvalid),
		// 								Region: to.Ptr(""),
		// 								ResourceGroupName: to.Ptr(""),
		// 							},
		// 						},
		// 				}},
		// 			}
	}
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

const { SecurityCenter } = require("@azure/arm-security");
const { DefaultAzureCredential } = require("@azure/identity");

/**
 * This sample demonstrates how to Cloud accounts connectors of a subscription
 *
 * @summary Cloud accounts connectors of a subscription
 * x-ms-original-file: specification/security/resource-manager/Microsoft.Security/preview/2020-01-01-preview/examples/Connectors/GetListConnectorSubscription_example.json
 */
async function getAllCloudAccountsConnectorsOfASubscription() {
  const subscriptionId =
    process.env["SECURITY_SUBSCRIPTION_ID"] || "20ff7fc3-e762-44dd-bd96-b71116dcdc23";
  const credential = new DefaultAzureCredential();
  const client = new SecurityCenter(credential, subscriptionId);
  const resArray = new Array();
  for await (let item of client.connectors.list()) {
    resArray.push(item);
  }
  console.log(resArray);
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

using System;
using System.Threading.Tasks;
using Azure;
using Azure.Core;
using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.Resources;
using Azure.ResourceManager.SecurityCenter;
using Azure.ResourceManager.SecurityCenter.Models;

// Generated from example definition: specification/security/resource-manager/Microsoft.Security/preview/2020-01-01-preview/examples/Connectors/GetListConnectorSubscription_example.json
// this example is just showing the usage of "Connectors_List" operation, for the dependent resources, they will have to be created separately.

// get your azure access token, for more details of how Azure SDK get your access token, please refer to https://learn.microsoft.com/en-us/dotnet/azure/sdk/authentication?tabs=command-line
TokenCredential cred = new DefaultAzureCredential();
// authenticate your client
ArmClient client = new ArmClient(cred);

// this example assumes you already have this SubscriptionResource created on azure
// for more information of creating SubscriptionResource, please refer to the document of SubscriptionResource
string subscriptionId = "20ff7fc3-e762-44dd-bd96-b71116dcdc23";
ResourceIdentifier subscriptionResourceId = SubscriptionResource.CreateResourceIdentifier(subscriptionId);
SubscriptionResource subscriptionResource = client.GetSubscriptionResource(subscriptionResourceId);

// get the collection of this SecurityCloudConnectorResource
SecurityCloudConnectorCollection collection = subscriptionResource.GetSecurityCloudConnectors();

// invoke the operation and iterate over the result
await foreach (SecurityCloudConnectorResource item in collection.GetAllAsync())
{
    // the variable item is a resource, you could call other operations on this instance as well
    // but just for demo, we get its data from this resource instance
    SecurityCloudConnectorData resourceData = item.Data;
    // for demo we just print out the id
    Console.WriteLine($"Succeeded on id: {resourceData.Id}");
}

Console.WriteLine($"Succeeded");

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

Sample Response

Status code:: 200

{
  "value": [
    {
      "id": "/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/providers/Microsoft.Security/connectors/aws_dev1",
      "name": "aws_dev1",
      "type": "Microsoft.Security/connectors",
      "properties": {
        "hybridComputeSettings": {
          "hybridComputeProvisioningState": "Valid",
          "autoProvision": "On",
          "resourceGroupName": "AwsConnectorRG",
          "region": "West US 2",
          "proxyServer": {
            "ip": "287.221.107.152",
            "port": "34"
          },
          "servicePrincipal": {
            "applicationId": "ad9bcd79-be9c-45ab-abd8-80ca1654a7d1"
          }
        },
        "authenticationDetails": {
          "authenticationProvisioningState": "Valid",
          "grantedPermissions": [
            "AWS::AWSSecurityHubReadOnlyAccess",
            "AWS::SecurityAudit",
            "AWS::AmazonSSMAutomationRole"
          ],
          "authenticationType": "awsCreds",
          "accountId": "922315681122",
          "awsAccessKeyId": "",
          "awsSecretAccessKey": ""
        }
      }
    },
    {
      "id": "/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/providers/Microsoft.Security/connectors/aws_dev2",
      "name": "aws_dev2",
      "type": "Microsoft.Security/connectors",
      "properties": {
        "hybridComputeSettings": {
          "hybridComputeProvisioningState": "Valid",
          "autoProvision": "On",
          "resourceGroupName": "AwsConnectorRG",
          "region": "West US 2",
          "proxyServer": {
            "ip": "167.210.187.160",
            "port": "34"
          },
          "servicePrincipal": {
            "applicationId": "ad9bcd79-be9c-45ab-abd8-80ca1654a7d1"
          }
        },
        "authenticationDetails": {
          "authenticationProvisioningState": "Valid",
          "grantedPermissions": [
            "AWS::AWSSecurityHubReadOnlyAccess",
            "AWS::SecurityAudit",
            "AWS::AmazonSSMAutomationRole"
          ],
          "authenticationType": "awsAssumeRole",
          "accountId": "81231569658",
          "awsAssumeRoleArn": "arn:aws:iam::81231569658:role/AscConnector",
          "awsExternalId": "20ff7fc3-e762-44dd-bd96-b71116dcdc23"
        }
      }
    },
    {
      "id": "/subscriptions/20ff7fc3-e762-44dd-bd96-b71116dcdc23/providers/Microsoft.Security/connectors/gcp_dev",
      "name": "gcp_dev",
      "type": "Microsoft.Security/connectors",
      "properties": {
        "hybridComputeSettings": {
          "hybridComputeProvisioningState": "Invalid",
          "autoProvision": "Off",
          "resourceGroupName": "",
          "region": "",
          "proxyServer": null,
          "servicePrincipal": null
        },
        "authenticationDetails": {
          "authenticationProvisioningState": "Valid",
          "grantedPermissions": [
            "GCP::Security Center Admin Viewer"
          ],
          "authenticationType": "gcpCredentials",
          "organizationId": "AscDemoOrg",
          "type": "",
          "projectId": "",
          "privateKeyId": "",
          "privateKey": "",
          "clientEmail": "",
          "clientId": "",
          "authUri": "",
          "tokenUri": "",
          "authProviderX509CertUrl": "",
          "clientX509CertUrl": ""
        }
      }
    }
  ]
}

Definitions

Name	Description
authenticationProvisioningState	State of the multi-cloud connector
autoProvision	Whether or not to automatically install Azure Arc (hybrid compute) agents on machines
AwAssumeRoleAuthenticationDetailsProperties	AWS cloud account connector based assume role, the role enables delegating access to your AWS resources. The role is composed of role Amazon Resource Name (ARN) and external ID. For more details, refer to Creating a Role to Delegate Permissions to an IAM User (write only)
AwsCredsAuthenticationDetailsProperties	AWS cloud account connector based credentials, the credentials is composed of access key ID and secret key, for more details, refer to Creating an IAM User in Your AWS Account (write only)
CloudError	Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.).
CloudErrorBody	The error detail.
ConnectorSetting	The connector setting
ConnectorSettingList	For a subscription, list of all cloud account connectors and their settings
ErrorAdditionalInfo	The resource management error additional info.
GcpCredentialsDetailsProperties	GCP cloud account connector based service to service credentials, the credentials are composed of the organization ID and a JSON API key (write only)
hybridComputeProvisioningState	State of the service principal and its secret
HybridComputeSettingsProperties	Settings for hybrid compute management
PermissionProperty	A permission detected in the cloud account.
ProxyServerProperties	For a non-Azure machine that is not connected directly to the internet, specify a proxy server that the non-Azure machine can use.
ServicePrincipalProperties	Details of the service principal.

authenticationProvisioningState

State of the multi-cloud connector

Name	Type	Description
Expired	string	the connection has expired
IncorrectPolicy	string	Incorrect policy of the connector
Invalid	string	Invalid connector
Valid	string	Valid connector

autoProvision

Whether or not to automatically install Azure Arc (hybrid compute) agents on machines

Name	Type	Description
Off	string	Do not install Azure Arc agent on the machines automatically
On	string	Install missing Azure Arc agents on machines automatically

AwAssumeRoleAuthenticationDetailsProperties

AWS cloud account connector based assume role, the role enables delegating access to your AWS resources. The role is composed of role Amazon Resource Name (ARN) and external ID. For more details, refer to Creating a Role to Delegate Permissions to an IAM User (write only)

Name	Type	Description
accountId	string	The ID of the cloud account
authenticationProvisioningState	authenticationProvisioningState	State of the multi-cloud connector
authenticationType	string: awsAssumeRole	Connect to your cloud account, for AWS use either account credentials or role-based authentication. For GCP use account organization credentials.
awsAssumeRoleArn	string	Assumed role ID is an identifier that you can use to create temporary security credentials.
awsExternalId	string	A unique identifier that is required when you assume a role in another account.
grantedPermissions	PermissionProperty[]	The permissions detected in the cloud account.

AwsCredsAuthenticationDetailsProperties

AWS cloud account connector based credentials, the credentials is composed of access key ID and secret key, for more details, refer to Creating an IAM User in Your AWS Account (write only)

Name	Type	Description
accountId	string	The ID of the cloud account
authenticationProvisioningState	authenticationProvisioningState	State of the multi-cloud connector
authenticationType	string: awsCreds	Connect to your cloud account, for AWS use either account credentials or role-based authentication. For GCP use account organization credentials.
awsAccessKeyId	string	Public key element of the AWS credential object (write only)
awsSecretAccessKey	string	Secret key element of the AWS credential object (write only)
grantedPermissions	PermissionProperty[]	The permissions detected in the cloud account.

CloudError

Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.).

Name	Type	Description
error.additionalInfo	ErrorAdditionalInfo[]	The error additional info.
error.code	string	The error code.
error.details	CloudErrorBody[]	The error details.
error.message	string	The error message.
error.target	string	The error target.

CloudErrorBody

The error detail.

Name	Type	Description
additionalInfo	ErrorAdditionalInfo[]	The error additional info.
code	string	The error code.
details	CloudErrorBody[]	The error details.
message	string	The error message.
target	string	The error target.

ConnectorSetting

The connector setting

Name	Type	Description
id	string	Resource Id
name	string	Resource name
properties.authenticationDetails	AuthenticationDetailsProperties: AwAssumeRoleAuthenticationDetailsProperties AwsCredsAuthenticationDetailsProperties GcpCredentialsDetailsProperties	Settings for authentication management, these settings are relevant only for the cloud connector.
properties.hybridComputeSettings	HybridComputeSettingsProperties	Settings for hybrid compute management. These settings are relevant only for Arc autoProvision (Hybrid Compute).
type	string	Resource type

ConnectorSettingList

For a subscription, list of all cloud account connectors and their settings

Name	Type	Description
nextLink	string	The URI to fetch the next page.
value	ConnectorSetting[]	List of all the cloud account connector settings

ErrorAdditionalInfo

The resource management error additional info.

Name	Type	Description
info	object	The additional info.
type	string	The additional info type.

GcpCredentialsDetailsProperties

GCP cloud account connector based service to service credentials, the credentials are composed of the organization ID and a JSON API key (write only)

Name	Type	Description
authProviderX509CertUrl	string	Auth provider x509 certificate URL field of the API key (write only)
authUri	string	Auth URI field of the API key (write only)
authenticationProvisioningState	authenticationProvisioningState	State of the multi-cloud connector
authenticationType	string: gcpCredentials	Connect to your cloud account, for AWS use either account credentials or role-based authentication. For GCP use account organization credentials.
clientEmail	string	Client email field of the API key (write only)
clientId	string	Client ID field of the API key (write only)
clientX509CertUrl	string	Client x509 certificate URL field of the API key (write only)
grantedPermissions	PermissionProperty[]	The permissions detected in the cloud account.
organizationId	string	The organization ID of the GCP cloud account
privateKey	string	Private key field of the API key (write only)
privateKeyId	string	Private key ID field of the API key (write only)
projectId	string	Project ID field of the API key (write only)
tokenUri	string	Token URI field of the API key (write only)
type	string	Type field of the API key (write only)

hybridComputeProvisioningState

State of the service principal and its secret

Name	Type	Description
Expired	string	the service principal details are expired
Invalid	string	Invalid service principal details.
Valid	string	Valid service principal details.

HybridComputeSettingsProperties

Settings for hybrid compute management

Name	Type	Description
autoProvision	autoProvision	Whether or not to automatically install Azure Arc (hybrid compute) agents on machines
hybridComputeProvisioningState	hybridComputeProvisioningState	State of the service principal and its secret
proxyServer	ProxyServerProperties	For a non-Azure machine that is not connected directly to the internet, specify a proxy server that the non-Azure machine can use.
region	string	The location where the metadata of machines will be stored
resourceGroupName	string	The name of the resource group where Arc (Hybrid Compute) connectors are connected.
servicePrincipal	ServicePrincipalProperties	An object to access resources that are secured by an Azure AD tenant.

PermissionProperty

A permission detected in the cloud account.

Name	Type	Description
AWS::AWSSecurityHubReadOnlyAccess	string	This permission provides read only access to AWS Security Hub resources.
AWS::AmazonSSMAutomationRole	string	The permission provides for EC2 Automation service to execute activities defined within Automation documents.
AWS::SecurityAudit	string	This permission grants access to read security configuration metadata.
GCP::Security Center Admin Viewer	string	This permission provides read only access to GCP Security Command Center.

ProxyServerProperties

For a non-Azure machine that is not connected directly to the internet, specify a proxy server that the non-Azure machine can use.

Name	Type	Description
ip	string	Proxy server IP
port	string	Proxy server port

ServicePrincipalProperties

Details of the service principal.

Name	Type	Description
applicationId	string	Application ID of service principal.
secret	string	A secret string that the application uses to prove its identity, also can be referred to as application password (write only).

Connectors - List

URI Parameters

Responses

Security

azure_auth

Scopes

Examples

Get all cloud accounts connectors of a subscription

Sample Request

Sample Response

Definitions

authenticationProvisioningState

autoProvision

AwAssumeRoleAuthenticationDetailsProperties

AwsCredsAuthenticationDetailsProperties

CloudError

CloudErrorBody

ConnectorSetting

ConnectorSettingList

ErrorAdditionalInfo

GcpCredentialsDetailsProperties

hybridComputeProvisioningState

HybridComputeSettingsProperties

PermissionProperty

ProxyServerProperties

ServicePrincipalProperties

Additional resources