Partage via

[Déconseillé] Créer un connecteur sans code hérité pour Microsoft Sentinel

  • Article

Important

La collecte de journaux dans un grand nombre d’appliances et d’appareils est désormais prise en charge par le CEF (Common Event Format) via AMA, Syslog via AMA ou les journaux personnalisés via le connecteur de données AMA dans Microsoft Sentinel. Pour plus d’informations, consultez Rechercher votre connecteur de données Microsoft Sentinel.

Important

Il existe une version plus récente de la plateforme de connecteurs sans code (CCP). Pour plus d’informations concernant le nouveau connecteur sans code , consultez Créer un connecteur sans code (préversion).

Référencez ce document si vous devez gérer ou mettre à jour un connecteur de données en fonction de cette version héritée antérieure du CCP.

Le CCP fournit aux partenaires, aux utilisateurs expérimentés et aux développeurs la possibilité de créer des connecteurs personnalisés, de les connecter et d’ingérer des données sur Microsoft Sentinel. Les connecteurs créés par le biais de la CCP peuvent être déployés via une API, un modèle ARM ou une solution dans le hub de contenu de Microsoft Sentinel.

Les connecteurs créés à l’aide de la CCP sont entièrement SaaS, sans aucune exigence en matière d’installation de service, et comprennent également un monitoring de l’intégrité et une assistance complète fournis par Microsoft Sentinel.

Créez votre connecteur de données en définissant des configurations JSON, avec des paramètres qui déterminent l’apparence de la page du connecteur de données dans Microsoft Sentinel ainsi que des paramètres d’interrogation qui définissent le fonctionnement de la connexion.

Important

Cette version de la plateforme de connecteurs sans code (CCP) est en PRÉVERSION, mais elle est également considérée comme héritée. Les Conditions d’utilisation supplémentaires des préversions Microsoft Azure incluent des conditions légales supplémentaires qui s’appliquent aux fonctionnalités Azure en version bêta, en préversion ou pas encore disponibles dans la version en disponibilité générale.

Pour créer votre connecteur CCP et vous connecter à votre source de données à partir de Microsoft Sentinel, procédez comme suit :

  • Configurer l’interface utilisateur du connecteur
  • Configurer les paramètres d’interrogation du connecteur
  • Déployer votre connecteur dans votre espace de travail Microsoft Sentinel
  • Connecter Microsoft Sentinel à votre source de données et commencer à ingérer des données

Cet article décrit la syntaxe utilisée dans les configurations JSON de la plateforme CCP et les procédures de déploiement de votre connecteur via une API, un modèle ARM ou une solution Microsoft Sentinel.

Prérequis

Avant de générer un connecteur, nous vous recommandons de comprendre le comportement de votre source de données et la manière exacte dont Microsoft Sentinel devra se connecter.

Par exemple, vous devez connaître les différents types d’authentification, de pagination et de points de terminaison d’API nécessaires à l’établissement des connexions.

Créer un fichier config JSON de connecteur

Votre connecteur CCP personnalisé comporte deux sections JSON principales nécessaires au déploiement. Complétez ces zones pour définir la façon dont votre connecteur s’affiche sur le portail Azure et comment il connecte Microsoft Sentinel à votre source de données.

Ensuite, si vous déployez votre connecteur sans code via ARM, vous devrez inclure ces sections dans le modèle ARM pour les connecteurs de données.

Examinez les autres exemples de connecteurs de données CCP ou téléchargez l’exemple de modèle DataConnector_API_CCP_template.json (préversion).

Configurer l’interface utilisateur de votre connecteur

Cette section décrit les options de configuration disponibles pour personnaliser l’interface utilisateur de la page du connecteur de données.

L’illustration suivante montre la page d’un exemple de connecteur de données, où sont mis en évidence des numéros qui correspondent aux zones importantes de l’interface utilisateur :

Capture d’écran d’une page connecteur avec un échantillon de données.

  1. Titre. Titre affiché pour votre connecteur de données.
  2. Logo. Icône affichée pour votre connecteur de données. Sa personnalisation n’est possible que si le déploiement s’effectue dans le cadre d’une solution.
  3. Status. Indique si votre connecteur de données est connecté ou pas à Microsoft Sentinel.
  4. Graphiques de données. Affiche les requêtes pertinentes et la quantité de données ingérées au cours des deux dernières semaines.
  5. Onglet Instructions. Comporte une section Prérequis, avec une liste de validations minimales à opérer par l’utilisateur avant qu’il puisse activer le connecteur, et une section Instructions pour guider l’utilisateur dans l’activation du connecteur. Cette section peut inclure du texte, des boutons, des formulaires, des tableaux et d’autres widgets courants pour simplifier le processus.
  6. Onglet Étapes suivantes. Contient des informations utiles pour comprendre comment rechercher des données dans les journaux des événements, tels que des exemples de requêtes.

Voici les sections connectorUiConfig et la syntaxe nécessaire pour configurer l’interface utilisateur :

