Automatically generate README for repo

Author: timlegge

README

@@ -0,0 +1,114 @@
+NAME
+    Net::SAML2
+
+VERSION
+    version 0.34
+
+SYNOPSIS
+      # 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)
+                    );
+
+                    # ...
+            }
+
+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:
+
+    GSuite (Google)
+    Azure (Microsoft Office 365)
+    OneLogin
+    Jump
+    Mircosoft ADFS
+    Keycloak
+
+NAME
+    Net::SAML2 - SAML bindings and protocol implementation
+
+MAJOR CAVEATS
+    SP-side protocol only
+    Requires XML metadata from the IdP
+
+AUTHOR
+    Chris Andrews <chrisandrews@venda.com>
+
+COPYRIGHT
+    The following copyright notice applies to all the files provided in this
+    distribution, including binary files, unless explicitly noted otherwise.
+
+    Copyright 2010, 2011 Venda Ltd.
+
+LICENCE
+    This library is free software; you can redistribute it and/or modify it
+    under the same terms as Perl itself.
+
+AUTHOR
+    Original Author: Chris Andrews <chrisa@cpan.org>
+
+COPYRIGHT AND LICENSE
+    This software is copyright (c) 2021 by Chris Andrews and Others; in
+    detail:
+
+      Copyright 2010-2012  Chris Andrews
+                2016       Jeff Fearn
+                2017       xmikew
+                2019-2021  Timothy Legge
+
+    This is free software; you can redistribute it and/or modify it under
+    the same terms as the Perl 5 programming language system itself.
+

README.md

@@ -38,6 +38,7 @@ exclude_filename = Makefile.PL
 exclude_filename = dev-bin/cpanm
 exclude_match = xt\/testapp\/.*
 exclude_filename = Dockerfile
+exclude_filename = README
 
 [Encoding]
 encoding = bytes
@@ -48,9 +49,10 @@ match = ico
 [CopyFilesFromBuild::Filtered]
 copy = cpanfile
 copy = Makefile.PL
+copy = README
 
 [CopyFilesFromRelease]
-copy = cpanfile, Makefile.PL
+copy = cpanfile, Makefile.PL, README
 
 [AutoPrereqs]
 skip = Saml2Test