SAML Assertions, Statements, and the Schema

This is Part 2 of the "SAML 2.0 for Engineers" series.

SAML 2.0 is often misunderstood as a simple "login button" protocol. In reality, it is a verbose, XML-based framework for exchanging security assertions. For developers and identity engineers, the core challenge lies in parsing and validating the Assertion element—a signed XML document that travels from the Identity Provider (IdP) to the Service Provider (SP). An assertion is not a single block of data; it is a container that can hold multiple distinct "statements," each serving a specific purpose in the federation handshake. Understanding the internal structure of these statements, the constraints applied via Conditions, and the schema validation required to process them safely is critical for building secure identity flows.

The Anatomy of an Assertion

At the top level, a SAML message contains an Assertion element (namespace urn:oasis:names:tc:SAML:2.0:assertion). As defined in the SAML 2.0 Core Specification, this element serves as the atomic unit of trust within the protocol. Before any business logic can be applied, the SP must verify that the assertion is structurally valid according to the SAML 2.0 XSD schema and cryptographically signed by the IdP.

Every assertion instance must include three mandatory metadata fields that establish its provenance and timing:

1. ID: A unique identifier (usually a UUID) for the assertion. This is critical for tracking and preventing replay attacks.
2. IssueInstant: The timestamp when the SAML document was created by the IdP.
3. Issuer: The entity ID of the IdP that created the token.

These fields are not just metadata; they are part of the signed payload. If an attacker modifies the Issuer or IssueInstant after signing, the signature verification will fail, and the SP will reject the token.

The Three Statement Types

Inside the Assertion container, you will find one or more Statement elements. Each statement type serves a distinct function in the identity federation model.

1. AuthnStatement (Authentication)

This is the most common statement. It confirms that the subject (user) has been authenticated. It does not just say "yes"; it provides context. Key elements include:

• AuthnContext: Describes how the user authenticated (e.g., password, MFA, certificate). This is defined by URIs in the AuthnContextClassRef element.
• AuthnInstant: The specific time authentication occurred.
• SessionIndex: An identifier for the session at the IdP, allowing the SP to correlate future requests.

As outlined in the SAML 2.0 Core Specification, the AuthnStatement structure provides the necessary context for the SP to determine the strength of the authentication event.

2. AttributeStatement

This statement carries the user's profile data. While AuthnStatement proves who the user is, AttributeStatement provides what we know about them. This includes attributes like email, displayName, group, or role. These attributes are essential for authorization decisions on the SP side, such as granting admin access or populating user profiles.

The structure of this statement is also governed by the SAML 2.0 Core Specification, which defines how attributes are packaged and transmitted within the assertion.

3. AuthorizationDecisionStatement

Less common in modern web SSO, this statement explicitly grants or denies access to a resource. It contains a Decision element with values Permit, Deny, or Indeterminate. Most SPs prefer to evaluate authorization locally based on attributes rather than relying on the IdP to make access decisions, making this statement rarely seen in practice.

NameID and Attribute Mapping

The NameID element is the primary identifier for identifying the user across systems. It appears in the Subject element of the Assertion. As specified in the SAML 2.0 Core Specification regarding NameID formats, the NameID consists of three parts:

• Value: The actual identifier string (e.g., user@example.com).
• Format: A URI defining the interpretation of the value (e.g., urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress).
• NameQualifier/SPNameQualifier: Optional qualifiers to disambiguate names if multiple entities use the same identifier space.

Common formats include emailAddress, transient (a random, non-persistent ID generated per SP), and persistent (a stable ID generated by the IdP for a specific SP). The choice of format impacts privacy and tracking. Transient IDs prevent cross-SP tracking, while email addresses enable easy user lookup but may raise privacy concerns.

In the AttributeStatement, attributes are mapped using the Attribute element, which contains a Name, NameFormat, and AttributeValue. The SP uses these names to map incoming data to its internal user model. Misalignment in attribute naming conventions is a frequent source of integration bugs.

Conditions and Validity Mechanisms

Security in SAML relies heavily on the Conditions element, which restricts when and where an assertion can be used. This element is optional per the SAML 2.0 schema but strongly recommended, and when present it contains two key sub-elements:

1. Time Constraints: NotBefore and NotOnOrAfter define a validity window. The SP must check its local clock against these timestamps. If the current time is outside this window, the assertion is rejected. This prevents replay attacks where an attacker captures and reuses an old assertion.

2. Audience Restriction: The AudienceRestriction element contains a list of Audience URIs. As detailed in the SAML 2.0 Profile Specification, the SP must verify that its own Entity ID is present in this list. If the assertion was intended for a different SP, it must be rejected. This ensures that sensitive user data is not leaked to unintended recipients.

Schema Validation and Security

Before processing any assertion, the SP must validate it against the SAML 2.0 XSD schema. This ensures the XML structure is correct and that all required elements are present. However, schema validation alone is insufficient for security.

Two major threats exploit the flexibility of XML:

• XML External Entity (XXE): Attackers can inject malicious entities in attribute values or other XML structures. According to security advisories such as OWASP XXE, SPs must disable external entity processing in their XML parsers to mitigate this risk.
• Signature Wrapping Attacks: An attacker can embed a valid, unsigned assertion inside a larger, signed assertion, or reorder elements to confuse the parser. To mitigate this, SPs should use canonicalization (C14N) when verifying signatures and ensure they are parsing the correct elements.

Always verify the signature after canonicalization and before trusting any content. Relying solely on schema validation leaves the system vulnerable to these sophisticated attacks.

Conclusion

SAML assertions are complex, structured documents that require careful handling. By understanding the roles of AuthnStatement, AttributeStatement, and Conditions, developers can build more resilient identity integrations. Always prioritize schema validation, signature verification, and strict audience restrictions to ensure secure federation.