Added POD documentation to the code

git-svn-id: https://svn.geant.net/GEANT/edugain_testidp_account_manager/trunk@47 047e039d-479c-447e-8a29-aa6bf4a09bab

bin/account-manager-client.pl

@@ -194,3 +194,56 @@ if ($options{'add_test_account'}) {
     die "Missing arguments";
     
 }
+
+__END__
+
+=head1 NAME
+
+IdPAccountManager::Tools - Command line client to the Test Account manager
+
+=head1 SYNOPSIS
+
+    ./bin/account-manager-client.pl --list_authentication_tokens
+
+=head1 DESCRIPTION
+
+The Test Account manager instanciates test accounts associated to a SAML Identity Provider.
+This script provides a command-line interface for most functions.
+
+=head1 EXAMPLES
+
+=over 8
+
+=item C<account-manager-client.pl --add_test_account --account_profile=student1 --sp_entityid=https://test.federation.renater.fr/test/ressource>
+
+Adds a new test account.
+
+=item C<account-manager-client.pl --list_test_accounts --sp_entityid=https://test.federation.renater.fr/test/ressource --account_profile=student1>
+
+List all test accounts. Criterias can be added to filter test accounts.
+
+=item C<account-manager-client.pl --parse_federation_metadata>
+
+Parses the SAML metadata file, as defined by the C<federation_metadata_file_path> configuration parameter.
+
+=item C<account-manager-client.pl --list_authentication_tokens --sp_entityid=https://test.federation.renater.fr/test/ressource --token=dhj67sjJ>
+
+List all authentication tokens. Criterias can be added to filter tokens.
+
+=item C<account-manager-client.pl --get_authentication_token --token=dhj67sjJ>
+
+Get informations on a token.
+
+=item C<account-manager-client.pl --add_authentication_token --email_address=john@my.fqdn --sp_entityid=https://test.federation.renater.fr/test/ressource>
+
+Adds a new test account.
+
+=item C<account-manager-client.pl --send_notice ----email_address=john@my.fqdn>
+
+Sends a mail notice to the specified email address.
+
+=back
+
+=head1 AUTHOR
+
+Olivier Salaün (olivier.salaun@renater.fr)
\ No newline at end of file

lib/IdPAccountManager/AuthenticationToken.pm

@@ -139,10 +139,93 @@ IdPAccountManager::AuthenticationToken - Manage Authentication tokens used to va
 
 =head1 SYNOPSIS
 
+    my $authentication_token = new IdPAccountManager::AuthenticationToken(token => 'sdfkl4fslkj44');
+    
+    unless ($authentication_token->load()) {
+        die "No corresponding token found in DB\n";
+    }
+    
+    $authentication_token->print();
+
 =head1 DESCRIPTION
 
+The Test Account manager instanciates test accounts associated to a SAML Identity Provider.
+This module allows to manage authentication tokens to validate requestor identity.
+
 =head1 SUBROUTINES/METHODS
 
+=over 8
+
+=item C<new ARGS>
+
+Class method. Create a new IdPAccountManager::AuthenticationToken object.
+Example:
+    
+    my $authentication_token = new IdPAccountManager::AuthenticationToken(token => 'sdfkl4fslkj44');
+
+Supported arguments include:
+
+=over 12
+
+=item C<token>
+
+ID of the token.
+
+=item C<sp_entityid>
+
+EntityID (SAML ID) of the Service Provider associated to the authentication token.
+
+=item C<email_address>
+
+Email address of the user associated to the authentication token.
+
+=back
+
+
+=item C<delete>
+
+Deletes the token in the database.
+
+=item C<get> ATTR_NAME
+
+Returns the value of the specified ATTR_NAME attribute of the token.
+
+=item C<list_authentication_tokens ARGS>
+
+Class method. List all tokens in database.
+
+Supported arguments include:
+
+=over 12
+
+=item C<sp_entityid>
+
+Entityid of a SAML Service Provider to list only tokens linked to this Service Provider.
+
+=item C<token>
+
+ID of the tokens to list only those tokens.
+
+=back
+
+=item C<load>
+
+Loads the token from the database.
+
+=item C<print FD> 
+
+Dumps the content of the authentication token to the specified FD file handler (default to STDOUT)
+
+=item C<set ARGS>
+
+Sets token attributes in ARGS. 
+
+=item C<save>
+
+Save the token in the database.
+
+=back
+
 =head1 AUTHOR
 
 Olivier Salaün (olivier.salaun@renater.fr)

lib/IdPAccountManager/SAMLMetadata.pm

@@ -78,7 +78,7 @@ sub parse {
     return 1;
 }
 
