website/docs: add SAML source mapping guidance (#21978)

website/docs/users-sources/sources/protocols/saml/index.md

@@ -86,9 +86,55 @@ This will depend heavily on what software you are using for your IDP. On the Met
 
 See the [overview](../../property-mappings/index.md) for information on how property mappings work.
 
+SAML source property mappings customize the user and group properties created from a SAML assertion. authentik parses the assertion's `AttributeStatement` into the `properties` dictionary before custom mappings run, using each SAML attribute's `Name` as the dictionary key. Custom mappings can then translate those SAML attribute names to authentik user fields such as `username`, `email`, `name`, and `attributes`.
+
+Property mappings do not change the internal SAML source connection identifier, which is based on the assertion's NameID. To persist mapped user fields, ensure the source flow that runs for the user includes a [User Write stage](../../../../add-secure-apps/flows-stages/stages/user_write.md) before the user login stage. For existing users, this is the source's authentication flow; for new users, this is the source's enrollment flow.
+
 ### Expression data
 
 The following variables are available to SAML source property mappings:
 
-- `root`: An XML `ETree` object containing data from the source.
+The parsed XML objects use Python's standard [`xml.etree.ElementTree`](https://docs.python.org/3/library/xml.etree.elementtree.html) API.
-- `name_id`: An XML `Element` object identifying the user.
+
+- `root`: The parsed XML root containing data from the source.
+- `assertion`: The parsed XML element containing the SAML assertion.
+- `name_id`: The parsed XML element identifying the user.
+- `properties`: A Python dictionary containing the source's parsed SAML attributes and the results of any previously run mappings.
+
+### Example
+
+This example maps common SAML attributes to authentik user fields. Replace the attribute names with the SAML attribute `Name` values sent by the external identity provider connected to this SAML source.
+
+```python
+email = properties.get("email") or properties.get("urn:oid:0.9.2342.19200300.100.1.3")
+first_name = properties.get("firstname") or properties.get("urn:oid:2.5.4.42")
+last_name = properties.get("lastname") or properties.get("urn:oid:2.5.4.4")
+
+return {
+    "username": email,
+    "email": email,
+    "name": f"{first_name or ''} {last_name or ''}".strip(),
+    "attributes": {
+        "first_name": first_name,
+        "last_name": last_name,
+    },
+}
+```
+
+If you need to read the XML assertion directly, use the SAML assertion namespace when searching for elements:
+
+```python
+NS_SAML_ASSERTION = "urn:oasis:names:tc:SAML:2.0:assertion"
+
+attributes = {}
+for attribute in assertion.findall(f".//{{{NS_SAML_ASSERTION}}}Attribute"):
+    values = [
+        value.text
+        for value in attribute.findall(f"{{{NS_SAML_ASSERTION}}}AttributeValue")
+    ]
+    attributes[attribute.attrib["Name"]] = values[0] if len(values) == 1 else values
+
+return {
+    "email": attributes.get("email"),
+}
+```