**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](../../../reference-and-developer-docs/reference/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](https://app.gitbook.com/s/HVBaxKOW1b6qcIQ6iMBh/).
### 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.
### <strong>Mapping principles</strong>
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.
### <strong>Why follow the mapping principles?</strong>
* 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.
### <strong>Third-party mapping examples</strong>
* [DUO- SSO - Data Model Mapping](https://github.com/demisto/content/blob/master/Packs/DuoAdminApi/ModelingRules/DuoModelingRule_2_0/DuoModelingRule_2_0.xif#L26)
* [Okta - SSO - Data Model Mapping](https://github.com/demisto/content/blob/master/Packs/Okta/ModelingRules/OktaModelingRules_2_0/OktaModelingRules_2_0.xif)
### <strong>Mandatory XDM fields to map for authentication events</strong>
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](../../../reference-and-developer-docs/reference/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.
<table><thead><tr><th width="171">XDM Target Field</th><th>Data Type</th><th>Purpose and Guidance</th></tr></thead><tbody><tr><td><code>xdm.auth.service</code></td><td>String</td><td><strong>System Role.</strong> Decided PER EVENT TYPE: <code>IDP</code> (validates), <code>SP</code> (initiates), or <code>Universal</code> (local/AAA). Do not use protocol names here.</td></tr><tr><td><code>xdm.event.operation</code></td><td>String</td><td>Describes the action (such as <code>AUTH_LOGIN</code>, <code>AUTH_MFA</code>). Never blind-default if unclear.</td></tr><tr><td><code>xdm.event.original_event_type</code></td><td>String</td><td>The raw vendor event name exactly as logged.</td></tr><tr><td><code>xdm.event.outcome</code></td><td>Enum</td><td>Set only to <code>SUCCESS</code> or <code>FAILED</code>. Do not set on intermediate steps.</td></tr><tr><td><code>xdm.event.tags</code></td><td>Array</td><td>Must include <code>XDM_CONST.EVENT_TAG_AUTHENTICATION</code></td></tr><tr><td><code>xdm.event.type</code></td><td>String</td><td>Must contain <code>authentication</code>.</td></tr><tr><td><code>xdm.network.ip_protocol</code></td><td>Enum</td><td>The transport protocol (e.g., <code>TCP</code>). Fallback to <code>IP_PROTOCOL_IP</code> if unknown.</td></tr><tr><td><code>xdm.source.ipv4</code></td><td>String</td><td>The client IP observed by the authenticator. Never static or empty.</td></tr><tr><td><code>xdm.source.port</code></td><td>Integer</td><td>Map real value; otherwise <code>0</code>.</td></tr><tr><td><code>xdm.source.user.upn</code></td><td>String</td><td><strong>Identity Key.</strong> Must be UPN-shaped (<code>user@domain</code>). Use a shape-guard to append <code>@localhost</code> if the source provides only a bare username.</td></tr><tr><td><code>xdm.source.user.identity_type</code></td><td>Enum</td><td>The nature of the principal (such as <code>USER</code>, <code>MACHINE</code>, <code>BUILTIN</code>).</td></tr><tr><td><code>xdm.source.user.user_type</code></td><td>Enum</td><td>The account class (such as <code>REGULAR</code>, <code>SERVICE_ACCOUNT</code>).</td></tr><tr><td><code>xdm.target.ipv4</code></td><td>String</td><td>The IP of the device being accessed. If absent, use <code>""</code>.</td></tr><tr><td><code>xdm.target.port</code></td><td>Integer</td><td>Map real value; otherwise <code>0</code>.</td></tr><tr><td><code>xdm.target.resource.name</code></td><td>String</td><td>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.</td></tr></tbody></table>
### <strong>Detailed implementation guidance</strong>
### The three branches logic
When an authentication field is missing from your source log, apply these treatments in order:
1. **MAP**: If the source carries the value directly.
2. **DERIVE**: If the value can be constructed from another field (e.g., synthesizing a UPN).
3. **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. |
### <strong>Important topologies</strong>
### **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.