SAML 2.0 Assertion XML Structure Explained

A Security Assertion Markup Language (SAML) 2.0 assertion is an XML-based security token issued by an Identity Provider (IdP) to communicate identity verification and user claims to a Service Provider (SP). This article outlines the architectural structure of a SAML 2.0 assertion, specifically detailing the root container, the <Subject> element for user identification, and the <AttributeStatement> element used for transmitting user profile and authorization data.

Structural Overview of an Assertion

A complete SAML 2.0 assertion containing subject information and attributes adheres to a standardized XML hierarchy. The root <saml:Assertion> tag envelops metadata, conditions, subject definitions, and statements.

<saml:Assertion 
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    ID="_a75932c0-8d5f-4a3b-9e48-e87f3b890a21"
    Version="2.0"
    IssueInstant="2023-10-24T12:00:00.000Z">
    
    <saml:Issuer>https://idp.example.com/metadata</saml:Issuer>

    <!-- Optional digital signature verifying authenticity -->
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <!-- XML Digital Signature Elements -->
    </ds:Signature>

    <saml:Subject>
        <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">
            user@example.com
        </saml:NameID>
        <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
            <saml:SubjectConfirmationData 
                NotOnOrAfter="2023-10-24T12:05:00.000Z" 
                Recipient="https://sp.example.com/saml/sso"/>
        </saml:SubjectConfirmation>
    </saml:Subject>

    <saml:Conditions 
        NotBefore="2023-10-24T11:55:00.000Z" 
        NotOnOrAfter="2023-10-24T12:05:00.000Z">
        <saml:AudienceRestriction>
            <saml:Audience>https://sp.example.com/metadata</saml:Audience>
        </saml:AudienceRestriction>
    </saml:Conditions>

    <saml:AuthnStatement 
        AuthnInstant="2023-10-24T12:00:00.000Z" 
        SessionIndex="_session_index_value">
        <saml:AuthnContext>
            <saml:AuthnContextClassRef>
                urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
            </saml:AuthnContextClassRef>
        </saml:AuthnContext>
    </saml:AuthnStatement>

    <saml:AttributeStatement>
        <saml:Attribute Name="firstName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
            <saml:AttributeValue xsi:type="xs:string">Jane</saml:AttributeValue>
        </saml:Attribute>
        
        <saml:Attribute Name="lastName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
            <saml:AttributeValue xsi:type="xs:string">Doe</saml:AttributeValue>
        </saml:Attribute>

        <saml:Attribute Name="roles" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
            <saml:AttributeValue xsi:type="xs:string">Administrator</saml:AttributeValue>
            <saml:AttributeValue xsi:type="xs:string">Editor</saml:AttributeValue>
        </saml:Attribute>
    </saml:AttributeStatement>

</saml:Assertion>

The Subject Statement

The <saml:Subject> element specifies the principal (the user or entity) authenticated by the IdP and describes the constraints under which the assertion is valid.

<saml:NameID>: Defines the unique identity handle for the subject. The Format attribute specifies the identifier type, such as emailAddress, unspecified, transient, or persistent.
<saml:SubjectConfirmation>: Establishes how the Service Provider can verify that the subject matches the entity presenting the assertion.
- Method: Typically set to urn:oasis:names:tc:SAML:2.0:cm:bearer for single sign-on flows.
- <saml:SubjectConfirmationData>: Enforces security constraints including NotOnOrAfter (token expiration) and Recipient (the exact endpoint URL at the SP authorized to receive the token).

The Attribute Statement

The <saml:AttributeStatement> element delivers user identity claims, profile information, and authorization roles to the Service Provider.

<saml:Attribute>: Represents an individual claim or property.
- Name: The machine-readable or standardized identifier for the attribute (e.g., firstName, email, memberOf).
- NameFormat: Specifies the URI format standard for interpreting the name (e.g., urn:oasis:names:tc:SAML:2.0:attrname-format:basic or urn:oasis:names:tc:SAML:2.0:attrname-format:uri).
- FriendlyName: An optional, human-readable label.
<saml:AttributeValue>: Contains the actual value of the attribute. Multiple <saml:AttributeValue> tags can exist within a single <saml:Attribute> tag to convey multi-valued attributes, such as multiple user roles or group memberships. The xsi:type attribute can explicitly define data types such as xs:string or xs:integer.