Nom de la propriété Type Description
availability {
"status": 1,
"isPreview": Booléen
}
status : 1 Indique que le connecteur est en disponibilité générale pour les clients.
isPreview Indique s’il faut inclure le suffixe (Preview) au nom du connecteur.
connectivityCriteria {
"type": SentinelKindsV2,
"value": APIPolling
}		 Objet qui définit comment vérifier si le connecteur est correctement défini. Utilisez les valeurs indiquées ici.
dataTypes dataTypes[] Liste de tous les types de données pour votre connecteur et requête pour récupérer l’heure du dernier événement pour chaque type de données.
descriptionMarkdown String Description du connecteur avec la possibilité d’ajouter le langage Markdown pour l’améliorer.
graphQueries graphQueries[] Requêtes qui présentent l’ingestion des données au cours des deux dernières semaines dans le volet Graphiques de données.

Fournissez soit une requête pour tous les types de données du connecteur de données, soit une requête différente pour chaque type de données.
graphQueriesTableName String Définit le nom de la table Log Analytics à partir de laquelle les données de vos requêtes sont extraites.

Le nom de la table peut être n’importe quelle chaîne, mais doit se terminer par _CL. Par exemple : TableName_CL
instructionsSteps instructionSteps[] Tableau de parties de widget qui expliquent comment installer le connecteur, affiché sous l’onglet Instructions.
métadonnées métadonnées Métadonnées affichées sous la description du connecteur.
autorisations permissions[] Informations affichées sous la section Prérequis de l’interface utilisateur qui indiquent les autorisations nécessaires pour activer ou désactiver le connecteur.
publisher String Texte figurant dans la section Fournisseur.
sampleQueries sampleQueries[] Exemples de requêtes permettant au client de comprendre comment rechercher les données dans le journal des événements, à afficher dans l’onglet Étapes suivantes.
title String Titre affiché dans la page du connecteur de données.

Il est compliqué d’assembler tous ces éléments. Utilisez l’outil de validation de l’expérience utilisateur de la page du connecteur pour tester les composants que vous assemblez.

dataTypes

Valeur de tableau Type Description
name String Description explicite de lastDataReceivedQuery, avec la prise en charge d’une variable.

Exemple : {{graphQueriesTableName}}
lastDataReceivedQuery String Requête KQL qui retourne une seule ligne avec l’heure à laquelle les données ont été reçues pour la dernière fois, ou pas de données en l’absence de données pertinentes.

Exemple : {{graphQueriesTableName}}\n | summarize Time = max(TimeGenerated)\n | where isnotempty(Time)

graphQueries

Définit une requête qui présente l’ingestion des données au cours des deux dernières semaines dans le volet Graphiques de données.

Fournissez soit une requête pour tous les types de données du connecteur de données, soit une requête différente pour chaque type de données.

Valeur de tableau Type Description
metricName String Nom explicite de votre graphique.

Exemple : Total data received
legend String Chaîne qui apparaît dans la légende à droite du graphique, y compris une référence à une variable.

Exemple : {{graphQueriesTableName}}
baseQuery String Requête qui filtre les événements pertinents, y compris une référence à une variable.

Par exemple : TableName_CL | where ProviderName == "myprovider"  ou {{graphQueriesTableName}}

instructionSteps

Cette section fournit des paramètres qui définissent l’ensemble des instructions qui s’affichent sur la page de votre connecteur de données dans Microsoft Sentinel.

Propriété de tableau Type Description
title String Facultatif. Définit un titre pour vos instructions.
description String Facultatif. Définit une description explicite de vos instructions.
innerSteps Array Optionnel. Définit un tableau d’étapes d’instructions internes.
instructions Tableau d’instructions Obligatoire. Définit un tableau d’instructions d’un type de paramètre spécifique.
bottomBorder Boolean Optionnel. Si true, ajoute une bordure inférieure à la zone des instructions sur la page du connecteur dans Microsoft Sentinel.
isComingSoon Boolean Optionnel. Si true, ajoute un titre Bientôt disponible sur la page du connecteur dans Microsoft Sentinel.

instructions

Affiche un groupe d’instructions, avec différentes options en tant que paramètres et la possibilité d’imbriquer davantage d’instructionsSteps dans des groupes.

Paramètre Propriété de tableau Description
APIKey APIKey Ajoute des espaces réservés au fichier config JSON de votre connecteur.
CopyableLabel CopyableLabel Affiche un champ de texte avec un bouton de copier à l’extrémité. Lorsque le bouton est sélectionné, la valeur du champ est copiée.
InfoMessage InfoMessage Définit un message d’information inlined.
InstructionStepsGroup InstructionStepsGroup Affiche un groupe d’instructions, éventuellement développé ou réductible, dans une section d’instructions distincte.
InstallAgent InstallAgent Affiche un lien vers d’autres parties d’Azure pour répondre à diverses exigences d’installation.

APIKey

Vous pouvez créer un modèle de fichier config JSON, avec des paramètres d’espace réservé, afin de le réutiliser pour plusieurs connecteurs ou même pour créer un connecteur avec des données que vous n’avez pas encore.

Pour créer des paramètres d’espace réservé, définissez un tableau supplémentaire nommé userRequestPlaceHoldersInput dans la section Instructions de votre fichier config JSON de la CCP en utilisant la syntaxe suivante :

