From 5e7bd9878d6ced76a8adf7468628f6f3d4e9503e Mon Sep 17 00:00:00 2001
From: Chris Andrews <chrisandrews@venda.com>
Date: Oct 04 2010 12:34:36 +0000
Subject: Add a synopsis and note the caveats in this version.


---

diff --git a/Changes b/Changes
index 96518e5..de92992 100644
--- a/Changes
+++ b/Changes
@@ -1,4 +1,7 @@
 Revision history for Perl extension Net::SAML2.
 
-0.01  Mon  4 Oct 2010 12:47:56 BST
+0.01_01  Mon  4 Oct 2010 12:47:56 BST
       Initial version. 
+
+      This version will correctly perform Web Browser SSO, but
+      with caveats. See the embedded documentation for details. 
diff --git a/lib/Net/SAML2.pm b/lib/Net/SAML2.pm
index cdbd61b..8d068a8 100644
--- a/lib/Net/SAML2.pm
+++ b/lib/Net/SAML2.pm
@@ -13,6 +13,59 @@ Net::SAML2 - SAML bindings and protocol implementation
 
 =head1 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,
+        )->as_xml;
+
+        my $redirect = Net::SAML2::Binding::Redirect->new(
+                key => 'sign-nopw-cert.pem',
+                url => $sso_url,
+        );
+
+        my $url = $redirect->sign_request($authnreq);
+
+  # 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(
+                        xml => decode_base64($saml_response)
+                );
+
+                # ...
+        }
+
+=head1 DESCRIPTION
+
+Support for the Web Browser SSO profile of SAML2. 
+
+This is a very early release, but one which will correctly perform the
+SSO process.
+
+=head1 MAJOR CAVEATS
+
+=over
+
+=item SP-side protocol only
+
+=item No verification of the signer of received Assertions
+
+=item Limited handling of protocol / network errors
+
+=item Requires XML metadata from the IdP
+
+=back
+
 =cut
 
 # entities
@@ -41,7 +94,7 @@ The following copyright notice applies to all the files provided in
 this distribution, including binary files, unless explicitly noted
 otherwise.
 
-Copyright 2010 Venda Ltd
+Copyright 2010 Venda Ltd.
 
 =head1 LICENCE