/ 
Net-SAML2-0.89
⭐ Starred 8 / Net::SAML2::Protocol::Assertion

NAME

Net::SAML2::Protocol::Assertion - SAML2 assertion object

VERSION

version 0.89

SYNOPSIS

my $assertion = Net::SAML2::Protocol::Assertion->new_from_xml(
  xml         => decode_base64($SAMLResponse),
  cacert      => 'cacert.pem',        # Required to securely validate Assertions
  key_file    => 'private.key',       # Required for Encrypted Assertions
  issuer      => $idp->{entity_id},   # May be required in future version
  destination => 'SP Destination',    # May be required in future version
);

METHODS

new_from_xml( ... )

Constructor. Creates an instance of the Assertion object, parsing the given XML to find the attributes, session and nameid.

Arguments:

xml

XML data

key_file

Optional but Required handling Encrypted Assertions.

path to the SP's private key file that matches the SP's public certificate used by the IdP to Encrypt the response (or parts of the response)

cacert

path to the CA certificate for verification.

cacert trusts the certificate embedded in the document's own KeyInfo, but only once that certificate chains to the CA. A trust anchor is only as narrow as the CA behind it: any certificate issued under that CA is accepted, so point cacert at the IdP's own certificate (or a dedicated single-purpose CA) rather than a public/corporate root. When the IdP references its signing key by KeyName or RetrievalMethod (no embedded X509Certificate), use cert_text instead.

cert_text

text form of the IdP signing certificate (FORMAT_PEM) used to verify the assertion signature. Unlike cacert, this pins a specific certificate: signatures are verified directly against it and the document's own KeyInfo is never consulted. That makes cert_text the stronger of the two anchors on the key-trust axis - a certificate issued by the same CA as the IdP's does not satisfy it.

One of cacert, cert_text or insecure_trust_embedded_cert is required.

Pinning is exact. Every signature the assertion is extracted from must be made by the pinned certificate, so an IdP that rotates signing certificates needs cert_text updated in step with the rotation (or cacert pointed at a CA narrow enough to cover only that IdP).

insecure_trust_embedded_cert

Boolean, default false. When true, no trust anchor is required and the certificate embedded in the document is trusted as-is. This disables effective signature verification, and with it the signature-wrapping defences that anchor assertion extraction. Intended only for local testing.

require_signed_assertion

Boolean. When true, a decrypted EncryptedAssertion that carries no signature is rejected rather than accepted.

issuer

Specifies the expected Issuer value in the Assertion. Results in a croak if defined and the value does not match the value in the Assertion.

It would be the $idp->{entity_id}

While optional it is recommended for ensuring that the Assertion is properly validated.

Notice: This may become required in a future version.

destination

Specifies the expected destination value in the Assertion. Results in a croak if defined and the value does not match the value in the Assertion.

It would be the Location field of the assertion_consumer_service for the Binding that you are receiving the Assertion via (POST).

While optional it is recommended for ensuring that the Assertion is properly validated.

Notice: This may become required in a future version.

response_status

Returns the response status

response_substatus

SAML errors are usually "nested" ("Responder -> RequestDenied" for instance, means that the responder in this transaction (the IdP) denied the login request). For proper error message generation, both levels are needed.

name

Returns the CN attribute, if provided.

nameid

Returns the NameID

nameid_format

Returns the NameID Format

nameid_name_qualifier

Returns the NameID NameQualifier

nameid_sp_name_qualifier

Returns the NameID SPNameQualifier

nameid_sp_provided_id

Returns the NameID SPProvidedID

authnstatement

Returns the AuthnStatement

authnstatement_authninstant

Returns the AuthnStatement AuthnInstant

authnstatement_sessionindex

Returns the AuthnStatement SessionIndex

authnstatement_subjectlocality

Returns the AuthnStatement SubjectLocality

subjectlocality_address

Returns the SubjectLocality Address

subjectlocality_dnsname

Returns the SubjectLocality DNSName

authnstatement_authncontext

Returns the AuthnContext for the AuthnStatement

contextclass_authncontextclassref

Returns the ContextClass AuthnContextClassRef

valid( $audience, $in_response_to, $issuer, $destination )

Returns true if this Assertion is currently valid for the given audience.

Also accepts $in_response_to which it checks against the returned Assertion. This is very important for security as it helps ensure that the assertion that was received was for the request that was made.

Checks the audience matches, and that the current time is within the Assertions validity period as specified in its Conditions element.

Optionally it also checks that the $issuer and $destination matches the values provided in the Assertion.

Parameters:

$audience: Intended Audience for the Assertion
$in_response_to: the orginal SAML request ID

It checks against the returned Assertion. This is very important for security as it helps ensure that the assertion that was received was for the request that was made.

$issuer: The IdP configured Issuer

Checks to ensure that the Issuer in the Assertion is the expected value.

$destination: The SP Destination

Checks to ensure that the Destination in the Response is the expected value.

success

Returns true if the response status is a success, returns false otherwise. In case the assertion isn't successfull, the "response_status" and "response_substatus" calls can be use to see why the assertion wasn't successful.

AUTHOR

Timothy Legge <timlegge@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Venda Ltd, see the CONTRIBUTORS file for others.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.