"instructions": [
                {
                  "parameters": {
                    "enable": "true",
                    "userRequestPlaceHoldersInput": [
                      {
                        "displayText": "Organization Name",
                        "requestObjectKey": "apiEndpoint",
                        "placeHolderName": "{{placeHolder}}"
                      }
                    ]
                  },
                  "type": "APIKey"
                }
              ]

Le paramètre userRequestPlaceHoldersInput comprend les attributs suivants :

Name Type Description
DisplayText String Définit la valeur d’affichage de la zone de texte, qui est affichée à l’utilisateur lors de la connexion.
RequestObjectKey String Définit l’ID dans la section request de pollingConfig pour remplacer la valeur de l’espace réservé par la valeur fournie par l’utilisateur.

Si vous n’utilisez pas cet attribut, utilisez plutôt l’attribut PollingKeyPaths.
PollingKeyPaths String Définit un tableau d’objets JsonPath qui dirige l’appel d’API vers n’importe quel endroit du modèle, afin de remplacer une valeur d’espace réservé par une valeur utilisateur.

Exemple : "pollingKeyPaths":["$.request.queryParameters.test1"]

Si vous n’utilisez pas cet attribut, utilisez plutôt l’attribut RequestObjectKey.
PlaceHolderName String Définit le nom du paramètre d’espace réservé dans le fichier du modèle JSON. Il peut s’agir de n’importe quelle valeur unique, telle que {{placeHolder}}.

CopyableLabel

Exemple :

Capture d’écran d’un bouton de copie de valeur dans un champ.

Exemple de code :

{
    "parameters": {
        "fillWith": [
            "WorkspaceId",
            "PrimaryKey"
            ],
        "label": "Here are some values you'll need to proceed.",
        "value": "Workspace is {0} and PrimaryKey is {1}"
    },
    "type": "CopyableLabel"
}
Valeur de tableau Type Description
fillWith ENUM Optionnel. Tableau de variables d’environnement utilisé pour remplir un espace réservé. Séparez plusieurs espaces réservés par des virgules. Par exemple : {0},{1}

Valeurs prises en charge : workspaceId, workspaceName, primaryKey, MicrosoftAwsAccount, subscriptionId
label String Définit le texte de l’étiquette au-dessus d’une zone de texte.
value String Définit la valeur à présenter dans la zone de texte, prend en charge les espaces réservés.
rows Lignes Optionnel. Définit les lignes dans la zone de l’interface utilisateur. Par défaut, définissez sur 1.
wideLabel Boolean Optionnel. Détermine une étiquette large pour les chaînes longues. Par défaut, définissez sur false.

InfoMessage

Voici un exemple de message d’information inclus :

Capture d’un message d’information inlined.

À l’inverse, l’illustration suivante montre un message d’information non inlined :

Capture d’un message d’information qui n’est pas inlined.

Valeur de tableau Type Description
text String Définit le texte à afficher dans le message.
visible Boolean Détermine si le message s’affiche.
inline Boolean Détermine le mode d’affichage du message d’information.

- true : (Recommandé) Affiche le message d’information incorporé dans les instructions.
- false : Ajoute un arrière-plan bleu.

InstructionStepsGroup

Voici un exemple de groupe d’instructions pouvant être développé :

Capture d’écran d’un groupe d’instructions supplémentaire extensible.

Valeur de tableau Type Description
title String Définit le titre de l’étape d’instruction.
canCollapseAllSections Boolean Optionnel. Détermine si la section est un accordéon réductible ou non.
noFxPadding Boolean Optionnel. Si true, réduit le remplissage en hauteur pour gagner de l’espace.
expanded Boolean Optionnel. Si true, développé par défaut.

Pour obtenir un exemple détaillé, consultez le JSON de configuration du connecteur DNS Windows.

InstallAgent

Certains types InstallAgent apparaissent sous la forme d’un bouton, d’autres sous la forme d’un lien. Voici des exemples des deux :

Capture d’écran d’un lien ajouté en tant que bouton.

Capture d’écran d’un lien ajouté comme texte inlined

Valeurs de tableau Type Description
linkType ENUM Détermine le type de lien avec l’une des valeurs suivantes :

InstallAgentOnWindowsVirtualMachine
InstallAgentOnWindowsNonAzure
InstallAgentOnLinuxVirtualMachine
InstallAgentOnLinuxNonAzure
OpenSyslogSettings
OpenCustomLogsSettings
OpenWaf
OpenAzureFirewall OpenMicrosoftAzureMonitoring
OpenFrontDoors
OpenCdnProfile
AutomaticDeploymentCEF
OpenAzureInformationProtection
OpenAzureActivityLog
OpenIotPricingModel
OpenPolicyAssignment
OpenAllAssignmentsBlade
OpenCreateDataCollectionRule
policyDefinitionGuid Chaîne Obligatoire lorsque le linkType OpenPolicyAssignment est utilisé. Pour les connecteurs basés sur des stratégies, définit le GUID de la définition de stratégie intégrée.
assignMode ENUM Optionnel. Pour les connecteurs basés sur des stratégies, définit le mode d’attribution avec l’une des valeurs suivantes : Initiative, Policy
dataCollectionRuleType ENUM Optionnel. Pour les connecteurs DCR, définit le type de règle de collecte de données avec l’une des valeurs suivantes : SecurityEvent, ForwardEvent

