How to map authentication events for analytics ↗

License

To enable Identity Threat Detection and Response (ITDR) analytics, you must have the ITDR license and ingest identity logs. Full identity analytics capabilities are optimized for data collected via Cortex XDR agents and specific cloud/SaaS integrations.

Cortex XSIAM enables analytics to run on all mapped authentication data, which automatically creates authentication stories for Cortex Data Model (XDM) identity data. To build these stories, you must map authentication events to the XDM schema using specific mandatory fields and principles. For a complete list of these fields, see XDM fields for mapping authentication events.

Prerequisite

You must have View/Edit RBAC permissions for Data Management (under Configurations > Data Management).
Familiarize yourself with the Cortex Data model (XDM) schema for field definitions and naming conventions, see XSIAM Data Model Schema.

Scope Clarification

This Feature focuses on authentication events related to SSO (Single Sign-On) and SaaS (Software-as-a-Service) application authentications. It does not cover internal authentication mechanisms such as Kerberos, NTLM, or traditional domain logon events generated by on-premise infrastructure.

Mapping principles

When mapping your authentication data, follow these guidelines:

Prioritize conclusive events: Focus on mapping events that represent the final result of an authentication process.
Exclude ambiguous steps: Intermediate or informational events should not be treated as indicators of success or failure.
Preserve context across the full authentication flow: Include intermediate events to provide visibility into the process, while making it clear they are not final outcomes.
Normalize raw error and outcome data: Define explicit mapping logic between the raw event fields that contain outcome or error messages, such as get_reason and debugdata_errorcode, and the target XDM fields. This logic should normalize provider-specific strings or codes into a canonical format to support reliable detection and analytics across diverse sources.
Preserve attack evidence: Do not sanitize identity fields at model time. Hostile values, such as template-injection probes, must be preserved verbatim as they are critical evidence for detection.

Why follow the mapping principles?

Prevents misclassification of failed sessions as successful.
Avoids distorted behavioral baselines that can mask real attacks.
Preserves full visibility of authentication flows without misleading analytics.

Third-party mapping examples

Mandatory XDM fields to map for authentication events

You must map all 15 of the following fields. If a mandatory field is unmapped or incorrect, the event will be dropped from authentication stories and identity analytics. For more detailed information on these fields, see XDM fields for mapping authentication events.

Important

To maximize the variety of issues that are retrieved based on the XDM authentication stories, we recommend that the following additional fields are populated: xdm.logon.type, xdm.source.user_agent, and xdm.source.host.device_category. Should you decide to change the default XDM mappings, ensure that both the mandatory and recommended fields are populated and do not contain any empty values.

XDM Target Field	Data Type	Purpose and Guidance
`xdm.auth.service`	String	System Role. Decided PER EVENT TYPE: `IDP` (validates), `SP` (initiates), or `Universal` (local/AAA). Do not use protocol names here.
`xdm.event.operation`	String	Describes the action (such as `AUTH_LOGIN`, `AUTH_MFA`). Never blind-default if unclear.
`xdm.event.original_event_type`	String	The raw vendor event name exactly as logged.
`xdm.event.outcome`	Enum	Set only to `SUCCESS` or `FAILED`. Do not set on intermediate steps.
`xdm.event.tags`	Array	Must include `XDM_CONST.EVENT_TAG_AUTHENTICATION`
`xdm.event.type`	String	Must contain `authentication`.
`xdm.network.ip_protocol`	Enum	The transport protocol (e.g., `TCP`). Fallback to `IP_PROTOCOL_IP` if unknown.
`xdm.source.ipv4`	String	The client IP observed by the authenticator. Never static or empty.
`xdm.source.port`	Integer	Map real value; otherwise `0`.
`xdm.source.user.upn`	String	Identity Key. Must be UPN-shaped (`user@domain`). Use a shape-guard to append `@localhost` if the source provides only a bare username.
`xdm.source.user.identity_type`	Enum	The nature of the principal (such as `USER`, `MACHINE`, `BUILTIN`).
`xdm.source.user.user_type`	Enum	The account class (such as `REGULAR`, `SERVICE_ACCOUNT`).
`xdm.target.ipv4`	String	The IP of the device being accessed. If absent, use `""`.
`xdm.target.port`	Integer	Map real value; otherwise `0`.
`xdm.target.resource.name`	String	The name or address of the service being accessed. Set this in addition to specific host/app fields. Never pad this; if absent, resolve to null.

Detailed implementation guidance

The three branches logic

When an authentication field is missing from your source log, apply these treatments in order:

MAP: If the source carries the value directly.
DERIVE: If the value can be constructed from another field (e.g., synthesizing a UPN).
PAD: Use semantically empty placeholders only if derivation is impossible.
- Valid Pads: to_integer(0) for ports, "" for target IP, IP_PROTOCOL_IP for protocol.
- Invalid Pads: Never pad xdm.target.resource.name or xdm.source.ipv4.

Principal Classification (Identity vs. User Type)

To support identity analytics, you must map both fields using specific constants:

identity_type: Classifies the nature of the principal (such as IDENTITY_TYPE_MACHINE for names ending in $, IDENTITY_TYPE_BUILTIN for SYSTEM).
user_type: Defines the operational class (such as USER_TYPE_REGULAR for human logins, USER_TYPE_SERVICE_ACCOUNT for svc_ prefixes).

Mandatory Field Crosswalk for Network/AAA Devices

Vendor Field Hint	XDM Target Field	Implementation Note
`user`, `username`	`xdm.source.user.upn`	Synthesize UPN: `concat(tmp_user, "@localhost")`
`priv_lvl`, `privilege`	`xdm.auth.privilege_level`	Band 15+ to `ADMIN`, 1+ to `USER`, 0 to `GUEST`.
`dvc_ip`, `nas-ip`	`xdm.target.ipv4`	The IP of the accessed device.
`src_ip`, `rem_addr`	`xdm.source.ipv4`	The IP of the authenticating client workstation.
`service`	`xdm.auth.auth_method`	Protocol. (e.g., `RADIUS`). Do not map to `xdm.auth.service`.
`task_id`, `session-id`	`xdm.network.session_id`	Crucial for correlating session lifecycle events.

Important topologies

Device-local authentication

When a device logs a login to itself (such as SSH into a router):

Observer: The device that wrote the log is the xdm.observer.*.
Target: If the login was into that device, the device is ALSO the target: xdm.target.host.hostname and xdm.target.ipv4.
Source: The remote workstation initiating the connection is the source: xdm.source.ipv4, xdm.source.port, and xdm.source.user.*.

AAA Gateway topology

Network-device AAA logs (TACACS+, RADIUS) involve three parties:

Principal: The human or service account (xdm.source.user.upn).
Source: The user's workstation (xdm.source.ipv4).
Target: The network device being accessed (xdm.target.ipv4 and xdm.target.resource.name).
Observer: The AAA server validating the credential (xdm.observer.name).

Logout convention

A logout record should take xdm.event.outcome = OUTCOME_SUCCESS but leave xdm.event.operation unset. This ensures logout events do not incorrectly inflate login metrics.