Creación de un conector sin código heredado para Microsoft Sentinel

  • Artículo

Importante

Hay una versión más reciente de la plataforma de conector sin código (CCP). Para más información sobre la nueva CCP, consulte Creación de un conector sin código (versión preliminar).

Haga referencia a este documento si necesita mantener o actualizar un conector de datos basado en esta versión anterior y heredada de la CCP.

La CCP proporciona a asociados, usuarios avanzados y desarrolladores la capacidad de crear conectores personalizados, conectarlos e ingerir datos en Microsoft Sentinel. Los conectores creados mediante la CCP se pueden implementar a través de la API, de una plantilla de ARM o como una solución en el centro de contenido de Microsoft Sentinel.

Los conectores creados con la CCP están totalmente habilitados para SaaS, sin ningún requisito para las instalaciones de servicio, y también incluyen seguimiento de estado y soporte técnico completo por parte de Microsoft Sentinel.

Cree su conector de datos mediante la definición de valores de configuración JSON, teniendo en cuenta valores de configuración del aspecto de la página del conector de datos en Microsoft Sentinel y unos valores de sondeo que definen cómo funciona la conexión.

Importante

Esta versión de la plataforma de conector sin código (CCP) está en versión preliminar, pero también se considera heredada. En la página Términos de uso complementarios para las Versiones preliminares de Microsoft Azure se incluyen términos legales adicionales que se aplican a las características de Azure que se encuentran en versión beta, versión preliminar o que todavía no se han publicado para su disponibilidad general.

Siga los siguientes pasos para crear el conector CCP y conectarse al origen de datos desde Microsoft Sentinel:

  • Configuración de la interfaz de usuario del conector
  • Configuración de los valores de sondeo del conector
  • Implementación del conector en el área de trabajo de Microsoft Sentinel
  • Conecte Microsoft Sentinel al origen de datos y empiece a ingerir datos

En este artículo se describe la sintaxis que se usa en los valores de configuración JSON de CCP y los procedimientos para implementar el conector mediante la API, una plantilla de ARM o una solución de Microsoft Sentinel.

Requisitos previos

Antes de crear un conector, es recomendable que comprenda cómo se comporta el origen de datos y la manera exacta en la que Microsoft Sentinel tiene que conectarse.

Por ejemplo, tendrá que aprender los tipos de autenticación, paginación y puntos de conexión de API necesarios para las conexiones correctas.

Creación de un archivo de configuración JSON del conector

El conector CCP personalizado tiene dos secciones JSON principales necesarias para la implementación. Rellene estas áreas para definir cómo se muestra el conector en Azure Portal y cómo conecta Microsoft Sentinel al origen de datos.

A continuación, si implementa el conector sin código a través de ARM, encapsulará estas secciones en la plantilla de ARM de los conectores de datos.

Revise otros conectores de datos CCP como ejemplos o descargue la plantilla de ejemplo DataConnector_API_CCP_template.json (versión preliminar).

Configuración de la interfaz de usuario del conector

En esta sección se describen las opciones de configuración disponibles para personalizar la interfaz de usuario de la página del conector de datos.

En la imagen siguiente se muestra una página de ejemplo del conector de datos, resaltada con números que corresponden a áreas configurables de la interfaz de usuario:

Screenshot of a sample data connector page.

  1. Título. Título que se muestra para el conector de datos.
  2. Logotipo. Icono que se muestra para el conector de datos. La personalización de este elemento solo es posible cuando se implementa como parte de una solución.
  3. Status. Indica si el conector de datos está conectado o no a Microsoft Sentinel.
  4. Gráficos de datos. Muestra las consultas pertinentes y la cantidad de datos ingeridos en las últimas dos semanas.
  5. Pestaña Instrucciones. Incluye una sección de Requisitos previos, con una lista de validaciones mínimas antes de que el usuario pueda habilitar el conector; también cuenta con una sección de Instrucciones que tiene una lista de instrucciones para guiar al usuario en el proceso de habilitación del conector. Esta sección puede incluir texto, botones, formularios, tablas y otros widgets comunes para simplificar el proceso.
  6. Pestaña Pasos siguientes. Incluye información útil para comprender cómo buscar datos, entre otros consultas de ejemplo, en los registros de eventos.

Estas son las connectorUiConfig secciones y la sintaxis necesarias para configurar la interfaz de usuario:

Nombre de propiedad Type Descripción
disponibilidad {
"status": 1,
"isPreview": (booleana)
}
status: 1 indica que el conector está disponible de forma general para los clientes.
isPreview: indica si se debe incluir el sufijo (versión preliminar) en el nombre del conector.
connectivityCriteria {
"type": SentinelKindsV2,
"value": APIPolling
}		 Objeto que define cómo comprobar si el conector está definido correctamente. Use los valores indicados aquí.
dataTypes dataTypes[] Una lista de todos los tipos de datos para el conector y una consulta para capturar la hora del último evento para cada tipo de datos.
descriptionMarkdown String Descripción del conector con la capacidad de agregar lenguaje Markdown para mejorarlo.
graphQueries graphQueries[] Consultas que presentan la ingesta de datos en las últimas dos semanas en el panel Gráficos de datos.

Proporcione una consulta para todos los tipos de datos del conector de datos o una consulta diferente para cada tipo de datos.
graphQueriesTableName String Define el nombre de la tabla de Log Analytics de la que se extraen los datos de las consultas.

El nombre de la tabla puede ser cualquier cadena, pero debe terminar en _CL. Por ejemplo: TableName_CL
instructionsSteps instructionSteps[] Matriz de elementos de widget que explican cómo instalar el conector, que se muestra en la pestaña Instrucciones.
metadata metadata Metadatos que se muestran en la descripción del conector.
permisos permissions[] Es la información que se muestra en la sección Requisitos previos de la interfaz de usuario, que a su vez muestra los permisos necesarios para habilitar o deshabilitar el conector.
publisher String Este es el texto que se muestra en la sección Proveedor.
sampleQueries sampleQueries[] Consultas de ejemplo para que el cliente entienda cómo buscar los datos en el registro de eventos, que se mostrarán en la pestaña Pasos siguientes.
title String Título que se muestra en la página del conector de datos.

Unir todas estas piezas es complicado. Use la herramienta de validación de la experiencia de usuario de la página del conector para probar los componentes que ha reunido.

dataTypes

Valor Array Tipo Descripción
name String Descripción significativa de lastDataReceivedQuery, incluida la compatibilidad con una variable.

Ejemplo: {{graphQueriesTableName}}
lastDataReceivedQuery String Consulta de KQL que, o devuelve una fila e indica la última vez que se recibieron los datos, o no devuelve ningún dato si no hay datos pertinentes.

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

graphQueries

Consultas que presentan la ingesta de datos en las últimas dos semanas en el panel Gráficos de datos.

Proporcione una consulta para todos los tipos de datos del conector de datos o una consulta diferente para cada tipo de datos.

Valor Array Tipo Descripción
metricName String Escriba un nombre significativo para el gráfico.

Ejemplo: Total data received
legend String Cadena que aparece en la leyenda a la derecha del gráfico, incluida una referencia de variable.

Ejemplo: {{graphQueriesTableName}}
baseQuery String Consulta que filtra los eventos relevantes, incluida una referencia de variable.

Por ejemplo, TableName_CL | where ProviderName == "myprovider" o {{graphQueriesTableName}}.

instructionSteps

En esta sección se proporcionan parámetros que definen el conjunto de instrucciones que aparecen en la página del conector de datos en Microsoft Sentinel.

Propiedad Array Tipo Descripción
title String Opcional. Define un título para las instrucciones.
description String Opcional. Define una descripción significativa para las instrucciones.
innerSteps Array Opcional. Define una matriz de pasos de instrucciones internas.
instructions Matriz de instrucciones Necesario. Define una matriz de instrucciones de un tipo de parámetro específico.
bottomBorder Boolean Opcional. Cuando se produce true, agrega un borde inferior al área de instrucciones de la página del conector en Microsoft Sentinel
isComingSoon Boolean Opcional. Cuando se produce true, agrega un título en el que pone Próximamente, en la página del conector en Microsoft Sentinel

instrucciones

Muestra un grupo de instrucciones, con varias opciones como parámetros y la capacidad de anidar más instrucciones y pasos en grupos.

Parámetro Propiedad Array Descripción
APIKey APIKey Permite agregar marcadores de posición al archivo de configuración JSON del conector.
CopyableLabel CopyableLabel Muestra un campo de texto con el botón Copiar al final. Cuando se pulsa el botón, se copia el valor del campo.
InfoMessage InfoMessage Define un mensaje de información insertado.
InstructionStepsGroup InstructionStepsGroup Muestra un grupo de instrucciones, opcionalmente expandidas o contraídas, en una sección de instrucciones independiente.
InstallAgent InstallAgent Muestra un vínculo a otras partes de Azure para cumplir varios requisitos de instalación.