metadata

Cette section fournit des métadonnées dans l’interface utilisateur du connecteur de données sous la zone Description.

Valeur de collection Type Description
kind String Définit le type de modèle ARM que vous êtes en train de créer. Utilisez toujours dataConnector.
source String Décrit votre source de données en utilisant la syntaxe suivante :
{
"kind":chaîne
"name":chaîne
}
author String Décrit l’auteur du connecteur de données en utilisant la syntaxe suivante :
{
"name":chaîne
}
support String Décrit la prise en charge fournie pour le connecteur de données en utilisant la syntaxe suivante :
{
"tier":chaîne,
"name":chaîne,
"email":chaîne,
"link":chaîne d’URL
}

autorisations

Valeur de tableau Type Description
customs String Décrit toutes les autorisations personnalisées requises pour votre connexion de données, dans la syntaxe suivante :
{
"name":string,
"description":chaîne
}

Exemple : La valeur de customs s’affiche dans la section Prérequis de Microsoft Sentinel avec une icône d’information bleue. Dans l’exemple GitHub, cela correspond à la ligne Clé de jeton personnel de l’API GitHub : Vous devez accéder au jeton personnel GitHub...
licences ENUM Définit les licences requises, avec l’une des valeurs suivantes : OfficeIRM, OfficeATP, Office365, AadP1P2, Mcas, Aatp, Mdatp, Mtp, IoT

Exemple : La valeur de licenses s’affiche dans Microsoft Sentinel comme suit : Licence : Azure AD Premium P2 obligatoire.
resourceProvider resourceProvider Décrit les conditions préalables pour votre ressource Azure.

Exemple : La valeur de resourceProvider s’affiche dans la section Prérequis de Microsoft Sentinel comme suit :
Espace de travail : L’autorisation d’accès en lecture et écriture est nécessaire.
Clés : Des autorisations d’accès en lecture sur les clés partagées pour l’espace de travail sont requises.
client tableau de valeurs ENUM
Exemple :

"tenant": [
"GlobalADmin",
"SecurityAdmin"
]
 Définit les autorisations requises, comme une ou plusieurs des valeurs suivantes : "GlobalAdmin", "SecurityAdmin", "SecurityReader", "InformationProtection"

Exemple : Affiche la valeur de tenant dans Microsoft Sentinel comme suit : Autorisations du locataire : Nécessite Global Administrator ou Security Administrator sur le locataire de l’espace de travail.

resourceProvider

valeur de sous-tableau Type Description
provider ENUM Décrit le fournisseur de ressources, avec l’une des valeurs suivantes :
- Microsoft.OperationalInsights/workspaces
- Microsoft.OperationalInsights/solutions
- Microsoft.OperationalInsights/workspaces/datasources
- microsoft.aadiam/diagnosticSettings
- Microsoft.OperationalInsights/workspaces/sharedKeys
- Microsoft.Authorization/policyAssignments
providerDisplayName String Élément de liste sous Prérequis qui affiche un « x » rouge ou une coche verte lorsque les requiredPermissions sont validées dans la page du connecteur. Par exemple, "Workspace"
permissionsDisplayText String Affiche du texte pour les autorisations Lecture, Écriture ou Lecture et écriture qui doivent correspondre aux valeurs configurées dans requiredPermissions
requiredPermissions {
"action":Booléen,
"delete":Booléen,
"read":Booléen,
"write":Boolean
}		 Décrit les autorisations minimales nécessaires pour le connecteur.
scope ENUM Décrit l’étendue du connecteur de données avec l’une des valeurs suivantes : "Subscription", "ResourceGroup", "Workspace"

sampleQueries

valeur de tableau Type Description
description String Description explicite de l’exemple de requête.

Exemple : Top 10 vulnerabilities detected
requête String Exemple de requête utilisé pour extraire les données du type de données.

Exemple : {{graphQueriesTableName}}\n | sort by TimeGenerated\n | take 10

Pour définir un lien inclus en utilisant Markdown, servez-vous de l’exemple suivant. Ici, un lien est fourni dans la description d’une instruction :

{
   "title": "",
   "description": "Make sure to configure the machine's security according to your organization's security policy\n\n\n[Learn more >](https://aka.ms/SecureCEF)"
}

Pour définir un lien comme modèle ARM, utilisez l’exemple suivant comme guide :

{
   "title": "Azure Resource Manager (ARM) template",
   "description": "1. Click the **Deploy to Azure** button below.\n\n\t[![Deploy To Azure](https://aka.ms/deploytoazurebutton)]({URL to custom ARM template})"
}

Valider l’expérience utilisateur de la page du connecteur de données

Suivez ces étapes pour afficher et valider l’expérience utilisateur du connecteur.

  1. L’utilitaire de test est accessible via l’URL https://aka.ms/sentineldataconnectorvalidateurl
  2. Accédez à Microsoft Sentinel -> Connecteurs de données
  3. Cliquez sur le bouton « importer » et sélectionnez un fichier JSON qui contient uniquement la section connectorUiConfig de votre connecteur de données.

Pour plus d’informations sur cet outil de validation, consultez les instructions Générer le connecteur dans notre guide de génération GitHub.

