/ 
Punk-SAML-0.01
/ Punk::SAML::Response

NAME

Punk::SAML::Response - a Response, verified

DESCRIPTION

Verifies a Response and returns the identity it carries.

Usable with no application booted, which is what lets punk saml verify run against a saved document and the suite run this a thousand times with no HTTP at all.

METHODS

verify ($bytes, %opts)

The decoded XML in, an identity hashref out, or a Punk::SAML::Error thrown. Required options are entity_id (this application's), idp_entity_id (the provider's), acs_url and certs. Optional: idp, now, skew, require_signed, allow_sha1, allow_idp_initiated, in_response_to and seen.

now is an argument rather than a call to time, so a test and punk saml verify --at can move it without sleeping.

seen is the replay store: a coderef called with the assertion id, returning true if it has been presented before. It is an argument because whether the store is shared across the worker pool is the application's decision, and this method has no application.

The identity

{
    idp             => 'okta',
    name_id         => 'jo@example.com',
    name_id_format  => '...',
    attributes      => { groups => ['staff', 'eng'] },
    friendly        => { 'E-Mail Address' => ['jo@example.com'] },
    session_index   => '_a1b2...',
    authn_instant   => 1725600000,
    not_on_or_after => 1725600300,
    assertion_id    => '_c3d4...',
    raw             => $bytes,
}

Every attribute value is an arrayref, always, including when there is one value. SAML attributes are multi-valued and groups is the one everybody uses; an API that returned a scalar for one value and an arrayref for two would be the bug every on_login body has on the day a user joins a second group. A provider that sends the same Name twice has its values merged rather than replaced.

WHAT IS CHECKED

In order, and the order matters: cheap before expensive, structural before cryptographic, and the signature before anything the signature protects is read.

The element whose child the Signature is, is the element the signature covers, is the element the identity is read from. Every SAML authentication bypass of the last decade is a document where those three were allowed to differ.

AUTHOR

LNATION, <email at lnation.org>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION.

This is free software, licensed under the Artistic License 2.0.