APIKey

Es posible que desee crear una plantilla de archivo de configuración JSON, con parámetros de marcadores de posición, para reutilizar en varios conectores o incluso para crear un conector con datos que no tiene actualmente.

Para crear parámetros de marcador de posición, defina una matriz adicional denominada userRequestPlaceHoldersInput en la sección Instrucciones del archivo de configuración JSON de CCP, con la sintaxis siguiente:

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

El parámetro userRequestPlaceHoldersInput incluye los siguientes atributos:

Nombre Tipo Descripción
DisplayText String Define el valor de presentación del cuadro de texto, que se muestra al usuario al conectarse.
RequestObjectKey String Define el id. en la sección de solicitud del elemento pollingConfig para sustituir el valor del marcador de posición con el valor que haya proporcionado el usuario.

Si no usa este atributo, use el atributo PollingKeyPaths en su lugar.
PollingKeyPaths String Define una matriz de objetos JsonPath, que dirige la llamada API a cualquier parte de la plantilla para reemplazar un valor de marcador de posición por un valor de usuario.

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

Si no usa este atributo, use el atributo RequestObjectKey en su lugar.
PlaceHolderName String Define el nombre del parámetro de marcador de posición en el archivo de plantilla JSON. Puede ser cualquier valor único, como {{placeHolder}}.

CopyableLabel

Ejemplo:

Screenshot of a copy value button in a field.

Código de ejemplo:

{
    "parameters": {
        "fillWith": [
            "WorkspaceId",
            "PrimaryKey"
            ],
        "label": "Here are some values you'll need to proceed.",
        "value": "Workspace is {0} and PrimaryKey is {1}"
    },
    "type": "CopyableLabel"
}
Valor Array Tipo Descripción
fillWith ENUM Opcional. Matriz de variables de entorno utilizadas para rellenar un marcador de posición. Separe varios marcadores de posición con comas. Por ejemplo: {0},{1}

Valores admitidos: workspaceId, workspaceName, primaryKey, MicrosoftAwsAccount, subscriptionId
label String Define el texto de la etiqueta encima de un cuadro de texto.
value String Define el valor que se debe presentar en el cuadro de texto y admite marcadores de posición.
rows Filas Opcional. Define las filas del área de interfaz de usuario. De manera predeterminada, se establece en 1.
wideLabel Boolean Opcional. Determina una etiqueta ancha para cadenas largas. De manera predeterminada, se establece en false.

InfoMessage

Este es un ejemplo de un mensaje de información insertado:

Screenshot of an inline information message.

Por el contrario, la imagen siguiente muestra un mensaje de información no insertado:

Screenshot of a non-inline information message.

Valor Array Tipo Descripción
text String Texto que se va a mostrar en el mensaje.
visible Boolean Determina si se muestra el mensaje.
inline Boolean Determina cómo se muestra el mensaje de información.

- true: (Recomendado) Muestra el mensaje de información insertado en las instrucciones.
- false: agrega un fondo azul.

InstructionStepsGroup

Este es un ejemplo de un grupo de instrucciones expandible:

Screenshot of an expandable, extra instruction group.

Valor Array Tipo Descripción
title String Define el título del paso de instrucción.
canCollapseAllSections Boolean Opcional. Determina si la sección es una instancia de Accordion contraíble o no contraíble.
noFxPadding Boolean Opcional. Si se produce true, reduce el relleno de altura para ahorrar espacio.
expanded Boolean Opcional. Si se produce true, se muestra como expandido de manera predeterminada.

Para obtener un ejemplo detallado, consulte el archivo JSON de configuración para el conector DNS de Windows.

InstallAgent

Algunos tipos InstallAgent aparecen como un botón; otros aparecerán como un vínculo. Estos son ejemplos de ambos:

Screenshot of a link added as a button.

Screenshot of a link added as inline text.

Valores Array Tipo Descripción
linkType ENUM Determina el tipo de vínculo, como uno de los valores siguientes:

InstallAgentOnWindowsVirtualMachine
InstallAgentOnWindowsNonAzure
InstallAgentOnLinuxVirtualMachine
InstallAgentOnLinuxNonAzure
OpenSyslogSettings
OpenCustomLogsSettings
OpenWaf
OpenAzureFirewall OpenMicrosoftAzureMonitoring
OpenFrontDoors
OpenCdnProfile
AutomaticDeploymentCEF
OpenAzureInformationProtection
OpenAzureActivityLog
OpenIotPricingModel
OpenPolicyAssignment
OpenAllAssignmentsBlade
OpenCreateDataCollectionRule
policyDefinitionGuid String Se requiere al usar el tipo de vínculo OpenPolicyAssignment. Para los conectores basados en directivas, define el GUID de la definición de directiva integrada.
assignMode ENUM Opcional. En el caso de los conectores basados en directivas, define el modo de asignación, como uno de los siguientes valores: Initiative, Policy
dataCollectionRuleType ENUM Opcional. Para los conectores basados en DCR, define el tipo de regla de recopilación de datos como uno de los siguientes: SecurityEvent, ForwardEvent

metadata

En esta sección se proporcionan metadatos en la interfaz de usuario del conector de datos en el área Descripción.

Valor Collection Tipo Descripción
kind String Define el tipo de plantilla de ARM que está creando. Use siempre dataConnector.
source String Describe el origen de datos, con la sintaxis siguiente:
{
"kind":cadena
"name":cadena
}
author String Describe el autor del conector de datos, con la sintaxis siguiente:
{
"name":cadena
}
support String Describa la compatibilidad proporcionada para el conector de datos mediante la sintaxis siguiente:
{
"tier":cadena,
"name":cadena,
"email":cadena,
"link":cadena de dirección URL
}

permisos

Valor Array Tipo Descripción
customs String Describe los permisos personalizados necesarios para la conexión de datos, en la sintaxis siguiente:
{
"name":string,
"description":cadena
}

Ejemplo: el valor customs se muestra en la sección Requisitos previos de Microsoft Sentinel con un icono informativo azul. En el ejemplo de GitHub, esto se correlaciona con la línea Clave de token personal de la API de GitHub: necesita acceso al token personal de GitHub...
licenses ENUM Define las licencias necesarias, como uno de los valores siguientes: OfficeIRM,OfficeATP, Office365, AadP1P2, Mcas, Aatp, Mdatp, Mtp, IoT

Ejemplo: el valor licenses (licencias) se muestra así en Microsoft Sentinel: Licencia: requiere Azure AD Premium P2
resourceProvider resourceProvider Describe los requisitos previos para el recurso de Azure.

Ejemplo: el valor resourceProvider se muestra así en la sección Requisitos previos de Microsoft Sentinel:
Área de trabajo: se requiere permiso de escritura y de escritura.
Debe tener permisos de lectura para las claves compartidas del área de trabajo.
tenant matriz de valores ENUM
Ejemplo:

"tenant": [
"GlobalADmin",
"SecurityAdmin"
]
 Define los permisos necesarios, como uno o varios de los valores siguientes: "GlobalAdmin", "SecurityAdmin", "SecurityReader", "InformationProtection"

Ejemplo: el valor tenant se muestra así en Microsoft Sentinel: Permisos de inquilino: requiere Global Administrator o Security Administrator en el área de trabajo del inquilino.

resourceProvider

valor de submatriz Tipo Descripción
proveedor ENUM Describe el proveedor de recursos, con uno de los valores siguientes:
- Microsoft.OperationalInsights/workspaces
- Microsoft.OperationalInsights/solutions
- Microsoft.OperationalInsights/workspaces/datasources
- microsoft.aadiam/diagnosticSettings
- Microsoft.OperationalInsights/workspaces/sharedKeys
- Microsoft.Authorization/policyAssignments
providerDisplayName String Es un elemento de lista en Requisitos previos que mostrará una "x" roja o una marca de verificación verde cuando se validen los elementos requisitosPermissions en la página del conector. Ejemplo, "Workspace"
permissionsDisplayText String Muestra texto para permisos de lectura, escritura o lectura y escritura que deben corresponder a los valores configurados en requiredPermissions.
requiredPermissions {
"action":Boolean,
"delete":Boolean,
"read":Boolean,
"write":Boolean
}		 Describe los permisos mínimos necesarios para el conector.
scope ENUM Describe el ámbito del conector de datos, como uno de los valores siguientes: "Subscription", "ResourceGroup", "Workspace"

sampleQueries

valor array Tipo Descripción
description String Descripción significativa de la consulta de ejemplo.

Ejemplo: Top 10 vulnerabilities detected
consulta String Consulta de ejemplo usada para capturar los datos del tipo de datos.

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

Para definir un vínculo insertado mediante Markdown, use el ejemplo siguiente. Aquí se proporciona un vínculo en una descripción de instrucciones:

{
   "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)"
}

Para definir un vínculo como una plantilla de ARM, use el ejemplo siguiente como guía:

{
   "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})"
}

Validación de la experiencia de usuario de la página del conector de datos

Siga estos pasos para representar y validar la experiencia de usuario del conector.

  1. Esta dirección URL puede acceder a la utilidad de prueba: https://aka.ms/sentineldataconnectorvalidateurl
  2. Vaya a Microsoft Sentinel -> Conectores de datos.
  3. Haga clic en el botón "Importar" y seleccione un archivo JSON que solo contenga la sección connectorUiConfig del conector de datos.

Para obtener más información sobre esta herramienta de validación, consulte las instrucciones de Compilación del conector en la guía de compilación de GitHub.

Nota

Dado que el parámetro de instrucción APIKey es específico del conector sin código, quite temporalmente esta sección para usar la herramienta de validación o se producirá un error.

Configuración de los valores de sondeo del conector

En esta sección se describe la configuración de cómo se sondean los datos del origen de datos para un conector de datos sin código.

El código siguiente muestra la sintaxis de la sección pollingConfig del archivo de configuración de CCP.

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

La sección pollingConfig se incluye los datos siguientes:

Nombre Tipo Descripción
auth String Describe las propiedades de autenticación para sondear los datos. Para más información, consulte Configuración de autenticación.
auth.authType String Mandatory. Define el tipo de autenticación, anidado dentro del objeto auth, como uno de los siguientes valores: Basic, APIKey, OAuth2
Solicitud JSON anidado Mandatory. Describe la carga de solicitud para sondear los datos, como el punto de conexión de la API. Para más información, consulte configuración de solicitud.
response JSON anidado Mandatory. Describe el objeto de respuesta y el mensaje anidado devueltos por la API al sondear los datos. Para más información, consulte configuración de respuesta.
paging JSON anidado Opcional. Describe la carga de paginación al sondear los datos. Para más información, consulte Configuración de paginación.

Para más información, consulte Código pollingConfig de ejemplo.

configuración de autenticación

La sección auth de la configuración pollingConfig incluye los parámetros siguientes, dependiendo del tipo definido en el elemento authType:

Parámetros authType básicos

Nombre Tipo Descripción
Nombre de usuario String Mandatory. Define el nombre de usuario.
Contraseña String Mandatory. Define la contraseña de usuario.

Parámetros authType de APIKey

Nombre Tipo Descripción
APIKeyName String Opcional. Define el nombre de la clave de API, como uno de los valores siguientes:

- XAuthToken
- Authorization
IsAPIKeyInPostPayload Boolean Determina dónde se define la clave de API.

True: La clave de API se define en la carga de la solicitud POST
False: la clave de API se define en el encabezado
APIKeyIdentifier String Opcional. Define el nombre del identificador de la clave de API.

Por ejemplo, cuando la autorización se define como "Authorization": "token <secret>", este parámetro se define como: {APIKeyIdentifier: “token”})

Parámetros authType de OAuth2

Codeless Connector Platform admite la concesión de código de autorización de OAuth 2.0.

Los clientes confidenciales y públicos usan el tipo de concesión de código de autorización para intercambiar un código de autorización para un token de acceso.

Después de que el usuario vuelva al cliente a través de la dirección URL de redireccionamiento, la aplicación obtendrá el código de autorización de la dirección URL y lo usará para solicitar un token de acceso.

Nombre Tipo Descripción
FlowName String Mandatory. Define un flujo de OAuth2.

Valor admitido: AuthCode - requiere un flujo de autorización
AccessToken String Opcional. Define un token de acceso de OAuth2, pertinente cuando el token de acceso no expira.
AccessTokenPrepend String Opcional. Define un token de acceso de OAuth2 antepuesto. El valor predeterminado es Bearer.
RefreshToken Cadena Obligatorio para los tipos de autenticación de OAuth2. Define el token de actualización de OAuth2.
TokenEndpoint Cadena Obligatorio para los tipos de autenticación de OAuth2. Define el punto de conexión de servicio de token de OAuth2.
AuthorizationEndpoint String Opcional. Define el punto de conexión del servicio de autorización de OAuth2. Solo se usa durante la incorporación o al renovar un token de actualización.
RedirectionEndpoint String Opcional. Define un punto de conexión de redireccionamiento durante la incorporación.
AccessTokenExpirationDateTimeInUtc String Opcional. Define una fecha y hora de expiración del token de acceso, en formato UTC. Pertinente para cuando el token de acceso no expira y, por tanto, tiene un datetime grande en UTC o cuando el token de acceso tiene un datetime de expiración grande.
RefreshTokenExpirationDateTimeInUtc String Obligatorio para los tipos de autenticación de OAuth2. Define el datetime de expiración del token de actualización en formato UTC.
TokenEndpointHeaders Diccionario<string, objeto> Opcional. Define los encabezados al llamar a un punto de conexión de servicio de token de OAuth2.