Notes

Sachant que le paramètre d’instruction APIKey est propre au connecteur sans code, supprimez provisoirement cette section avant d’utiliser l’outil de validation pour éviter un échec de celui-ci.

Configurer les paramètres d’interrogation de votre connecteur

Cette section décrit la configuration de l’interrogation des données de votre source de données pour un connecteur de données sans code.

Le code suivant illustre la syntaxe de la section pollingConfig du fichier config de la CCP.

"pollingConfig": {
    "auth": {
    },
    "request": {
    },
    "response": {
    },
    "paging": {
    }
 }

La section pollingConfig comprend les propriétés suivantes :

Name Type Description
auth String Décrit les propriétés d’authentification pour l’interrogation des données. Pour plus d’informations, consultez Configuration d’auth.
auth.authType String Mandatory. Définit le type d’authentification, imbriqué à l’intérieur de l’objet auth, avec l’une des valeurs suivantes : Basic, APIKey, OAuth2
requête JSON imbriqué Mandatory. Décrit la charge utile de la requête pour interroger les données, telles que le point de terminaison de l’API. Pour plus d’informations, consultez Configuration de request.
response JSON imbriqué Mandatory. Décrit l’objet de réponse et le message imbriqué renvoyés par l’API lors de l’interrogation des données. Pour plus d’informations, consultez Configuration de response.
paging JSON imbriqué Optionnel. Décrit la charge utile de la pagination lors de l’interrogation des données. Pour plus d’informations, consultez Configuration de paging.

Pour plus d’informations, consultez Exemple de code pollingConfig.

Configuration d’auth

La section auth de la configuration pollingConfig comprend les paramètres suivants, selon le type défini dans l’élément authType :

Paramètres authType de base

Nom Type Description
Nom d’utilisateur String Mandatory. Définit le nom d’utilisateur.
Mot de passe String Mandatory. Définit le mot de passe de l’utilisateur.

Paramètres authType pour APIKey

Name Type Description
APIKeyName Chaîne facultatif. Définit le nom de votre clé API, avec l’une des valeurs suivantes :

- XAuthToken
- Authorization
IsAPIKeyInPostPayload Boolean Détermine l’emplacement où votre clé API est définie.

True : La clé API est définie dans la charge utile de la requête POST
False : La clé API est définie dans l’en-tête
APIKeyIdentifier Chaîne Facultatif. Définit le nom de l’identificateur pour la clé API.

Par exemple, lorsque l’autorisation est définie sur "Authorization": "token <secret>", ce paramètre est défini comme suit : {APIKeyIdentifier: “token”})

Paramètres d’authType OAuth2

La plateforme du connecteur sans code prend en charge l’octroi de code d’autorisation OAuth 2.0.

Le type d’autorisation du code d’autorisation est utilisé par les clients confidentiels et publics pour échanger un code d’autorisation pour un jeton d’accès.

Une fois que l’utilisateur est retourné au client via l’URL de redirection, l’application obtient le code d’autorisation de l’URL et l’utilise pour demander un jeton d’accès.

Nom Type Description
FlowName String Mandatory. Définit un flux OAuth2.

Valeur prise en charge : AuthCode- nécessite un flux d’autorisation
AccessToken String Facultatif. Définit un jeton d’accès OAuth2, pertinent lorsque le jeton d’accès n’expire pas.
AccessTokenPrepend String Facultatif. Définit un jeton d’accès OAuth2 ajouté. La valeur par défaut est Bearer.
RefreshToken String Obligatoire pour les types d’authentification OAuth2. Définit le jeton d’actualisation OAuth2.
TokenEndpoint String Obligatoire pour les types d’authentification OAuth2. Définit le point de terminaison du service de jeton OAuth2.
AuthorizationEndpoint String Facultatif. Définit le point de terminaison du service d’autorisation OAuth2. Utilisé uniquement lors de l’intégration ou lors du renouvellement d’un jeton d’actualisation.
RedirectionEndpoint String Facultatif. Définit un point de terminaison de redirection lors de l’intégration.
AccessTokenExpirationDateTimeInUtc String Facultatif. Définit une date/heure d’expiration du jeton d’accès au format UTC. Pertinent lorsque le jeton d’accès n’expire pas, et a donc une date importante en UTC, ou lorsque le jeton d’accès a une date d’expiration importante.
RefreshTokenExpirationDateTimeInUtc String Obligatoire pour les types d’authentification OAuth2. Définit la date d’expiration du jeton d’actualisation au format UTC.
TokenEndpointHeaders Dictionnaire<chaîne, objet> facultatif. Définit les en-têtes lors de l’appel d’un point de terminaison de service de jeton OAuth2.

Définissez une chaîne au format dictionary<string, string> sérialisé : {'<attr_name>': '<val>', '<attr_name>': '<val>'... }
AuthorizationEndpointHeaders Dictionnaire<chaîne, objet> facultatif. Définit les en-têtes lors de l’appel d’un point de terminaison de service d’autorisation OAuth2. Utilisé uniquement lors de l’intégration ou lors du renouvellement d’un jeton d’actualisation.

