> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/cortex-xsiam/configure-cortex-xsiam/data-management/data-model-rules/how-to-map-authentication-story-events.md).

# How to map authentication story events?

{% hint style="warning" %}

### Prerequisite

Data Model Rules requires **View/Edit** RBAC permissions for **Data Management** (under **Configurations** → **Data Management**), which are the same permissions required for Dataset Management, Parsing Rules, and Event Forwarding.
{% endhint %}

Cortex XSIAM enables analytics to run on all mapped authentication data, which automatically creates authentication stories for Cortex Data Model (XDM) identity data. As a result, you need to map authentication events to the Cortex XSIAM XDM schema to build the authentication story. For a complete list of these fields, see [XDM fields for mapping authentication events](/cortex-xsiam/reference-and-developer-docs/reference/xdm-fields-for-mapping-authentication-events.md).

{% hint style="info" %}

### 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.
{% endhint %}

{% hint style="warning" %}

### Prerequisite

Familiarize yourself with the Cortex Data model (XDM) schema for field definitions and naming conventions, see [XSIAM Data Model Schema](/xsiam-data-model-schema/readme.md).
{% endhint %}

<details>

<summary>Mapping principles</summary>

When mapping your authentication data, follow these guidelines:

* **Prioritize conclusive events**: Focus on mapping events that clearly represent the final stage or result of an authentication process.
* **Exclude ambiguous or non-final steps from outcome decisions**: 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**: You must 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.

</details>

<details>

<summary>Why follow the mapping principles?</summary>

* 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.

</details>

<details>

<summary>Third-party mapping examples</summary>

* [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)

</details>

<details>

<summary>Mandatory XDM fields to map for authentication events</summary>

There are mandatory fields that you need map to the Cortex Data Model (XDM) schema to build authentication stories based on the mapped authentication data. For more detailed information on these fields, see [XDM fields for mapping authentication events](/cortex-xsiam/reference-and-developer-docs/reference/xdm-fields-for-mapping-authentication-events.md).

The following fields are mandatory to map:

* `xdm.source.port`
* `xdm.target.ipv4`
* `xdm.target.port`
* `xdm.network.ip_protocol`
* `xdm.source.ipv4`
* `xdm.event.type`
* `xdm.event.tags`
* `xdm.event.operation`
* `xdm.event.original_event_type`
* `xdm.auth.service`
* `xdm.event.outcome`
* `xdm.source.user.upn`

{% hint style="info" %}

### 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.target.resource.name`, `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.
{% endhint %}

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cortex-docs.paloaltonetworks.com/cortex-xsiam/configure-cortex-xsiam/data-management/data-model-rules/how-to-map-authentication-story-events.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.