Defina una cadena en el formato dictionary<string, string> serializado: {'<attr_name>': '<val>', '<attr_name>': '<val>'... }
AuthorizationEndpointHeaders Diccionario<string, objeto> Opcional. Define los encabezados al llamar a un punto de conexión de servicio de autorización de OAuth2. Solo se usa durante la incorporación o al renovar un token de actualización.

Defina una cadena en el formato dictionary<string, object> serializado: {'<attr_name>': <serialized val>, '<attr_name>': <serialized val>, ... }
AuthorizationEndpointQueryParameters Diccionario<string, objeto> Opcional. Define los parámetros de consulta al llamar a un punto de conexión de servicio de autorización de OAuth2. Solo se usa durante la incorporación o al renovar un token de actualización.

Defina una cadena en el formato dictionary<string, object> serializado: {'<attr_name>': <serialized val>, '<attr_name>': <serialized val>, ... }
TokenEndpointQueryParameters Diccionario<string, objeto> Opcional. Defina los parámetros de consulta al llamar al punto de conexión de servicio de token de OAuth2.

Defina una cadena en el formato dictionary<string, object> serializado: {'<attr_name>': <serialized val>, '<attr_name>': <serialized val>, ... }
IsTokenEndpointPostPayloadJson Boolean Opcional, el valor predeterminado es falso. Determina si los parámetros de consulta están en formato JSON y establecidos en la carga POST de la solicitud.
IsClientSecretInHeader Boolean Opcional, el valor predeterminado es falso. Determina si los valores client_id y client_secret se definen en el encabezado, como se hace en el esquema de autenticación básica, en lugar de en la carga POST.
RefreshTokenLifetimeinSecAttributeName String Opcional. Define el nombre del atributo de la respuesta del punto de conexión del token, lo que especifica la duración del token de actualización, en segundos.
IsJwtBearerFlow Boolean Opcional, el valor predeterminado es falso. Determina si usa JWT.
JwtHeaderInJson Diccionario<string, objeto> Opcional. Defina los encabezados de JWT en formato JSON.

Defina una cadena en el formato dictionary<string, object> serializado: {'<attr_name>': <serialized val>, '<attr_name>': <serialized val>...}
JwtClaimsInJson Diccionario<string, objeto> Opcional. Define las notificaciones de JWT en formato JSON.

Defina una cadena en el formato dictionary<string, object> serializado: {'<attr_name>': <serialized val>, '<attr_name>': <serialized val>, ...}
JwtPem String Opcional. Define una clave secreta, en formato PEM Pkcs1: '-----BEGIN RSA PRIVATE KEY-----\r\n{privatekey}\r\n-----END RSA PRIVATE KEY-----\r\n'

Asegúrese de mantener el código '\r\n' en su lugar.
RequestTimeoutInSeconds Entero Opcional. Determina el tiempo de espera en segundos al llamar al punto de conexión de servicio de token. El valor predeterminado es 180 segundos.

Este es un ejemplo del aspecto que podría tener una configuración de OAuth2:

"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"
    },

Parámetros authType de la sesión

Nombre Tipo Descripción
QueryParameters Diccionario<string, objeto> Opcional. Lista de parámetros de consulta, en formato serializado dictionary<string, string>:

{'<attr_name>': '<val>', '<attr_name>': '<val>'... }
IsPostPayloadJson Boolean Opcional. Determina si los parámetros de consulta están en formato JSON.
Encabezados Diccionario<string, objeto> Opcional. Define el encabezado utilizado al llamar al punto de conexión para obtener el id. de sesión y al llamar a la API del punto de conexión.

Defina la cadena en el formato serializado dictionary<string, string>: {'<attr_name>': '<val>', '<attr_name>': '<val>'... }
SessionTimeoutInMinutes String Opcional. Define un tiempo de espera de la sesión, en minutos.
SessionIdName String Opcional. Define un nombre de id. para la sesión.
SessionLoginRequestUri String Opcional. Define un URI de solicitud de inicio de sesión.