Définissez une chaîne au format dictionary<string, object> sérialisé : {'<attr_name>': <serialized val>, '<attr_name>': <serialized val>, ... }
AuthorizationEndpointQueryParameters Dictionnaire<chaîne, objet> facultatif. Définit les paramètres de requête lors de l’appel d’un point de terminaison de service d’autorisation OAuth2. Utilisé uniquement lors de l’intégration ou lors du renouvellement d’un jeton d’actualisation.

Définissez une chaîne au format dictionary<string, object> sérialisé : {'<attr_name>': <serialized val>, '<attr_name>': <serialized val>, ... }
TokenEndpointQueryParameters Dictionnaire<chaîne, objet> facultatif. Définissez les paramètres de requête lors de l’appel du point de terminaison du service de jeton OAuth2.

Définissez une chaîne au format dictionary<string, object> sérialisé : {'<attr_name>': <serialized val>, '<attr_name>': <serialized val>, ... }
IsTokenEndpointPostPayloadJson Booléen facultatif. La valeur par défaut est false. Détermine si les paramètres de requête sont au format JSON et définis dans la charge utile POST de requête.
IsClientSecretInHeader Booléen facultatif. La valeur par défaut est false. Détermine si les valeurs client_id et client_secret valeurs sont définies dans l’en-tête, comme dans le schéma d’authentification de base, et non pas dans la charge utile POST.
RefreshTokenLifetimeinSecAttributeName String Facultatif. Définit le nom d’attribut de la réponse du point de terminaison de jeton, en spécifiant la durée de vie du jeton d’actualisation, en secondes.
IsJwtBearerFlow Booléen facultatif. La valeur par défaut est false. Détermine si vous utilisez JWT.
JwtHeaderInJson Dictionnaire<chaîne, objet> facultatif. Définissez les en-têtes JWT au format JSON.

Définissez une chaîne au format dictionary<string, object> sérialisé : {'<attr_name>': <serialized val>, '<attr_name>': <serialized val>...}
JwtClaimsInJson Dictionnaire<chaîne, objet> facultatif. Définit les revendications JWT au format JSON.

Définissez une chaîne au format dictionary<string, object> sérialisé : {'<attr_name>': <serialized val>, '<attr_name>': <serialized val>, ...}
JwtPem String Facultatif. Définit une clé secrète, au format PEM Pkcs1 : '-----BEGIN RSA PRIVATE KEY-----\r\n{privatekey}\r\n-----END RSA PRIVATE KEY-----\r\n'

Veillez à conserver le code '\r\n' en lieu sûr.
RequestTimeoutInSeconds Integer Optionnel. Détermine le délai d’expiration en secondes lors de l’appel du point de terminaison de service de jeton. La valeur par défaut est de 180 secondes

Voici un exemple de la façon dont une configuration OAuth2 peut se présenter :