-## Print the content of a test account
+## Dumps the SAML metadata content
 sub print {
     my $self = shift;
     my $fd = shift || \*STDOUT;
@@ -304,14 +304,76 @@ __END__
 
 =head1 NAME
 
-SAMLMetadata - Perl module loading SAML federation metadata
+SAMLMetadata - loading SAML federation metadata
 
 =head1 SYNOPSIS
 
+    my $federation_metadata = new IdPAccountManager::SAMLMetadata;
+    unless ($federation_metadata->load(federation_metadata_file_path => '/tmp/edugain-saml-metadata.xml')) {
+        die;
+    }
+    
+    my %args;
+    if ($options{'sp_entityid'}) {
+        $args{'filter_entity_id'} = $options{'sp_entityid'};
+    }
+
+    unless ($federation_metadata->parse(sp_entityid => 'https://test.federation.renater.fr/test/ressource')) {
+        die;
+    }
+        
+    ## List SAML entities
+    printf "Hashref representing the metadata:\n";
+    &IdPAccountManager::Tools::dump_var($federation_metadata->{'federation_metadata_as_hashref'}, 0, \*STDOUT);
+
 =head1 DESCRIPTION
 
+The Test Account manager instanciates test accounts associated to a SAML Identity Provider.
+This module parses a SAML2 metadata file.
+
 =head1 SUBROUTINES/METHODS
 
+=over 8
+
+=item C<new ARGS>
+
+Class method. Create a new IdPAccountManager::SAMLMetadata object.
+Example:
+    
+    my $federation_metadata = new IdPAccountManager::SAMLMetadata;
+
+=item C<load ARGS>
+
+Loads the SAML metadata file.
+
+Supported arguments include:
+
+=over 12
+
+=item C<federation_metadata_file_path>
+
+Path of the SAML metadata file.
+
+=back
+
+=item C<parse ARGS>
+
+Parse the SAML metadata file.
+
+Supported arguments include:
+
+=over 12
+
+=item C<filter_entity_id>
+
+EntityID of SAML entities to filter.
+
+=back
+
+=item C<print FD> 
+
+Dumps the content of the SAML metadata to the specified FD file handler (default to STDOUT)
+
 =head1 AUTHOR
 
 Olivier Salaün (olivier.salaun@renater.fr)

lib/IdPAccountManager/TestAccount.pm

@@ -146,10 +146,99 @@ IdPAccountManager::TestAccount - Manage test user accounts for the Test Identity
 
 =head1 SYNOPSIS
 
+  my $test_account = new IdPAccountManager::TestAccount(account_profile => 'student1',
+                                                      sp_entityid => 'https://test.federation.renater.fr/test/ressource');
+  unless (defined $test_account) {
+    die "Failed to create test account";
+  }
+    
+  unless ($test_account->save()) {
+    die "Failed to create test account";
+  }
+    
+  printf "Account created:\n\tuserid: user%d\n\tpassword: %s\n", $test_account->get('id'), $test_account->get('user_password');
+
 =head1 DESCRIPTION
 
+The Test Account manager instanciates test accounts associated to a SAML Identity Provider.
+This module allows to manage the test accounts.
+
 =head1 SUBROUTINES/METHODS
 
+=over 8
+
+=item C<new ARGS>
+
+Class method. Create a new IdPAccountManager::TestAccount object.
+Example:
+    
+    my $test_account = new IdPAccountManager::TestAccount(account_profile => 'student1',
+                                                          sp_entityid => 'https://test.federation.renater.fr/test/ressource');
+
+Supported arguments include:
+
+=over 12
+
+=item C<account_profile>
+
+ID of the account profile to be used.
+
+=item C<sp_entityid>
+
+EntityID (SAML ID) of the Service Provider associated to the test account.
+
+=back
+
+=item C<create_test_accounts_for_sp ARGS>
+
+Class method. Create test accounts for supported account profiles.
+
+Supported arguments include:
+
+=over 12
+
+=item C<sp_entityid>
+
+EntityID (SAML ID) of the Service Provider associated to the test account.
+
+=back
+
+=item C<delete>
+
+Deletes the test account in the database.
+
+=item C<get> ATTR_NAME
+
+Returns the value of the specified ATTR_NAME attribute of the test account.
+
+=item C<list_test_accounts ARGS>
+
+Class method. List all test accounts in database.
+
+Supported arguments include:
+
+=over 12
+
+=item C<sp_entityid>
+
+Entityid of a SAML Service Provider to list only test accounts linked to this Service Provider.
+
+=item C<account_profile>
+
+Test account profile to list only test accounts linked based on this profile.
+
+=back
+
+=item C<print FD> 
+
+Dumps the content of the test account to the specified FD file handler (default to STDOUT)
+
+=item C<save>
+
+Save the test account in the database.
+
+=back
+
 =head1 AUTHOR
 
 Olivier Salaün (olivier.salaun@renater.fr)

lib/IdPAccountManager/Tools.pm

@@ -263,14 +263,73 @@ __END__
 
 =head1 NAME
 
-IdPAccountManager::Tools - Set of subroutines usefull for the Account manager
-
-=head1 SYNOPSIS
+IdPAccountManager::Tools - Set of subroutines usefull for the Test Account manager
 
 =head1 DESCRIPTION
 
+The Test Account manager instanciates test accounts associated to a SAML Identity Provider.
+This module gathers a set of usefull subroutines.
+
 =head1 SUBROUTINES/METHODS
 
+=over 8
+
+=item C<dump_var ($var, $level, $fd)>
+
+Dumps a complex perl data structure. $var is a reference to the variable to dump. $level should be set to 0 (subroutine called recursively). $fd is the file descriptor for the output (default is STDOUT). 
+
+=item C<do_log ($level, $message)>
+
+Write $message to the log file. $level sets the log level (debug, info, trace, notice, error).
+
+=item C<encode_utf8 ($string)>
+
+Return a UTF8 encoded version of $string.
+
+=item C<escape_xml ($string)>
+
+Escape XML chars in $string.
+
+=item C<generate_password>
+
+Returns a random password following some security guidelines.
+
+=item C<mail_notice (ARGS)>
+
+Send a mail notice.
+
+Supported arguments include:
+
+=over 12
+
+=item C<template>
+
+TT2 mail template to parse.
+
+=item C<to>
+
+Destination email address.
+
+=item C<data>
+
+A hashref with parameters used to parse the mail template.
+
+=back
+
+=item C<qencode ($string)>
+
+Retunrs a Q-encoded version of $string.
+
+=item C<sha256_hash ($string)>
+
+Returns a SHA256 hash for $string.
+
+=item C<update_ssp_authsources>
+
+Update simpleSAMLphp authsources.php configuration file with the currently valid test accounts.
+
+=back
+
 =head1 AUTHOR
 
 Olivier Salaün (olivier.salaun@renater.fr)