Merge pull request #106 from waterkip/GH-docs-for_release

Documentation updates

Author: waterkip

lib/Net/SAML2/Binding/Redirect.pm

@@ -55,16 +55,19 @@ Arguments:
 The SP's (Service Provider) also known as your application's signing key
 that your application uses to sign the AuthnRequest.  Some IdPs may not
 verify the signature.
+Required with B<param> being C<SAMLRequest>.
 
 =item B<cert>
 
 IdP's (Identity Provider's) certificate that is used to verify a signed
 Redirect from the IdP.  It is used to verify the signature of the Redirect
 response.
+Required with B<param> being C<SAMLResponse>.
 
 =item B<url>
 
 IdP's SSO (Single Sign Out) service url for the Redirect binding
+Required with B<param> being C<SAMLRequest>.
 
 =item B<param>
 
@@ -150,10 +153,9 @@ sub BUILD {
         croak("Need to have an URL specified") unless $self->has_url;
         croak("Need to have a key specified") unless $self->has_key;
     }
-    if ($self->param eq 'SAMLResponse') {
+    elsif ($self->param eq 'SAMLResponse') {
         croak("Need to have a cert specified") unless $self->has_cert;
     }
-    # other params don't need to have these per-se
 }
 
 # BUILDARGS

lib/Net/SAML2/Binding/SOAP.pm

@@ -11,10 +11,6 @@ with 'Net::SAML2::Role::VerifyXML';
 
 # ABSTRACT: Net::SAML2::Binding::SOAP - SOAP binding for SAML
 
-=head1 NAME
-
-Net::SAML2::Binding::SOAP - SOAP binding for SAML2
-
 =head1 SYNOPSIS
 
   my $soap = Net::SAML2::Binding::SOAP->new(

lib/Net/SAML2/Protocol/ArtifactResolve.pm

@@ -15,17 +15,26 @@ Net::SAML2::Protocol::ArtifactResolve - ArtifactResolve protocol class.
 
 =head1 SYNOPSIS
 
-  my $resolver = Net::SAML2::Binding::ArtifactResolve->new(
-    issuer => 'http://localhost:3000',
-  );
+    my $resolver = Net::SAML2::Protocol::ArtifactResolve->new(
+        artifact    => 'yourartifact',
+        destination => $idp->art_url('urn:oasis:names:tc:SAML:2.0:bindings:SOAP'), # https://idp.example.net/idp
+        issuer      => $sp->id, # https://you.example.com/auth/saml
+    );
 
-  my $response = $resolver->resolve(params->{SAMLart});
+    my $binding = Net::SAML2::Binding::SOAP->new(...);
+    $binding->request($resolved->as_xml);
 
 =head1 METHODS
 
 =cut
 
-=head2 new( ... )
+=head2 new(%args)
+
+    my $resolver = Net::SAML2::Protocol::ArtifactResolve->new(
+        artifact    => 'yourartifact',
+        destination => $idp->art_url('urn:oasis:names:tc:SAML:2.0:bindings:SOAP'), # https://idp.example.net/idp
+        issuer      => $sp->id, # https://you.example.com/auth/saml
+    );
 
 Constructor. Returns an instance of the ArtifactResolve request for
 the given issuer and artifact.
@@ -36,16 +45,20 @@ Arguments:
 
 =item B<issuer>
 
-issuing SP's identity URI
+Issuing SP's identity URI
 
 =item B<artifact>
 
-artifact to be resolved
+Artifact to be resolved
 
 =item B<destination>
 
 IdP's identity URI
 
+=item B<provider>
+
+IdP's provider name
+
 =back
 
 =cut
@@ -60,14 +73,14 @@ has 'provider' => (
     predicate => 'has_provider',
 );
 
-=head2 as_xml( )
+=head2 as_xml()
 
 Returns the ArtifactResolve request as XML.
 
 =cut
 
 sub as_xml {
-    my ($self) = @_;
+    my $self = shift;
 
     my $x = XML::Generator->new(':pretty');
     my $saml  = ['saml' => URN_ASSERTION ];

lib/Net/SAML2/Protocol/LogoutRequest.pm

@@ -11,10 +11,6 @@ with 'Net::SAML2::Role::ProtocolMessage';
 
 # ABSTRACT: SAML2 LogoutRequest Protocol object
 
-=head1 NAME
-
-Net::SAML2::Protocol::LogoutRequest - the SAML2 LogoutRequest object
-
 =head1 SYNOPSIS
 
   my $logout_req = Net::SAML2::Protocol::LogoutRequest->new(
@@ -36,24 +32,41 @@ Arguments:
 
 =item B<session>
 
-session to log out
+Session to log out
 
 =item B<nameid>
 
 NameID of the user to log out
 
+=item B<destination>
+
+IdP's identity URI this is required for a signed message but likely should be
+sent regardless
+
+=back
+
+The following options alter the output of the NameID element
+
+=over
+
 =item B<nameid_format>
 
-NameIDFormat to specify
+When supplied adds the Format attribute to the NameID
 
-=item B<issuer>
+=item B<sp_provided_id>
 
-SP's identity URI
+When supplied adds the SPProvidedID attribute to the NameID
 
-=item B<destination>
+=item B<include_name_qualifier>
 
-IdP's identity URI this is required for a signed message but likely should be
-sent regardless
+Tell the module to include the NameQualifier and SPNameQualifier attributes in
+the NameID. Defaults to false unless the B<nameid_format> equals
+C<urn:oasis:names:tc:SAML:2.0:nameidformat:persistent>
+
+=item B<affiliation_group_id>
+
+When supplied sets the SPNameQualifier attribute. When not supplied, this
+defaults to the issuer.
 
 =back
 

lib/Net/SAML2/SP.pm

@@ -46,23 +46,27 @@ Arguments:
 
 =item B<url>
 
-base for all SP service URLs
+Base for all SP service URLs
+
+=item B<error_url>
+
+The error URI. Can be relative to the base URI or a regular URI
 
 =item B<id>
 
 SP's identity URI.
 
 =item B<cert>
 
-path to the signing certificate
+Path to the signing certificate
 
 =item B<key>
 
-path to the private key for the signing certificate
+Path to the private key for the signing certificate
 
 =item B<cacert>
 
-path to the CA certificate for verification
+Path to the CA certificate for verification
 
 =item B<org_name>