Merge branch 'feature/pdometadata' of https://github.com/tdiscuit/simplesamlphp into tdiscuit-feature/pdometadata

2 files changed, 170 insertions, 0 deletions

diff --git a/docs/simplesamlphp-database.txt b/docs/simplesamlphp-database.txt
new file mode 100644
index 0000000..663fdce
--- /dev/null
+++ b/docs/simplesamlphp-database.txt
@@ -0,0 +1,91 @@
+SimpleSAML\Database
+=============================
+
+<!-- 
+	This file is written in Markdown syntax. 
+	For more information about how to use the Markdown syntax, read here:
+	http://daringfireball.net/projects/markdown/syntax
+-->
+
+
+<!-- {{TOC}} -->
+
+Purpose
+-------
+This document covers the SimpleSAML\Database class and is only relevant to anyone writing code for SimpleSAMLphp, including modules, that require a database connection.
+
+The Database class provides a single class that can be used to connect to a database which can be shared by anything within SimpleSAMLphp.
+
+Getting Started
+---------------
+If you are just using the already configured database, which would normally be the case, all you need to do is get the global instance of the Database class.
+
+	$db = SimpleSAML\Database::getInstance();
+
+If there is a requirement to connect to an alternate database server (ex. authenticating users that exist on a different SQL server or database) you can specify an alternate configuration.
+
+	$config = new SimpleSAML_Configuration($myconfigarray, "mymodule/lib/Auth/Source/myauth.php");
+	$db = SimpleSAML\Database::getInstance($config);
+
+That will create a new instance of the database, separate from the global instance, specific to the configuration defined in $myconfigarray. If you are going to specify an alternate config, your configuration array must contain the same keys that exist in the master config (database.dsn, database.username, database.password, database.prefix, etc).
+
+Database Prefix
+---------------
+Administrators can add a prefix to all the table names that this database classes accesses and you should take that in account when querying. Assuming that a prefix has been configured as "sp_":
+
+	$table = $db->applyPrefix("saml20_idp_hosted");
+
+$table would be set to "sp_saml20_idp_hosted"
+
+Querying The Database
+---------------------
+You can query the database through two public functions read() and write() which are fairly self-explanitory when it comes to determining which one to use when querying.
+
+### Writing to The Database
+Since the database class allows administrators to configure master and slave database servers, the write function will always use the master database connection.
+
+The write function takes 2 parameters: SQL, params.
+
+	$table = $db->applyPrefix("test");
+	$values = array(
+		'id' => 20,
+		'data' => 'Some data',
+	);
+	
+	$query = $db->write("INSERT INTO $table (id, data) VALUES (:id, :data)", $values);
+
+The values specified in the $values array will be bound to the placeholders and will be executed on the master. By default, values are binded as PDO::PARAM_STR. If you need to override this, you can specify it in the values array.
+
+	$table = $db->applyPrefix("test");
+	$values = array(
+		'id' => array(20, PDO::PARAM_INT),
+		'data' => 'Some data',
+	);
+	
+	$query = $db->write("INSERT INTO $table (id, data) VALUES (:id, :data)", $values);
+
+You can also skip usage of prepared statements. You should **only** use this if you have a statement that has no user input (ex. CREATE TABLE). If the params variable is explicity set to false, it will skip usage of prepared statements. This is only available when writing to the database.
+
+	$table = $db->applyPrefix("test");
+	$query = $db->write("CREATE TABLE IF NOT EXISTS $table (id INT(16) NOT NULL, data TEXT NOT NULL)", false);
+
+### Reading The Database
+Since the database class allows administrators to configure master and slave database servers, the read function will randomly select a slave server to query. If no slaves are configured, it will read from the master.
+
+The read function takes 2 parameters: SQL, params.
+
+	$table = $db->applyPrefix("test");
+	$values = array(
+		'id' => 20,
+	);
+	
+	$query = $db->read("SELECT * FROM $table WHERE id = :id", $values);
+
+The values specified in the $values array will be bound to the placeholders and will be executed on the selected slave. By default, values are binded as PDO::PARAM_STR. If you need to override this, you can specify it in the values array.
+
+	$table = $db->applyPrefix("test");
+	$values = array(
+		'id' => array(20, PDO::PARAM_INT),
+	);
+	
+	$query = $db->read("SELECT * FROM $table WHERE id = :id", $values);
diff --git a/docs/simplesamlphp-metadata-pdostoragehandler.txt b/docs/simplesamlphp-metadata-pdostoragehandler.txt
new file mode 100644
index 0000000..82656fb
--- /dev/null
+++ b/docs/simplesamlphp-metadata-pdostoragehandler.txt
@@ -0,0 +1,79 @@
+PDO Metadata Storage Handler
+=============================
+
+<!-- 
+	This file is written in Markdown syntax. 
+	For more information about how to use the Markdown syntax, read here:
+	http://daringfireball.net/projects/markdown/syntax
+-->
+
+
+<!-- {{TOC}} -->
+
+Introduction
+------------
+
+If you want to run a clustered SimpleSAMLphp IdP service and you would like to have centralized storage for metadata, you can use the PDO metadata storage handler.
+
+The present document explains how to configure SimpleSAMLphp and your database.
+
+
+
+Preparations
+------------
+
+You will need to have the appropriate PDO drivers for your database and you will have to configure the database section within the config/config.php file.
+
+
+
+Configuring SimpleSAMLphp
+-----------------------------
+
+You will first need to configure a PDO metadata source.
+
+	[root@simplesamlphp simplesamlphp]# vi config/config.php
+
+Here is an example of flatfile plus PDO:
+
+	'metadata.sources' => array(
+		array('type' => 'flatfile'),
+		array('type' => 'pdo'),
+	),
+
+
+
+Initializing the Database
+-------------------------
+
+
+Once you have configured your metadata sources to include a PDO source, you will need to initialize the database. This process will create tables in the database for each type of metadata set (saml20-idp-hosted, saml20-idp-remote, saml20-sp-remote, etc).
+
+	[root@simplesamlphp simplesamlphp]# php bin/initMDSPdo.php
+
+If you connect to your database, you will see 11 new empty tables; one for each metadata set.
+
+
+Adding Metadata
+---------------
+
+With the PDO metadata storage handler, metadata is stored in the table for the appropriate set and is stored in JSON format.
+
+As an example, here is the saml20_idp_hosted table:
+
+entity_id       | entity_data
+----------------|-------------------------------------------------------------------------------------------------------------------------
+`__DEFAULT:1__` | {"host":"\_\_DEFAULT\_\_","privatekey":"idp.key","certificate":"idp.crt","auth":"example-ldap","userid.attribute":"uid"}
+
+Another example is the saml20_idp_remote table:
+
+entity_id                | entity_data
+-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+https://openidp.feide.no | {"name":{"en":"Feide OpenIdP - guest users","no":"Feide Gjestebrukere"},"description":"Here you can login with your account on Feide RnD OpenID. If you do not already have an account on this identity provider, you can create a new one by following the create new account link and follow the instructions.","SingleSignOnService":"https:\/\/openidp.feide.no\/simplesaml\/saml2\/idp\/SSOService.php","SingleLogoutService":"https:\/\/openidp.feide.no\/simplesaml\/saml2\/idp\/SingleLogoutService.php","certFingerprint":"c9ed4dfb07caf13fc21e0fec1572047eb8a7a4cb"}
+
+There is an included script in the `bin` directory that will import all flatfile metadata files and store them in the database, but you can use an external tool to maintain the metadata in the database. This document will only cover adding metadata using the included utility, but the tables above should provide enough information if you would like to create a utility to manage your metadata externally.
+
+To import all flatfile metadata files into the PDO database, run the following script
+
+	[root@simplesamlphp simplesamlphp]# php bin/importPdoMetadata.php
+
+In the event that you import a metadata for an entity id that already exists in the database, it will be overwritten.