NAME

Net::SAML2 - SAML2 bindings and protocol implementation

VERSION

version 0.82

SYNOPSIS

See TUTORIAL.md for implementation documentation and
t/12-full-client.t for a pseudo implementation following the tutorial

# generate a redirect off to the IdP:

      my $idp = Net::SAML2::IdP->new($IDP);
      my $sso_url = $idp->sso_url('urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect');

      my $authnreq = Net::SAML2::Protocol::AuthnRequest->new(
              issuer        => 'http://localhost:3000/metadata.xml',
              destination   => $sso_url,
              nameid_format => $idp->format('persistent'),
      )->as_xml;

      my $authnreq = Net::SAML2::Protocol::AuthnRequest->new(
        id            => 'NETSAML2_Crypt::OpenSSL::Random::random_pseudo_bytes(16),
        issuer        => $self->{id},		# Service Provider (SP) Entity ID
        destination   => $sso_url,		# Identity Provider (IdP) SSO URL
        provider_name => $provider_name,	# Service Provider (SP) Human Readable Name
        issue_instant => DateTime->now,	# Defaults to Current Time
      );

      my $request_id = $authnreq->id;	# Store and Compare to InResponseTo

      # or

      my $request_id = 'NETSAML2_' . unpack 'H*', Crypt::OpenSSL::Random::random_pseudo_bytes(16);

      my $authnreq = Net::SAML2::Protocol::AuthnRequest->as_xml(
        id            => $request_id,		# Unique Request ID will be returned in response
        issuer        => $self->{id},		# Service Provider (SP) Entity ID
        destination   => $sso_url,		# Identity Provider (IdP) SSO URL
        provider_name => $provider_name,	# Service Provider (SP) Human Readable Name
        issue_instant => DateTime->now,	# Defaults to Current Time
      );

      my $redirect = Net::SAML2::Binding::Redirect->new(
              key => '/path/to/SPsign-nopw-key.pem',
              url => $sso_url,
              param => 'SAMLRequest' OR 'SAMLResponse',
              cert => '/path/to/IdP-cert.pem'
      );

      my $url = $redirect->sign($authnreq);

      my $ret = $redirect->verify($url);

# handle the POST back from the IdP, via the browser:

      my $post = Net::SAML2::Binding::POST->new;
      my $ret = $post->handle_response(
              $saml_response
      );

      if ($ret) {
              my $assertion = Net::SAML2::Protocol::Assertion->new_from_xml(
                      xml         => decode_base64($saml_response),
                      key_file    => "SP-Private-Key.pem",    # Required for EncryptedAssertions
                      cacert      => "IdP-cacert.pem",        # Required for EncryptedAssertions
              );

              # ...
      }

DESCRIPTION

Support for the Web Browser SSO profile of SAML2.

Version 0.54 and newer support EncryptedAssertions. No changes required to existing SP applications if EncryptedAssertions are not in use.

Net::SAML2 correctly perform the SSO process against numerous SAML Identity Providers (IdPs). It has been tested against:

Auth0 (requires Net::SAML2 >=0.39)

Azure (Microsoft Office 365)

GSuite (Google)

Jump

Keycloak

MockSAML (https://mocksaml.com/)

Mircosoft ADFS

Okta

OneLogin

PingIdentity (requires Net::SAML2 >=0.54)

SAMLTEST.ID (requires Net::SAML2 >=0.63)

Shibboleth (requires Net::SAML2 >=0.63)

SimpleSAMLphp

DigiD (requires Net::SAML2 >= 0.63)

eHerkenning (requires Net::SAML2 >= 0.73)

eIDAS (requires Net::SAML2 >= 0.73)

MAJOR CAVEATS

SP-side protocol only

Requires XML metadata from the IdP

AUTHORS

• Chris Andrews <chrisa@cpan.org>

• Timothy Legge <timlegge@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2025 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.