Added documentation for the consent module.

git-svn-id: https://simplesamlphp.googlecode.com/svn/trunk@659 44740490-163a-0410-bde0-09ae8108e29a

docs/source/simplesamlphp-advancedfeatures.xml

@@ -425,6 +425,108 @@ foreach($_SERVER as $key=>$value) {
   </section>
 
 
+  <section>
+    <title>Attribute release consent</title>
+
+    <para>simpleSAMLphp can be configured to require the user to give consent
+    before his or her attributes are released to the service provider. The
+    users consent choices can optionally be stored to a database.</para>
+
+    <para>Attribute release consent is enabled on a per-IdP basis by setting
+    the <literal>requireconsent</literal> option in the metadata of the IdP.
+    It is supported by both the SAML 2.0 and Shib 1.3 IdP. This is all you
+    need to do if you don't want to allow simpleSAMLphp to remember the user's
+    consent choices.</para>
+
+    <section>
+      <title>Consent storage setup</title>
+
+      <para>Consent storage requires a database to store the consent
+      information in. Currently, only MySQL is tested and known to work. The
+      consent will be stored in a table named <literal>consent</literal>. This
+      table can be created with the following command:</para>
+
+      <programlisting>CREATE TABLE consent (
+  hashed_user_id varchar(128) NOT NULL,
+  service_id varchar(128) NOT NULL,
+  attribute varchar(128) NOT NULL,
+  consent_date datetime NOT NULL,
+  usage_date datetime NOT NULL,
+  PRIMARY KEY USING BTREE (hashed_user_id, service_id)
+);</programlisting>
+
+      <para>Consent storage is controlled by the following options in
+      <literal>config/config.php</literal>:</para>
+
+      <para><glosslist>
+        <glossentry>
+          <glossterm>consent_usestorage</glossterm>
+
+          <glossdef>
+            <para>Whether the consent storage module should be enabled. Set
+            this to <literal>TRUE</literal> to allow simpleSAMLphp to remember
+            the user's consent choices.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>consent_userid</glossterm>
+
+          <glossdef>
+            <para>This is the name of the attribute which should be used to
+            uniquely identify each user. It is important that the value of the
+            attribute uniquely identifies a single user - otherwise several
+            users will share the same consent information. The default
+            attribute is <literal>eduPersonPrincipalName</literal>.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>consent_salt</glossterm>
+
+          <glossdef>
+            <para>This option should be set to a random valid PHP string. This
+            option is used when hashing values which are stored in the
+            database.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>consent_pdo_connect</glossterm>
+
+          <glossdef>
+            <para>This is the DSN for the database where the consent
+            information is stored. See the
+            <ulink url="http://www.php.net/manual/en/pdo.drivers.php">database
+            driver specific documentation</ulink> in the PHP documentation for
+            information about the syntax. The DSN syntax for the MySQL driver
+            can be found
+            <ulink url="http://www.php.net/manual/en/ref.pdo-mysql.connection.php">
+            here</ulink>.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>consent_pdo_user</glossterm>
+
+          <glossdef>
+            <para>This is the username which should be used when
+            authenticating with the database server.</para>
+          </glossdef>
+        </glossentry>
+
+        <glossentry>
+          <glossterm>consent_pdo_passwd</glossterm>
+
+          <glossdef>
+            <para>This is the password which should be used when
+            authenticating with the database server.</para>
+          </glossdef>
+        </glossentry>
+      </glosslist></para>
+    </section>
+  </section>
+
   <section>
     <title>Support</title>