NAME
    Net::SAML2 - SAML2 bindings and protocol implementation

VERSION
    version 0.64

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.

    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
    Mircosoft ADFS (not recently tested)
    Okta
    OneLogin
    PingIdentity
        Version 0.54 and newer support EncryptedAssertions. No changes
        required to existing SP applications if EncryptedAssertions are not
        in use.

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

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) 2023 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.