From fb94bc5d1fde9e8cf5ce7400193ce1c1ca32bdf3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andreas=20=C3=85kre=20Solberg?= <andreas.solberg@uninett.no>
Date: Fri, 14 Mar 2008 09:58:07 +0000
Subject: [PATCH] Update to documentation
git-svn-id: https://simplesamlphp.googlecode.com/svn/trunk@414 44740490-163a-0410-bde0-09ae8108e29a
---
.../source/simplesamlphp-advancedfeatures.xml | 163 +++++++++-
docs/source/simplesamlphp-googleapps.xml | 56 +++-
docs/source/simplesamlphp-idp.xml | 119 +++++---
docs/source/simplesamlphp-install.xml | 77 ++++-
docs/source/simplesamlphp-maintenance.xml | 288 +++++++++++-------
docs/source/simplesamlphp-sp.xml | 119 +++++---
6 files changed, 606 insertions(+), 216 deletions(-)
diff --git a/docs/source/simplesamlphp-advancedfeatures.xml b/docs/source/simplesamlphp-advancedfeatures.xml
index 055f66077..35ddf1c52 100644
--- a/docs/source/simplesamlphp-advancedfeatures.xml
+++ b/docs/source/simplesamlphp-advancedfeatures.xml
@@ -41,43 +41,176 @@
<section>
<title>Attribute control</title>
- <para></para>
+ <para>You have several options if you want control what attributes are
+ sent to services. in this section functionality around filtering and
+ modification of attributes are discussed.</para>
<section>
<title>Attribute filtering</title>
- <para></para>
+ <para>Attribute filtering lets you configure an array of attribute names
+ that are sent to each service. This option is placed in the service
+ provider metadata files.</para>
+
+ <para>On a Shibboleth or SAML 2.0 SimpleSAMLphp IdP, look at the
+ <filename>shib13-sp-remote.php</filename> or
+ <filename>saml20-sp-remote.php</filename> metadata file. Here you
+ optionally can add a parameter called <literal>attributes</literal>. If
+ you do not include this parameter, all available attributes will be sent
+ by default. Adding an array of attributes to this parameter, limits the
+ attributes sent to match this list. </para>
+
+ <example>
+ <title>Example of attribute filtering</title>
+
+ <para>Here is a metadata entry for a remote SP that will only receive
+ two attributes:</para>
+
+ <programlisting>'dev.andreas.feide.no' => array(
+ 'AssertionConsumerService' => 'http://dev.andreas.feide.no/simplesaml/saml2/sp/AssertionConsumerService.php',
+ 'SingleLogoutService' => 'http://dev.andreas.feide.no/simplesaml/saml2/sp/SingleLogoutService.php',
+ 'attributes' => array('eduPersonPrincipalName', 'mail'),
+),</programlisting>
+ </example>
</section>
<section>
<title>Attribute name mapping</title>
- <para></para>
- </section>
+ <para>You can configure a mapping table with attribute names that are
+ transformed into another name. This is particularly useful whe bridging
+ between different federations.</para>
- <section>
- <title>Attribute alter functions</title>
+ <para>To define a new attribute name mapping table, give it a name,
+ f.ex. <literal>feide2edugain</literal>. Then you create a new file in
+ <filename>attributemap/feide2edugain.php</filename>. This file shuold
+ have a syntax like this:</para>
- <para></para>
+ <programlisting><?php
- <example>
- <title>Example of alter script</title>
+$attributemap = array(
+ 'mobile' => 'urn:mace:dir:attribute-def:mobile'
+);
- <para>This example injects a realm attribute that is generated from
- the eduPersonPrincipalName.</para>
+?>
+</programlisting>
- <programlisting>function attributealter_realm(&$attributes, $spentityid = null, $idpentityid = null) {
+ <para>Next, you need to configure where to apply this mapping. There is
+ a parameter called <literal>attributemap</literal>, which you can add to
+ either the IdP hosted metadata or the SP remote metadata. This parameter
+ can be set to a name of a mapping table.</para>
- if (array_key_exists('eduPersonPrincipalName', $attributes)) {
- $eduppn = $attributes['eduPersonPrincipalName'][0];
+ <example>
+ <title>Example of attribute mapping</title>
+
+ <para>Here is an example of saml20-idp-hosted.php:</para>
+
+ <programlisting>'test.andreas.feide.no' => array(
+ 'host' => 'dev2.andreas.feide.no',
+ 'privatekey' => 'googleappsidp.pem',
+ 'certificate' => 'googleappsidp.crt',
+ 'auth' => 'auth/login.php',
+
+ 'attributemap' => 'feide2edugain'
+),</programlisting>
+
+ <para>This will process the attributemap
+ <literal>feide2edugain</literal> for all SPs that connects to the SAML
+ 2.0 IdP <literal>test.andreas.feide.no</literal>. Alternatively the
+ parameter can be configured to the SP remote metadata, where it will
+ be processed for that specific SP only.</para>
+ </example>
+ </section>
+
+ <section>
+ <title>Attribute alter functions</title>
+
+ <para>You can implement your own attribute function that filter,
+ injects, modifies or removes attributes. You shuold give your attribute
+ alter function a name, in example we can create an attribute alter
+ functions that take the last part of the eduPersonPrincipalName
+ attribute (the part after <literal>@</literal>, f.ex.
+ <literal>uninett.no</literal> in <literal>andreas@uninett.no</literal>),
+ and add this part as a new attribute with the name
+ <literal>realm</literal>. Let us call this attribute alter function for
+ <literal>realm</literal>. Then we create this function in the attribute
+ alter function file:
+ <filename>attributealter/alterfunctions.php</filename>. We the function
+ will have the name of the attribute alter function, but prefixed with
+ <literal>attributealter_</literal>, so we end up with:
+ <literal>attributealter_realm</literal>. The method signature should
+ be:</para>
+
+ <programlisting>function attributealter_realm(&$attributes, $spentityid = null, $idpentityid = null) {</programlisting>
+
+ <para>We see that we get a reference to the attributes array. This array
+ contains all the other attributes, and we can add new attributes into
+ this array that will be sent to the service. We also get the entity ID
+ of the SP and the IdP.</para>
+
+ <para>Here is the full example function:</para>
+
+ <programlisting>function attributealter_realm(&$attributes, $spentityid = null, $idpentityid = null) {
+
+ $attributename = 'eduPersonPrincipalName';
+ if (array_key_exists($attributename, $attributes)) {
+ $eduppn = $attributes[$attributename][0];
$splitted = explode('@', $eduppn);
if (count($splitted) > 1) {
$attributes['realm'] = array($splitted[1]);
+ } else {
+ SimpleSAML_Logger::debug('attributealter_realm: Wrong format on ' . $attributename . ' (not including @)');
}
+ } else {
+ SimpleSAML_Logger::debug('attributealter_realm: Could not find ' . $attributename);
}
}</programlisting>
- </example>
+
+ <itemizedlist>
+ <listitem>
+ <para><ulink
+ url="https://ow.feide.no/simplesamlphp:alterfunctions">This wiki
+ page on the simpleSAMLphp wiki page is supposed to hold several
+ example attribute alter functions for inspiration for
+ others</ulink>. Please contribute with your attribute alter
+ functions to this page. Contact Andreas, if you have not access to
+ the wiki and want to add some examples.</para>
+ </listitem>
+ </itemizedlist>
</section>
</section>
+
+ <section>
+ <title>Support</title>
+
+ <para>If you have problems to get this work, or want to discuss
+ simpleSAMLphp with other users of the software you are lucky! Around
+ simpleSAMLphp there is a great Open source community, and you are welcome
+ to join! Both for asking question, answer other questions, request
+ improvements or contribute with code or plugins of your own.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><ulink url="http://rnd.feide.no/simplesamlphp">simpleSAMLphp
+ homepage (at Feide RnD)</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="http://rnd.feide.no/view/simplesamlphpdocs">List of
+ all available simpleSAMLphp documentation</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="http://rnd.feide.no/content/simplesamlphp-users-mailinglist">Join
+ the simpleSAMLphp user's mailing list</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="https://ow.feide.no/simplesamlphp:start">Visit and
+ contribute to the simpleSAMLphp wiki</ulink></para>
+ </listitem>
+ </itemizedlist>
+ </section>
</article>
\ No newline at end of file
diff --git a/docs/source/simplesamlphp-googleapps.xml b/docs/source/simplesamlphp-googleapps.xml
index ef05f4d88..b4b20a380 100644
--- a/docs/source/simplesamlphp-googleapps.xml
+++ b/docs/source/simplesamlphp-googleapps.xml
@@ -8,7 +8,7 @@
<articleinfo>
<date>2007-10-15</date>
- <pubdate>Sat Mar 8 22:40:15 2008</pubdate>
+ <pubdate>Fri Mar 14 10:38:52 2008</pubdate>
<author>
<firstname>Andreas Ă…kre</firstname>
@@ -32,6 +32,18 @@
<literallayout>dev2.andreas.feide.no</literallayout>
</section>
+ <section>
+ <title>Enabling the Identity Provider functionality</title>
+
+ <para>Edit <filename>config.php</filename>, and enable the SAML 2.0
+ IdP:</para>
+
+ <programlisting>'enable.saml20-sp' => false,
+'enable.saml20-idp' => true,
+'enable.shib13-sp' => false,
+'enable.shib13-idp' => false,</programlisting>
+ </section>
+
<section>
<title>Setting up a SSL signing certificate</title>
@@ -115,6 +127,15 @@ An optional company name []:</screen>
</glossdef>
</glossentry>
+ <glossentry>
+ <glossterm>auth/login-feide.php</glossterm>
+
+ <glossdef>
+ <para>A multi-LDAP module which looks up the users in LDAP first
+ searching for <literal>eduPersonPrincipalName</literal>.</para>
+ </glossdef>
+ </glossentry>
+
<glossentry>
<glossterm>auth/login-radius.php</glossterm>
@@ -135,6 +156,15 @@ An optional company name []:</screen>
<para>This module is not completed yet. Work in progress.</para>
</glossdef>
</glossentry>
+
+ <glossentry>
+ <glossterm>auth/login-cas-ldap.php</glossterm>
+
+ <glossdef>
+ <para>Authentication via CAS. Then look up attributes via
+ LDAP.</para>
+ </glossdef>
+ </glossentry>
</glosslist>
<section>
@@ -433,7 +463,27 @@ An optional company name []:</screen>
to join! Both for asking question, answer other questions, request
improvements or contribute with code or plugins of your own.</para>
- <para>Visit the project page of simpleSAMLphp at: <ulink
- url="http://code.google.com/p/simplesamlphp/">http://code.google.com/p/simplesamlphp/</ulink></para>
+ <itemizedlist>
+ <listitem>
+ <para><ulink url="http://rnd.feide.no/simplesamlphp">simpleSAMLphp
+ homepage (at Feide RnD)</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="http://rnd.feide.no/view/simplesamlphpdocs">List of
+ all available simpleSAMLphp documentation</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="http://rnd.feide.no/content/simplesamlphp-users-mailinglist">Join
+ the simpleSAMLphp user's mailing list</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="https://ow.feide.no/simplesamlphp:start">Visit and
+ contribute to the simpleSAMLphp wiki</ulink></para>
+ </listitem>
+ </itemizedlist>
</section>
</article>
\ No newline at end of file
diff --git a/docs/source/simplesamlphp-idp.xml b/docs/source/simplesamlphp-idp.xml
index 963f2f73c..58abcf568 100644
--- a/docs/source/simplesamlphp-idp.xml
+++ b/docs/source/simplesamlphp-idp.xml
@@ -7,7 +7,7 @@
<articleinfo>
<date>2007-10-15</date>
- <pubdate>Thu Mar 13 22:22:51 2008</pubdate>
+ <pubdate>Fri Mar 14 10:39:22 2008</pubdate>
<author>
<firstname>Andreas Ă…kre</firstname>
@@ -18,6 +18,20 @@
</author>
</articleinfo>
+ <section>
+ <title>Enabling the Identity Provider functionality</title>
+
+ <para>The SAML 2.0 SP functionality is enabled per default. Edit
+ <filename>config.php</filename>, and enable either the SAML 2.0 IdP or the
+ Shib 1.3 IdP, depending on your needs. Here is an example of SAML 2.0 IdP
+ enabled:</para>
+
+ <programlisting>'enable.saml20-sp' => false,
+'enable.saml20-idp' => true,
+'enable.shib13-sp' => false,
+'enable.shib13-idp' => false,</programlisting>
+ </section>
+
<section>
<title>Authentication modules</title>
@@ -35,8 +49,7 @@
<glossdef>
<para>This is the standard LDAP backend authentication module, it
- uses LDAP configuration from the <filename>config/ldap.php</filename>
- file.</para>
+ uses LDAP configuration from the config.php file.</para>
</glossdef>
</glossentry>
@@ -50,6 +63,15 @@
</glossdef>
</glossentry>
+ <glossentry>
+ <glossterm>auth/login-feide.php</glossterm>
+
+ <glossdef>
+ <para>A multi-LDAP module which looks up the users in LDAP first
+ searching for <literal>eduPersonPrincipalName</literal>.</para>
+ </glossdef>
+ </glossentry>
+
<glossentry>
<glossterm>auth/login-radius.php</glossterm>
@@ -70,6 +92,15 @@
<para>This module is not completed yet. Work in progress.</para>
</glossdef>
</glossentry>
+
+ <glossentry>
+ <glossterm>auth/login-cas-ldap.php</glossterm>
+
+ <glossdef>
+ <para>Authentication via CAS. Then look up attributes via
+ LDAP.</para>
+ </glossdef>
+ </glossentry>
</glosslist>
<section>
@@ -80,7 +111,7 @@
<para>If you want to perform local authentication on this server, and
you want to use the LDAP authenticaiton plugin, then you need to
configure the following parameters in
- <filename>config/ldap.php</filename>:</para>
+ <filename>config.php</filename>:</para>
<itemizedlist>
<listitem>
@@ -99,14 +130,6 @@
LDAP. What attributes should be extracted?
<literal>objectclass=*</literal> gives you all.</para>
</listitem>
-
- <listitem>
- <para><literal>auth.ldap.enable_tls</literal>: Enable TLS for
- the connection to the LDAP server. The default is
- <literal>false</literal></para>
- </listitem>
-
-
</itemizedlist>
</section>
@@ -140,7 +163,7 @@
</warning>
<para>Here is an examples of openssl commands to generate a new key and a
- self-signed certificate to use for signing SAML messages:</para>
+ selfsigned certificate to use for signing SAML messages:</para>
<screen>openssl genrsa -des3 -out server2.key 1024
openssl rsa -in server2.key -out server2.pem
@@ -172,14 +195,14 @@ openssl x509 -req -days 60 -in server2.csr -signkey server2.key -out server2.crt
'idp.example.org' => array(
// The hostname of the server (VHOST) that this SAML entity will use.
- 'host' => 'sp.example.org',
+ 'host' => 'sp.example.org',
// X.509 key and certificate. Relative to the cert directory.
- 'privatekey' => 'server.pem',
- 'certificate' => 'server.crt',
+ 'privatekey' => 'server.pem',
+ 'certificate' => 'server.crt',
// Authentication plugin to use. login.php is the default one that uses LDAP.
- 'auth' => 'auth/login.php',
+ 'auth' => 'auth/login.php',
'authority' => 'login',
),</programlisting>
@@ -202,9 +225,7 @@ openssl x509 -req -days 60 -in server2.csr -signkey server2.key -out server2.crt
<glossterm>host</glossterm>
<glossdef>
- <para>The hostname of the server running this IdP. This hostname
- is used to determine which IdP the user is accessing and must
- match the domain name the user uses to access your IdP.</para>
+ <para>The hostname of the server running this IdP.</para>
</glossdef>
</glossentry>
@@ -246,8 +267,8 @@ openssl x509 -req -days 60 -in server2.csr -signkey server2.key -out server2.crt
<glossterm>requireconsent</glossterm>
<glossdef>
- <para>Set to true if you want to require the user's consent
- before sending attributes to an SP.</para>
+ <para>Set to true if you want to require user's consent each
+ time attributes are sent to an SP.</para>
</glossdef>
</glossentry>
@@ -256,8 +277,7 @@ openssl x509 -req -days 60 -in server2.csr -signkey server2.key -out server2.crt
<glossdef>
<para>Who is authorized to create sessions for this IdP. Can be
- <literal>login</literal> for LDAP login module, or
- <literal>saml2</literal> for SAML 2.0 SP. It is
+ login for LDAP login module, or saml2 for SAML 2.0 SP. It is
highly reccomended to set this parameter.</para>
</glossdef>
</glossentry>
@@ -278,7 +298,7 @@ openssl x509 -req -days 60 -in server2.csr -signkey server2.key -out server2.crt
<glossdef>
<para>You can implement custom functions that injects or
modifies attributes. Here you can specify an array of such
- functions. Read more in the advances features document.</para>
+ fuctions. Read more in the advances features document.</para>
</glossdef>
</glossentry>
</glosslist>
@@ -296,10 +316,9 @@ openssl x509 -req -days 60 -in server2.csr -signkey server2.key -out server2.crt
<glossterm>request.signing</glossterm>
<glossdef>
- <para>A boolean value which should be <literal>true</literal>
- or <literal>false</literal>. Default is <literal>false</literal>.
- To turn on signing authentication requests, set this flag
- to <literal>true</literal>.</para>
+ <para>A boolean value, that should be true or false. Default is
+ false. To turn on signing authentication requests, set this flag
+ to true.</para>
</glossdef>
</glossentry>
</glosslist>
@@ -374,12 +393,7 @@ openssl x509 -req -days 60 -in server2.csr -signkey server2.key -out server2.crt
<glossterm>NameIDFormat</glossterm>
<glossdef>
- <para>The format of the NameID sent to this SP. The default is
- <literal>'urn:oasis:names:tc:SAML:2.0:nameid-format:transient'</literal>.
- It could also be set to
- <literal>'urn:oasis:names:tc:SAML:2.0:nameid-format:email'</literal>
- to use the email name format. No other name formats are
- currently supported by simpleSAMLphp.</para>
+ <para>Set it to the default: transient.</para>
</glossdef>
</glossentry>
@@ -405,9 +419,11 @@ openssl x509 -req -days 60 -in server2.csr -signkey server2.key -out server2.crt
<glossterm>simplesaml.nameidattribute</glossterm>
<glossdef>
- <para>This is the name of the attribute simpleSAMLphp will use
- as the email address if email is selected as the
- NameIDFormat.</para>
+ <para>If the NameIDFormat is set to email, then the email
+ address will be retrieved from the attribute with this name. In
+ example, the simplesaml.nameidattribute can be set to uid, and
+ then the authentcation module sets an attribute with name uid.
+ The value of this attribute will be set as the NameID.</para>
</glossdef>
</glossentry>
@@ -522,11 +538,28 @@ openssl x509 -req -days 60 -in server2.csr -signkey server2.key -out server2.crt
to join! Both for asking question, answer other questions, request
improvements or contribute with code or plugins of your own.</para>
- <para>Go to simpleSAMLphp homepage: <ulink
- url="http://rnd.feide.no/simplesamlphp">http://rnd.feide.no/simplesamlphp</ulink></para>
-
- <para>And please join the mailinglist: <ulink
- url="http://rnd.feide.no/content/simplesamlphp-users-mailinglist">http://rnd.feide.no/content/simplesamlphp-users-mailinglist</ulink></para>
+ <itemizedlist>
+ <listitem>
+ <para><ulink url="http://rnd.feide.no/simplesamlphp">simpleSAMLphp
+ homepage (at Feide RnD)</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="http://rnd.feide.no/view/simplesamlphpdocs">List of
+ all available simpleSAMLphp documentation</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="http://rnd.feide.no/content/simplesamlphp-users-mailinglist">Join
+ the simpleSAMLphp user's mailing list</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="https://ow.feide.no/simplesamlphp:start">Visit and
+ contribute to the simpleSAMLphp wiki</ulink></para>
+ </listitem>
+ </itemizedlist>
</section>
<appendix>
diff --git a/docs/source/simplesamlphp-install.xml b/docs/source/simplesamlphp-install.xml
index e59340bbc..a79be7e8a 100644
--- a/docs/source/simplesamlphp-install.xml
+++ b/docs/source/simplesamlphp-install.xml
@@ -7,7 +7,7 @@
<articleinfo>
<date>2007-08-30</date>
- <pubdate>Tue Mar 11 21:00:08 2008</pubdate>
+ <pubdate>Fri Mar 14 10:39:49 2008</pubdate>
<author>
<firstname>Andreas Ă…kre</firstname>
@@ -234,7 +234,48 @@ cp -r metadata-templates/*.php metadata/
</listitem>
<listitem>
- <para></para>
+ <para><ulink
+ url="http://rnd.feide.no/content/simplesamlphp-advanced-features">Advanced
+ simpleSAMLphp features</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="http://rnd.feide.no/content/simplesamlphp-maintenance-and-configuration">simpleSAMLphp
+ maintenance and configuration</ulink></para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Support</title>
+
+ <para>If you have problems to get this work, or want to discuss
+ simpleSAMLphp with other users of the software you are lucky! Around
+ simpleSAMLphp there is a great Open source community, and you are welcome
+ to join! Both for asking question, answer other questions, request
+ improvements or contribute with code or plugins of your own.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><ulink url="http://rnd.feide.no/simplesamlphp">simpleSAMLphp
+ homepage (at Feide RnD)</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="http://rnd.feide.no/view/simplesamlphpdocs">List of
+ all available simpleSAMLphp documentation</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="http://rnd.feide.no/content/simplesamlphp-users-mailinglist">Join
+ the simpleSAMLphp user's mailing list</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="https://ow.feide.no/simplesamlphp:start">Visit and
+ contribute to the simpleSAMLphp wiki</ulink></para>
</listitem>
</itemizedlist>
</section>
@@ -242,17 +283,35 @@ cp -r metadata-templates/*.php metadata/
<appendix id="sect.altlocations">
<title>Installing simpleSAMLphp in alternative locations</title>
- <para>If you want to install simpleSAMLphp in an alternative directory,
- feel free to do so. You need to set the path of the installation directory
- in the config.php file:</para>
+ <para>You can spit the <literal>www</literal> folder in simpleSAMLphp from
+ the installation directory. You need to set the path of the installation
+ directory in the <filename>config.php</filename> file:</para>
- <programlisting>$config = array (
-[...]
- 'basedir' => '/usr/local/simplesaml/simplesamlphp',</programlisting>
+ <programlisting> 'basedir' => '/usr/local/simplesaml/simplesamlphp',</programlisting>
<para>And you also need to modify the Alias directive in the apache
configuration:</para>
- <programlisting> Alias /simplesaml /usr/local/simplesaml/simplesamlphp/www</programlisting>
+ <programlisting> Alias /simplesaml /usr/local/simplesaml/simplesamlphp/www</programlisting>
+
+ <para>You also need to change the path of the <literal>require_once(...
+ _include.php )</literal> line in the examples and in your integration
+ code.</para>
+
+ <para>Normally you would not want to do it this way, but one example is if
+ you must install simpleSAMLphp in your home directory, and you would like
+ the following directory structure:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><filename>~/simplesamlphp</filename></para>
+ </listitem>
+
+ <listitem>
+ <para><filename>~/publichtml/simplesaml</filename> where simplesaml is
+ the <filename>www</filename> directory from simplesamlphp installation
+ directory, either moved or a symlink.</para>
+ </listitem>
+ </itemizedlist>
</appendix>
</article>
\ No newline at end of file
diff --git a/docs/source/simplesamlphp-maintenance.xml b/docs/source/simplesamlphp-maintenance.xml
index b46a03823..359a1411d 100644
--- a/docs/source/simplesamlphp-maintenance.xml
+++ b/docs/source/simplesamlphp-maintenance.xml
@@ -7,7 +7,7 @@
<articleinfo>
<date>2007-08-30</date>
- <pubdate>Sat Mar 8 22:40:37 2008</pubdate>
+ <pubdate>Fri Mar 14 09:53:04 2008</pubdate>
<author>
<firstname>Andreas Ă…kre</firstname>
@@ -18,6 +18,10 @@
</author>
</articleinfo>
+ <warning>
+ <para>This document is in progress of beeing written.</para>
+ </warning>
+
<section>
<title>Session management</title>
@@ -25,8 +29,10 @@
means it is possible to choose between different kind of session stores,
as well as write new session store plugins.</para>
- <para>The current version of simpleSAMLphp includes two plugins for
- session management:</para>
+ <para>The <literal>session.handler</literal> configuration option in
+ <filename>config.php</filename> allows you to select which session handler
+ SimpleSAMLPHP should use to store the session information. Currently we
+ have two session handlers:</para>
<itemizedlist>
<listitem>
@@ -42,116 +48,155 @@
</listitem>
</itemizedlist>
+ <programlisting> 'session.handler' => 'phpsession',</programlisting>
+
<section>
<title>Configuring memcache</title>
- <para>From config.php</para>
-
- <programlisting>
- /*
- * This configuration option allows you to select which session handler
- * SimpleSAMLPHP should use to store the session information. Currently
- * we have two session handlers:
- * - 'phpsession': The default PHP session handler.
- * - 'memcache': Stores the session information in one or more
- * memcache servers by using the MemcacheStore class.
- *
- * The default session handler is 'phpsession'.
- */
- 'session.handler' => 'phpsession',
-
-
- /*
- * Configuration for the MemcacheStore class. This allows you to store
- * multiple redudant copies of sessions on different memcache servers.
- *
- * 'memcache_store.servers' is an array of server groups. Every data
- * item will be mirrored in every server group.
- *
- * Each server group is an array of servers. The data items will be
- * load-balanced between all servers in each server group.
- *
- * Each server is an array of parameters for the server. The following
- * options are available:
- * - 'hostname': This is the hostname or ip address where the
- * memcache server runs. This is the only required option.
- * - 'port': This is the port number of the memcache server. If this
- * option isn't set, then we will use the 'memcache.default_port'
- * ini setting. This is 11211 by default.
- * - 'weight': This sets the weight of this server in this server
- * group. http://php.net/manual/en/function.Memcache-addServer.php
- * contains more information about the weight option.
- * - 'timeout': The timeout for this server. By default, the timeout
- * is 3 seconds.
- *
- * Example of redudant configuration with load balancing:
- * This configuration makes it possible to lose both servers in the
- * a-group or both servers in the b-group without losing any sessions.
- * Note that sessions will be lost if one server is lost from both the
- * a-group and the b-group.
- *
- * 'memcache_store.servers' => array(
- * array(
- * array('hostname' => 'mc_a1'),
- * array('hostname' => 'mc_a2'),
- * ),
- * array(
- * array('hostname' => 'mc_b1'),
- * array('hostname' => 'mc_b2'),
- * ),
- * ),
- *
- * Example of simple configuration with only one memcache server,
- * running on the same computer as the web server:
- * Note that all sessions will be lost if the memcache server crashes.
- *
- * 'memcache_store.servers' => array(
- * array(
- * array('hostname' => 'localhost'),
- * ),
- * ),
- *
- */
- 'memcache_store.servers' => array(
- array(
- array('hostname' => 'localhost'),
- ),
+ <para>To use the memcache session handler, set the session.handler
+ parameter in <literal>config.php</literal>:</para>
+
+ <programlisting>'session.handler' => 'memcache',</programlisting>
+
+ <para>Memcache allows you to store multiple redudant copies of sessions
+ on different memcache servers.</para>
+
+ <para>The configuration parameter
+ <literal>memcache_store.servers</literal> is an array of server groups.
+ Every data item will be mirrored in every server group.</para>
+
+ <para>Each server group is an array of servers. The data items will be
+ load-balanced between all servers in each server group.</para>
+
+ <para>Each server is an array of parameters for the server. The
+ following options are available:</para>
+
+ <glosslist>
+ <glossentry>
+ <glossterm><literal>hostname</literal></glossterm>
+
+ <glossdef>
+ <para>This is the hostname or ip address where the memcache server
+ runs. This is the only required option.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm><literal>port</literal></glossterm>
+
+ <glossdef>
+ <para>This is the port number of the memcache server. If this
+ option isn't set, then we will use the
+ <literal>memcache.default_port</literal> ini setting. This is
+ 11211 by default.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm><literal>weight</literal></glossterm>
+
+ <glossdef>
+ <para>This sets the weight of this server in this server group.
+ <ulink
+ url="http://php.net/manual/en/function.Memcache-addServer.php">http://php.net/manual/en/function.Memcache-addServer.php</ulink>
+ contains more information about the weight option.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm><literal>timeout</literal></glossterm>
+
+ <glossdef>
+ <para>The timeout for this server. By default, the timeout is 3
+ seconds.</para>
+ </glossdef>
+ </glossentry>
+ </glosslist>
+
+ <para>Here are two examples of configuration of memcache session
+ handling:</para>
+
+ <example>
+ <title>Example of redudant configuration with load balancing</title>
+
+ <para>Example of redudant configuration with load balancing: This
+ configuration makes it possible to lose both servers in the a-group or
+ both servers in the b-group without losing any sessions. Note that
+ sessions will be lost if one server is lost from both the a-group and
+ the b-group.</para>
+
+ <programlisting>'memcache_store.servers' => array(
+ array(
+ array('hostname' => 'mc_a1'),
+ array('hostname' => 'mc_a2'),
+ ),
+ array(
+ array('hostname' => 'mc_b1'),
+ array('hostname' => 'mc_b2'),
),
+),</programlisting>
+ </example>
+ <example>
+ <title>Example of simple configuration with only one memcache
+ server</title>
- /*
- * This value is the duration data should be stored in memcache. Data
- * will be dropped from the memcache servers when this time expires.
- * The time will be reset every time the data is written to the
- * memcache servers.
- *
- * This value should always be larger than the 'session.duration'
- * option. Not doing this may result in the session being deleted from
- * the memcache servers while it is still in use.
- *
- * Set this value to 0 if you don't want data to expire.
- *
- * Note: The oldest data will always be deleted if the memcache server
- * runs out of storage space.
- */
- 'memcache_store.expires' => 36 * (60*60), // 36 hours.
-
-</programlisting>
-
- <important>
- <para>Setup a firewall restricting access to the memcache
- server.</para>
- </important>
+ <para>Example of simple configuration with only one memcache server,
+ running on the same computer as the web server: Note that all sessions
+ will be lost if the memcache server crashes.</para>
+
+ <programlisting>'memcache_store.servers' => array(
+ array(
+ array('hostname' => 'localhost'),
+ ),
+),</programlisting>
+ </example>
+
+ <para>The expiration value (<literal>memcache_store.expires</literal>)
+ is the duration data should be stored in memcache. Datawill be dropped
+ from the memcache servers when this time expires. The time will be reset
+ every time the data is written to the memcache servers.</para>
+
+ <para>This value should always be larger than the
+ <literal>session.duration</literal> option. Not doing this may result in
+ the session being deleted from the memcache servers while it is still in
+ use.</para>
+
+ <para>Set this value to 0 if you don't want data to expire. </para>
- <para>Configure memcahce to not do internal failover. This parameter is
- configured in <filename>php.ini</filename>.</para>
+ <note>
+ <para>The oldest data will always be deleted if the memcache server
+ runs out of storage space.</para>
+ </note>
- <programlisting>memcache.allow_failover = Off</programlisting>
+ <example>
+ <title>Example of configuration setting for session expiration</title>
+
+ <para>Here is an example of this configuration parameter:</para>
+
+ <programlisting>'memcache_store.expires' => 36 * (60*60), // 36 hours.</programlisting>
+ </example>
+
+ <section>
+ <title>Memcache PHP configuration</title>
+
+ <para>Configure memcahce to not do internal failover. This parameter
+ is configured in <filename>php.ini</filename>.</para>
+
+ <programlisting>memcache.allow_failover = Off</programlisting>
+ </section>
+
+ <section>
+ <title>Environmental configuration</title>
+
+ <para>Setup a firewall restricting access to the memcache
+ server.</para>
- <para>Because simpleSAMLphp uses a timestamp to check which session is
- most recent in a fail-over setup, it is very important to run
- syncrhonized clocks on all webservers where you run
- simpleSAMLphp.</para>
+ <para>Because simpleSAMLphp uses a timestamp to check which session is
+ most recent in a fail-over setup, it is very important to run
+ syncrhonized clocks on all webservers where you run
+ simpleSAMLphp.</para>
+ </section>
</section>
</section>
@@ -177,7 +222,7 @@
<section>
<title>PHP configuration</title>
- <para>Secure cookies.</para>
+ <para>Secure cookies (if you run HTTPS).</para>
<para>Turn off PHPSESSID in query string.</para>
</section>
@@ -258,4 +303,37 @@ templates/dkaaitheme/dk
of <literal>templatedir</literal> to
<filename>templates/dkaaitheme/</filename>.</para>
</section>
+
+ <section>
+ <title>Support</title>
+
+ <para>If you have problems to get this work, or want to discuss
+ simpleSAMLphp with other users of the software you are lucky! Around
+ simpleSAMLphp there is a great Open source community, and you are welcome
+ to join! Both for asking question, answer other questions, request
+ improvements or contribute with code or plugins of your own.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><ulink url="http://rnd.feide.no/simplesamlphp">simpleSAMLphp
+ homepage (at Feide RnD)</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="http://rnd.feide.no/view/simplesamlphpdocs">List of
+ all available simpleSAMLphp documentation</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="http://rnd.feide.no/content/simplesamlphp-users-mailinglist">Join
+ the simpleSAMLphp user's mailing list</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="https://ow.feide.no/simplesamlphp:start">Visit and
+ contribute to the simpleSAMLphp wiki</ulink></para>
+ </listitem>
+ </itemizedlist>
+ </section>
</article>
\ No newline at end of file
diff --git a/docs/source/simplesamlphp-sp.xml b/docs/source/simplesamlphp-sp.xml
index f48224c19..d1437a4dc 100644
--- a/docs/source/simplesamlphp-sp.xml
+++ b/docs/source/simplesamlphp-sp.xml
@@ -7,7 +7,7 @@
<articleinfo>
<date>2007-10-15</date>
- <pubdate>Thu Mar 13 22:23:40 2008</pubdate>
+ <pubdate>Fri Mar 14 10:40:20 2008</pubdate>
<author>
<firstname>Andreas Ă…kre</firstname>
@@ -33,6 +33,22 @@
although the configuration is similar.</para>
</section>
+ <section>
+ <title>Enabling the Service Provider functionality</title>
+
+ <para>The SAML 2.0 SP functionality is enabled per default. If you want to
+ setup a shibboleth 1.3 SP, you shuold disable SAML 2.0 SP and enable Shib
+ 1.3 SP. In <filename>config.php</filename>:</para>
+
+ <programlisting>'enable.saml20-sp' => false,
+'enable.saml20-idp' => false,
+'enable.shib13-sp' => true,
+'enable.shib13-idp' => false,</programlisting>
+
+ <para>If you will be using SAML 2.0 SP, leave the enable config as
+ default.</para>
+ </section>
+
<section>
<title>Configuring metadata for SAML 2.0 SP</title>
@@ -164,18 +180,6 @@
as software-PKI.</para>
</glossdef>
</glossentry>
-
- <glossentry>
- <glossterm>SPNameQualifier</glossterm>
-
- <glossdef>
- <para>This corresponds to the SPNameQualifier in the SAML 2.0
- specification. It allows to give subjects a SP specific
- namespace. This value is seldom used, so if you don't need it,
- do not include it. If you do not include it, simpleSAMLphp will
- include the entityID of your SP as the SPNameQualifier.</para>
- </glossdef>
- </glossentry>
</glosslist>
</section>
@@ -346,29 +350,26 @@
</glossentry>
<glossentry>
- <glossterm>SingleLogoutServiceResponse</glossterm>
+ <glossterm>SPNameQualifier</glossterm>
<glossdef>
- <para>Some IdPs may require logout responses to be sent to a
- different URL than logout requests. If this option is set, then
- logout responses will be sent to this URL while logout requests
- are sent to the URL in
- <literal>SingleLogoutService</literal>.
- <literal>SingleLogoutService</literal> will be used for both
- messages if this option is unset.</para>
+ <para>This corresponds to the SPNameQualifier in the SAML 2.0
+ specification. It allows to give subjects a SP specific
+ namespace. This value is seldom used, so if you don't need it,
+ do not include it. If you do not include it, simpleSAMLphp will
+ include the entityID of your SP as the SPNameQualifier.</para>
</glossdef>
</glossentry>
</glosslist>
</section>
<section>
- <title>Fields for requireing signed
- LogoutRequests/LogoutResponses</title>
+ <title>Fields for requireing signed LogoutRequests</title>
- <para>simpleSAMLphp supports signing the HTTP-REDIRECT messages, but
- by default it will neither sign nor validate them. To enable validation
- of LogoutRequest and LogoutResponse messages from this IdP, you will
- need to set these options:</para>
+ <para>simpleSAMLphp supports signing the HTTP-REDIRECT authentication
+ request, but by default it will not sign it. Note that if you want to
+ sign the authentication requests, you will need to have a
+ keypair/certificate at the SP.</para>
<glosslist>
<glossentry>
@@ -376,8 +377,17 @@
<glossdef>
<para>A boolean value, that should be true or false. Default is
- false. To require validation of messages from the IdP, set this
- flag to true.</para>
+ false. To turn on signing authentication requests, set this flag
+ to true.</para>
+ </glossdef>
+ </glossentry>
+
+ <glossentry>
+ <glossterm>privatekey</glossterm>
+
+ <glossdef>
+ <para>The filename of the privatekey to be used for
+ singing.</para>
</glossdef>
</glossentry>
@@ -385,15 +395,14 @@
<glossterm>certificate</glossterm>
<glossdef>
- <para>The filename of the certificate which should be used to
- verify the signature.</para>
+ <para>The filename of the certificate which corresponds to the
+ privatekey.</para>
</glossdef>
</glossentry>
</glosslist>
<example>
- <title>Example of configuration which requires validation valid
- signatures on LogoutRequests</title>
+ <title>Example of configured signed LogoutRequests</title>
<programlisting>'request.signing' => true,
'certificate' => 'server.crt'</programlisting>
@@ -657,17 +666,15 @@
<programlisting>require_once('SimpleSAML/Utilities.php');
require_once('SimpleSAML/Session.php');
-require_once('SimpleSAML/Metadata/MetaDataStorageHandler.php');
require_once('SimpleSAML/XHTML/Template.php');
</programlisting>
- <para>Then enable using PHP Sessions, and load configuration and metadata
- with simpleSAMLphp. You can copy this lines into your application without
+ <para>Then enable using PHP Sessions and load configuration with
+ simpleSAMLphp. You can copy this lines into your application without
changes:</para>
<programlisting>/* Load simpleSAMLphp, configuration and metadata */
$config = SimpleSAML_Configuration::getInstance();
-$metadata = SimpleSAML_Metadata_MetaDataStorageHandler::getMetadataHandler();
$session = SimpleSAML_Session::getInstance(true);</programlisting>
<para>Then at last, you check whether the session is valid. If it is not,
@@ -688,6 +695,19 @@ if (!isset($session) || !$session->isValid('saml2') ) {
$attributes = $session->getAttributes();
print_r($attributes);
</programlisting>
+
+ <section>
+ <title>Upgrading service integration from version 0.5 to 1.0</title>
+
+ <itemizedlist>
+ <listitem>
+ <para><ulink
+ url="https://ow.feide.no/simplesamlphp:spupgrade05to10">Wiki page
+ describing the differences between integrating a service with
+ simpleSAMLphp 0.5 and simpleSAMLphp 1.0.</ulink></para>
+ </listitem>
+ </itemizedlist>
+ </section>
</section>
<section>
@@ -699,11 +719,28 @@ print_r($attributes);
to join! Both for asking question, answer other questions, request
improvements or contribute with code or plugins of your own.</para>
- <para>Go to simpleSAMLphp homepage: <ulink
- url="http://rnd.feide.no/simplesamlphp">http://rnd.feide.no/simplesamlphp</ulink></para>
+ <itemizedlist>
+ <listitem>
+ <para><ulink url="http://rnd.feide.no/simplesamlphp">simpleSAMLphp
+ homepage (at Feide RnD)</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="http://rnd.feide.no/view/simplesamlphpdocs">List of
+ all available simpleSAMLphp documentation</ulink></para>
+ </listitem>
- <para>And please join the mailinglist: <ulink
- url="http://rnd.feide.no/content/simplesamlphp-users-mailinglist">http://rnd.feide.no/content/simplesamlphp-users-mailinglist</ulink></para>
+ <listitem>
+ <para><ulink
+ url="http://rnd.feide.no/content/simplesamlphp-users-mailinglist">Join
+ the simpleSAMLphp user's mailing list</ulink></para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="https://ow.feide.no/simplesamlphp:start">Visit and
+ contribute to the simpleSAMLphp wiki</ulink></para>
+ </listitem>
+ </itemizedlist>
</section>
<appendix id="a.fingerprint">
--
GitLab