Configuración de la solicitud

La sección request de la configuración pollingConfig incluye los parámetros siguientes:

Nombre Tipo Descripción
apiEndpoint String Mandatory. Define el punto de conexión del que se extraerán los datos.
httpMethod String Mandatory. Define el método de la API: GET o POST
queryTimeFormat String, o UnixTimestamp o UnixTimestampInMills Mandatory. Define el formato utilizado para definir la hora de consulta.

Este valor puede ser una cadena o en formato UnixTimestamp o UnixTimestampInMills, para indicar la hora de inicio y finalización de la consulta en UnixTimestamp.
startTimeAttributeName String Opcional. Define el nombre del atributo que define la hora de inicio de la consulta.
endTimeAttributeName String Opcional. Define el nombre del atributo que define la hora de finalización de la consulta.
queryTimeIntervalAttributeName String Opcional. Define el nombre del atributo que define el intervalo de tiempo de la consulta.
queryTimeIntervalDelimiter String Opcional. Define el delimitador del intervalo de tiempo de la consulta.
queryWindowInMin Entero Opcional. Define la ventana de consulta disponible, en minutos.

Valor mínimo: 5
queryParameters Diccionario<string, objeto> Opcional. Define los parámetros pasados en la consulta en la ruta de acceso eventsJsonPaths.

Defina la cadena en el formato dictionary<string, string> serializado: {'<attr_name>': '<val>', '<attr_name>': '<val>'... }.
queryParametersTemplate String Opcional. Define la plantilla de parámetros de consulta que se usará al pasar parámetros de consulta en escenarios avanzados.

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

{_QueryWindowStartTime} y {_QueryWindowEndTime} solo se admiten en los parámetros de solicitud queryParameters y queryParametersTemplate.

{_APIKeyName} y {_APIKey} solo se admiten en el parámetro de solicitud queryParametersTemplate.
isPostPayloadJson Boolean Opcional. Determina si la carga de POST está en formato JSON.
rateLimitQPS Double Opcional. Define el número de llamadas o consultas permitidas en un segundo.
timeoutInSeconds Entero Opcional. Define el tiempo de espera de la solicitud, en segundos.
retryCount Entero Opcional. Define el número de reintentos de solicitud, en caso de que se necesiten.
headers Diccionario<string, objeto> Opcional. Define el valor del encabezado de solicitud, en formato serializado dictionary<string, object>: {'<attr_name>': '<serialized val>', '<attr_name>': '<serialized val>'... }

Configuración de respuesta

La sección response de la configuración pollingConfig incluye los parámetros siguientes:

Nombre Tipo Descripción
eventsJsonPaths Lista de cadenas Mandatory. Define la ruta de acceso al mensaje en el JSON de respuesta.

Una expresión de ruta de acceso JSON especifica una ruta de acceso a un elemento o un conjunto de elementos en una estructura JSON
successStatusJsonPath String Opcional. Define la ruta de acceso al mensaje de operación correcta en el JSON de respuesta.
successStatusValue String Opcional. Define la ruta de acceso al valor del mensaje de operación correcta en el JSON de respuesta
isGzipCompressed Boolean Opcional. Determina si la respuesta se comprime en un archivo gzip.

En el código siguiente se muestra un ejemplo del valor eventsJsonPaths para un mensaje de nivel superior:

"eventsJsonPaths": [
              "$"
            ]

Configuración de paginación

La sección paging de la configuración pollingConfig incluye los parámetros siguientes:

Nombre Tipo Descripción
pagingType String Mandatory. Determina el tipo de paginación que se usará en los resultados, como uno de los valores siguientes: None, LinkHeader, NextPageToken, NextPageUrl, Offset
linkHeaderTokenJsonPath String Opcional. Define la ruta de acceso JSON para vincular el encabezado en el JSON de respuesta, si el LinkHeader no está definido en el encabezado de respuesta.
nextPageTokenJsonPath String Opcional. Define la ruta de acceso a un JSON de token de la página siguiente.
hasNextFlagJsonPath String Opcional. Define la ruta de acceso al atributo de marca HasNextPage.
nextPageTokenResponseHeader String Opcional. Define el encabezado de token de la página siguiente en la respuesta.
nextPageParaName String Opcional. Determina el nombre de la página siguiente en la solicitud.
nextPageRequestHeader String Opcional. Determina el nombre de encabezado de la página siguiente en la solicitud.
nextPageUrl String Opcional. Determina la dirección URL de la página siguiente, si es diferente de la dirección URL de la solicitud inicial.
nextPageUrlQueryParameters String Opcional. Determina los parámetros de consulta de la dirección URL de la página siguiente, si es diferente de la dirección URL de la solicitud inicial.

