From 0fd8403715f9932bd12c832107062cd33bfa12cd Mon Sep 17 00:00:00 2001
From: "renater.salaun" <renater.salaun@047e039d-479c-447e-8a29-aa6bf4a09bab>
Date: Tue, 28 Oct 2014 16:11:25 +0000
Subject: [PATCH] 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 | 53 ++++++++++++
lib/IdPAccountManager/AuthenticationToken.pm | 83 ++++++++++++++++++
lib/IdPAccountManager/SAMLMetadata.pm | 66 ++++++++++++++-
lib/IdPAccountManager/TestAccount.pm | 89 ++++++++++++++++++++
lib/IdPAccountManager/Tools.pm | 65 +++++++++++++-
5 files changed, 351 insertions(+), 5 deletions(-)
diff --git a/bin/account-manager-client.pl b/bin/account-manager-client.pl
index 0d3cbf4..fb8c0c0 100755
--- a/bin/account-manager-client.pl
+++ b/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
diff --git a/lib/IdPAccountManager/AuthenticationToken.pm b/lib/IdPAccountManager/AuthenticationToken.pm
index 4399f38..f26d3c6 100644
--- a/lib/IdPAccountManager/AuthenticationToken.pm
+++ b/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)
diff --git a/lib/IdPAccountManager/SAMLMetadata.pm b/lib/IdPAccountManager/SAMLMetadata.pm
index 8ca6632..cfddbb1 100644
--- a/lib/IdPAccountManager/SAMLMetadata.pm
+++ b/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)
diff --git a/lib/IdPAccountManager/TestAccount.pm b/lib/IdPAccountManager/TestAccount.pm
index b052b83..f36e784 100644
--- a/lib/IdPAccountManager/TestAccount.pm
+++ b/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)
diff --git a/lib/IdPAccountManager/Tools.pm b/lib/IdPAccountManager/Tools.pm
index 190e44d..9972b74 100644
--- a/lib/IdPAccountManager/Tools.pm
+++ b/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)
--
GitLab