"pollingConfig": {
    "auth": {
        "authType": "OAuth2",
        "authorizationEndpoint": "https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&prompt=consent",
        "redirectionEndpoint": "https://portal.azure.com/TokenAuthorize",
        "tokenEndpoint": "https://oauth2.googleapis.com/token",
        "authorizationEndpointQueryParameters": {},
        "tokenEndpointHeaders": {
            "Accept": "application/json"
        },
        "TokenEndpointQueryParameters": {},
        "isClientSecretInHeader": false,
        "scope": "https://www.googleapis.com/auth/admin.reports.audit.readonly",
        "grantType": "authorization_code",
        "contentType": "application/x-www-form-urlencoded",
        "FlowName": "AuthCode"
    },

Paramètres authType pour Session

Name Type Description
QueryParameters Dictionnaire<chaîne, objet> facultatif. Liste des paramètres de requête, au format dictionary<string, string> sérialisé :

{'<attr_name>': '<val>', '<attr_name>': '<val>'... }
IsPostPayloadJson Boolean Optionnel. Détermine si les paramètres de requête sont au format JSON.
En-têtes Dictionnaire<chaîne, objet> facultatif. Définit l’en-tête utilisé lors de l’appel du point de terminaison pour obtenir l’ID de session et lors de l’appel de l’API du point de terminaison.

Définissez la chaîne au format dictionary<string, string> sérialisé : {'<attr_name>': '<val>', '<attr_name>': '<val>'... }.
SessionTimeoutInMinutes Chaîne Facultatif. Définit un délai d’expiration de session, en minutes.
SessionIdName Chaîne Facultatif. Définit un nom d’ID pour la session.
SessionLoginRequestUri Chaîne Facultatif. Définit une URI de requête de connexion de session.

Configuration de requête

La section request de la configuration pollingConfig comprend les paramètres suivants :

Name Type Description
apiEndpoint String Mandatory. Définit le point de terminaison à partir duquel extraire les données.
httpMethod String Mandatory. Définit la méthode d’API : GET ou POST
queryTimeFormat Chaîne ou UnixTimestamp ou UnixTimestampInMills Mandatory. Définit le format utilisé pour définir l’heure de la requête.

Cette valeur peut être une chaîne ou être au format UnixTimestamp ou UnixTimestampInMills pour indiquer l’heure de début et de fin de la requête au format UnixTimestamp.
startTimeAttributeName Chaîne Facultatif. Définit le nom de l’attribut qui définit l’heure de début de la requête.
endTimeAttributeName Chaîne Facultatif. Définit le nom de l’attribut qui définit l’heure de fin de la requête.
queryTimeIntervalAttributeName String Optionnel. Définit le nom de l’attribut qui définit l’intervalle de temps de la requête.
queryTimeIntervalDelimiter Chaîne Facultatif. Définit le délimiteur de l’intervalle de temps de la requête.
queryWindowInMin Integer Optionnel. Définit la fenêtre de requête disponible, en minutes.

Valeur minimale : 5
queryParameters Dictionnaire<chaîne, objet> facultatif. Définit les paramètres transmis dans la requête dans le chemin d’accès eventsJsonPaths.

Définissez la chaîne au format dictionary<string, string> sérialisé : {'<attr_name>': '<val>', '<attr_name>': '<val>'... }.
queryParametersTemplate String Optionnel. Définit le modèle de paramètres de requête à utiliser lors de la transmission de paramètres de requête dans des scénarios avancés.

Par exemple : "queryParametersTemplate": "{'cid': 1234567, 'cmd': 'reporting', 'format': 'siem', 'data': { 'from': '{_QueryWindowStartTime}', 'to': '{_QueryWindowEndTime}'}, '{_APIKeyName}': '{_APIKey}'}"

{_QueryWindowStartTime} et {_QueryWindowEndTime} sont uniquement pris en charge dans les paramètres de requête queryParameters et queryParametersTemplate.

{_APIKeyName} et {_APIKey} sont uniquement pris en charge dans le paramètre de requête queryParametersTemplate.
isPostPayloadJson Boolean Optionnel. Détermine si la charge utile POST est au format JSON.
rateLimitQPS Double Optionnel. Définit le nombre d’appels ou de requêtes autorisés en une seconde.
timeoutInSeconds Integer Optionnel. Définit le délai d’expiration de la requête, en secondes.
retryCount Integer Optionnel. Définit le nombre de nouvelles tentatives de la requête, le cas échéant.
headers Dictionnaire<chaîne, objet> facultatif. Définit la valeur d’en-tête de demande au format dictionary<string, object> sérialisé : {'<attr_name>': '<serialized val>', '<attr_name>': '<serialized val>'... }.

Configuration de réponse

La section response de la configuration pollingConfig comprend les paramètres suivants :

Name Type Description
eventsJsonPaths Liste de chaînes Mandatory. Définit le chemin d’accès au message dans la réponse JSON.

Une expression de chemin d’accès JSON spécifie un chemin d’accès à un élément, ou à un ensemble d’éléments, dans une structure JSON
successStatusJsonPath Chaîne Facultatif. Définit le chemin d’accès au message de réussite dans la réponse JSON.
successStatusValue Chaîne Facultatif. Définit le chemin d’accès vers la valeur du message de réussite dans la réponse JSON.
isGzipCompressed Boolean Optionnel. Détermine si la réponse est compressée dans un fichier gzip.

Le code suivant illustre un exemple de la valeur eventsJsonPaths pour un message de niveau supérieur :

"eventsJsonPaths": [
              "$"
            ]

Configuration de pagination

La section paging de la configuration pollingConfig comprend les paramètres suivants :

Name Type Description
pagingType String Mandatory. Détermine le type de pagination à utiliser dans les résultats, avec l’une des valeurs suivantes : None, LinkHeader, NextPageToken, NextPageUrl, Offset
linkHeaderTokenJsonPath Chaîne Facultatif. Définit le chemin d’accès JSON vers l’en-tête de lien dans le JSON de la réponse, si le LinkHeader n’est pas défini dans l’en-tête de la réponse.
nextPageTokenJsonPath Chaîne Facultatif. Définit le chemin d’accès à un jeton JSON de page suivante.
hasNextFlagJsonPath Chaîne Facultatif. Définit le chemin d’accès vers l’attribut de l’indicateur HasNextPage.
nextPageTokenResponseHeader Chaîne Facultatif. Définit le nom de l’en-tête du jeton de page suivante dans la réponse.
nextPageParaName Chaîne Facultatif. Détermine le nom de la page suivante dans la requête.
nextPageRequestHeader Chaîne Facultatif. Détermine le nom de l’en-tête de la page suivante dans la requête.
nextPageUrl Chaîne Facultatif. Détermine l’URL de la page suivante, si elle est différente de l’URL de la requête initiale.
nextPageUrlQueryParameters Chaîne Facultatif. Détermine les paramètres de requête de l’URL de la page suivante s’ils sont différents de ceux de l’URL de la requête initiale.

Définissez la chaîne au format dictionary<string, object> sérialisé : {'<attr_name>': <val>, '<attr_name>': <val>... }.
offsetParaName Chaîne Facultatif. Définit le nom du paramètre de décalage.
pageSizeParaName Chaîne Facultatif. Définit le nom du paramètre de taille de page.
PageSize Integer Définit la taille de la pagination.

Exemple de code pollingConfig

Le code suivant illustre un exemple de la section pollingConfig du fichier config de la CCP :

"pollingConfig": {
    "auth": {
        "authType": "APIKey",
        "APIKeyIdentifier": "token",
        "APIKeyName": "Authorization"
     },
     "request": {
        "apiEndpoint": "https://api.github.com/../{{placeHolder1}}/audit-log",
        "rateLimitQPS": 50,
        "queryWindowInMin": 15,
        "httpMethod": "Get",
        "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
        "retryCount": 2,
        "timeoutInSeconds": 60,
        "headers": {
           "Accept": "application/json",
           "User-Agent": "Scuba"
        },
        "queryParameters": {
           "phrase": "created:{_QueryWindowStartTime}..{_QueryWindowEndTime}"
        }
     },
     "paging": {
        "pagingType": "LinkHeader",
        "pageSizeParaName": "per_page"
     },
     "response": {
        "eventsJsonPaths": [
          "$"
        ]
     }
}

Déployer votre connecteur dans Microsoft Sentinel et démarrer l’ingestion des données

Après avoir créé votre fichier config JSON, comprenant à la fois l’interface utilisateur et la configuration d’interrogation, déployez votre connecteur dans votre espace de travail Microsoft Sentinel.

  1. Utilisez l’une des options suivantes pour déployer votre connecteur de données.

    Conseil

    L’avantage du déploiement par le biais d’un modèle Azure Resource Manager (ARM) est que plusieurs valeurs sont intégrées au modèle et que vous n’avez pas besoin de les définir manuellement dans un appel d’API.

    Encapsulez vos collections de configurations JSON dans un modèle ARM pour déployer votre connecteur. Pour garantir un déploiement de votre connecteur de données dans l’espace de travail approprié, veillez à définir ce dernier dans le modèle ARM ou à le sélectionner au moment de déployer le modèle ARM.

    1. Préparez un fichier JSON de modèle ARM pour votre connecteur. Par exemple, consultez les fichiers JSON de modèle ARM suivants :

    2. Dans le portail Azure, recherchez Déployer un modèle personnalisé.

    3. Sur la page Déploiement personnalisé, sélectionnez Créer votre propre modèle dans l’éditeur>Charger un fichier. Naviguez jusqu’à votre modèle ARM local et sélectionnez-le, puis enregistrez vos modifications.

    4. Sélectionnez votre abonnement et votre groupe de ressources, puis entrez dans l’espace de travail Log Analytics où vous souhaitez déployer votre connecteur personnalisé.

    5. Sélectionnez Vérifier + créer pour déployer votre connecteur personnalisé sur Microsoft Sentinel.

    6. Dans Microsoft Sentinel, accédez à la page Connecteurs de données, puis recherchez votre nouveau connecteur. Configurez-le pour démarrer l’ingestion des données.

    Pour plus d’informations, consultez Déployer un modèle local dans la documentation d’Azure Resource Manager.

  2. Configurez votre connecteur de données pour connecter votre source de données et commencer à ingérer des données dans Microsoft Sentinel. Vous pouvez vous connecter à votre source de données soit via le portail, comme avec les connecteurs de données prêts à l’emploi, soit via une API.

    Lorsque vous utilisez le portail Azure pour vous connecter, les données utilisateur sont envoyées automatiquement. Lorsque vous vous connectez via l’API, vous devez envoyer les paramètres d’authentification pertinents dans l’appel d’API.

    Dans la page de votre connecteur de données Microsoft Sentinel, suivez les instructions que vous avez fournies pour vous connecter au connecteur de données.

    La page du connecteur de données dans Microsoft Sentinel est contrôlée par la configuration InstructionSteps dans l’élément connectorUiConfig du fichier config JSON de la plateforme CCP. Si vous rencontrez des problèmes avec la connexion à l’interface utilisateur, assurez-vous que vous disposez de la bonne configuration pour votre type d’authentification.

  3. Dans Microsoft Sentinel, accédez à la page Journaux et vérifiez que les journaux de votre source de données arrivent dans votre espace de travail.

Si vous ne voyez pas de données affluer dans Microsoft Sentinel, consultez la documentation et les ressources de dépannage de votre source de données, vérifiez les détails de la configuration et vérifiez la connectivité. Pour plus d’informations, consultez Superviser l’intégrité de vos connecteurs de données.

Déconnecter votre connecteur

Si vous n’avez plus besoin des données de votre connecteur, déconnectez-le pour arrêter le flux de données.

Appliquez l'une des méthodes suivantes :

  • Portail Azure : Dans la page de votre connecteur de données Microsoft Sentinel, sélectionnez Déconnexion.

  • API : Utilisez l’API DISCONNECT pour envoyer un appel PUT avec un corps vide à l’URL suivante :

    https://management.azure.com /subscriptions/{{SUB}}/resourceGroups/{{RG}}/providers/Microsoft.OperationalInsights/workspaces/{{WS-NAME}}/providers/Microsoft.SecurityInsights/dataConnectors/{{Connector_Id}}/disconnect?api-version=2021-03-01-preview

Étapes suivantes

Si vous ne l’avez pas encore fait, partagez votre nouveau connecteur de données sans code avec la communauté Microsoft Sentinel ! Créez une solution pour votre connecteur de données et partagez-la sur le marketplace de Microsoft Sentinel.

Pour plus d'informations, consultez la rubrique