Defina la cadena en el formato dictionary<string, object> serializado: {'<attr_name>': <val>, '<attr_name>': <val>... }
offsetParaName String Opcional. Define el nombre del parámetro de desplazamiento.
pageSizeParaName String Opcional. Define el nombre del parámetro de tamaño de página.
PageSize Entero Define el tamaño de paginación.

Código pollingConfig de ejemplo

El código siguiente muestra un ejemplo de la sección pollingConfig del archivo de configuración de 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": [
          "$"
        ]
     }
}

Implementación del conector en Microsoft Sentinel e inicio de la ingesta de datos

Después de crear el archivo de configuración JSON, incluida la interfaz de usuario y la configuración de sondeo, implemente el conector en el área de trabajo de Microsoft Sentinel.

  1. Use una de las siguientes opciones para implementar el conector de datos.

    Sugerencia

    La ventaja de la implementación mediante una plantilla de Azure Resource Manager (ARM) es que hay varios valores integrados en la plantilla y no es necesario definirlos manualmente en una llamada API.

    Ajuste las colecciones de configuración JSON en una plantilla de ARM para implementar el conector. Para asegurarse de que el conector de datos se implementa en el área de trabajo correcta, asegúrese de definir el área de trabajo de la plantilla de ARM o seleccione el área de trabajo al implementar la plantilla de ARM.

    1. Prepare un archivo JSON de plantilla de ARM para el conector. Por ejemplo, consulte los siguientes archivos JSON de plantilla de ARM:

    2. En Azure Portal, busque la opción Implementar una plantilla personalizada.

    3. En la página Implementación personalizada, seleccione Cree su propia plantilla en el editor>Cargar archivo. Vaya a la plantilla de ARM local, selecciónela y guarde los cambios.

    4. Seleccione la suscripción y el grupo de recursos. Después, escriba el área de trabajo de Log Analytics donde desea implementar el conector personalizado.

    5. Seleccione Revisar y crear para implementar el conector personalizado en Microsoft Sentinel.

    6. En Microsoft Sentinel, vaya a la página Conectores de datos y busque el nuevo conector. Configúrelo para iniciar la ingesta de datos.

    Para más información, consulte Implementación de una plantilla local en la documentación de Azure Resource Manager.

  2. Configure el conector de datos para conectar el origen de datos y empezar a ingerir datos en Microsoft Sentinel. Puede conectarse al origen de datos a través del portal, como con los conectores de datos estándar, o a través de la API.

    Cuando se usa el Azure Portal para conectarse, los datos de usuario se envían automáticamente. Al conectarse a través de la API, deberá enviar los parámetros de autenticación pertinentes en la llamada API.

    En la página del conector de datos de Microsoft Sentinel, siga las instrucciones que ha proporcionado para conectarse al conector de datos.

    La página del conector de datos de Microsoft Sentinel se controla mediante la configuración de InstructionSteps en el elemento connectorUiConfig del archivo de configuración JSON de CCP. Si tiene problemas con la conexión de la interfaz de usuario, asegúrese de que tiene la configuración correcta para el tipo de autenticación.

  3. En Microsoft Sentinel, vaya a la página Registros y compruebe que ve que los registros del origen de datos fluyen al área de trabajo.

Si no ve que los datos fluyen a Microsoft Sentinel, compruebe la documentación del origen de datos y los recursos de solución de problemas, compruebe los detalles de configuración y compruebe la conectividad. Para más información, consulte Supervisión del estado de los conectores de datos.

Desconexión del conector

Si ya no necesita los datos del conector, desconéctelo para detener el flujo de datos.

Utilice uno de los métodos siguientes:

  • Azure Portal: en la página del conector de datos de Microsoft Sentinel, seleccione Desconectar.

  • API: use la API DISCONNECT para enviar una llamada PUT con un cuerpo vacío a la siguiente dirección URL:

    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

Pasos siguientes

Si aún no lo ha hecho, le invitamos a que comparta su nuevo conector de datos sin código con la comunidad de Microsoft Sentinel. Cree una solución para el conector de datos y compártala en el Marketplace de Microsoft Sentinel.

Para obtener más información, vea