Skip to content
Snippets Groups Projects
Commit 5b66aa25 authored by Andreas Åkre Solberg's avatar Andreas Åkre Solberg
Browse files

[docbook] Adding article info and fixing missing xml encoding of ampersand.

git-svn-id: https://simplesamlphp.googlecode.com/svn/trunk@827 44740490-163a-0410-bde0-09ae8108e29a
parent c6931ae5
No related branches found
No related tags found
No related merge requests found
...@@ -8,7 +8,7 @@ ...@@ -8,7 +8,7 @@
<articleinfo> <articleinfo>
<date>2007-10-15</date> <date>2007-10-15</date>
<pubdate>Thu Mar 27 20:45:58 2008</pubdate> <pubdate>Thu Aug 21 10:30:22 2008</pubdate>
<author> <author>
<firstname>Andreas Åkre</firstname> <firstname>Andreas Åkre</firstname>
......
...@@ -7,7 +7,7 @@ ...@@ -7,7 +7,7 @@
<articleinfo> <articleinfo>
<date>2007-10-15</date> <date>2007-10-15</date>
<pubdate>Thu Jun 19 08:20:30 2008</pubdate> <pubdate>Thu Aug 21 10:31:08 2008</pubdate>
<author> <author>
<firstname>Andreas Åkre</firstname> <firstname>Andreas Åkre</firstname>
......
...@@ -4,6 +4,18 @@ ...@@ -4,6 +4,18 @@
<article> <article>
<title>simpleSAMLphp modules</title> <title>simpleSAMLphp modules</title>
<articleinfo>
<date>2008-08-21</date>
<pubdate>Thu Aug 21 10:32:42 2008</pubdate>
<author>
<firstname>Olav</firstname>
<surname>Morken</surname>
</author>
</articleinfo>
<section> <section>
<title>simpleSAMLphp documentation</title> <title>simpleSAMLphp documentation</title>
...@@ -17,9 +29,9 @@ ...@@ -17,9 +29,9 @@
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>This document describes how the module system in simpleSAMLphp works. <para>This document describes how the module system in simpleSAMLphp
It descibes what types of modules there are, how they are configured, and works. It descibes what types of modules there are, how they are
how to write new modules.</para> configured, and how to write new modules.</para>
</section> </section>
<section> <section>
...@@ -31,28 +43,28 @@ ...@@ -31,28 +43,28 @@
also support for storing supporting files, such as templates and also support for storing supporting files, such as templates and
dictionaries, in modules.</para> dictionaries, in modules.</para>
<para>The different functionalities which can be created as modules will be <para>The different functionalities which can be created as modules will
described in more detail in the following sections; what follows is a short be described in more detail in the following sections; what follows is a
introduction to what you can du with them:</para> short introduction to what you can du with them:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>Authentication sources implement different methods for <para>Authentication sources implement different methods for
authenticating users, for example simple login forms which authenticate authenticating users, for example simple login forms which
against a database backend, or login methods which use client-side authenticate against a database backend, or login methods which use
certificates.</para> client-side certificates.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Authentication processing filters perform various tasks after the <para>Authentication processing filters perform various tasks after
user is authenticated and has a set of attributes. They can add, remove the user is authenticated and has a set of attributes. They can add,
and modify attributes, do additional authentication checks, ask remove and modify attributes, do additional authentication checks, ask
questions of the user, +++.</para> questions of the user, +++.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Themes allow you to package custom templates for multiple modules <para>Themes allow you to package custom templates for multiple
into a single module.</para> modules into a single module.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</section> </section>
...@@ -60,12 +72,11 @@ ...@@ -60,12 +72,11 @@
<section> <section>
<title>Module layout</title> <title>Module layout</title>
<para>Each simpleSAMLphp module is stored in a directory under the the <para>Each simpleSAMLphp module is stored in a directory under the the
<filename>modules</filename>-directory. The module directory contains the <filename>modules</filename>-directory. The module directory contains the
following directories and files:</para> following directories and files:</para>
<para> <para><glosslist>
<glosslist>
<glossentry> <glossentry>
<glossterm>default-disable</glossterm> <glossterm>default-disable</glossterm>
...@@ -92,15 +103,15 @@ ...@@ -92,15 +103,15 @@
<glossdef> <glossdef>
<para>This directory contains dictionaries which belong to this <para>This directory contains dictionaries which belong to this
module. To use a dictionary stored in a module, the extended tag module. To use a dictionary stored in a module, the extended tag
names can be used: names can be used: <literal>{&lt;module name&gt;:&lt;dictionary
<literal>{&lt;module name&gt;:&lt;dictionary name&gt;:&lt;tag name&gt;}</literal> name&gt;:&lt;tag name&gt;}</literal> For example,
For example, <literal>{example:login:hello}</literal> will look up <literal>{example:login:hello}</literal> will look up
<literal>hello</literal> in <literal>hello</literal> in
<literal>modules/example/dictionaries/login.php</literal>.</para> <literal>modules/example/dictionaries/login.php</literal>.</para>
<para>It is also possible to specify <para>It is also possible to specify <literal>&lt;module
<literal>&lt;module name&gt;:&lt;dictionary name&gt;</literal> as name&gt;:&lt;dictionary name&gt;</literal> as the default
the default dictionary when instantiating the dictionary when instantiating the
<literal>SimpleSAML_XHTML_Template</literal> class.</para> <literal>SimpleSAML_XHTML_Template</literal> class.</para>
</glossdef> </glossdef>
</glossentry> </glossentry>
...@@ -120,8 +131,7 @@ ...@@ -120,8 +131,7 @@
<para>Thus, if simpleSAMLphp needs to load a class named <para>Thus, if simpleSAMLphp needs to load a class named
<literal>sspmod_example_Auth_Source_Example</literal>, it will <literal>sspmod_example_Auth_Source_Example</literal>, it will
load the file named load the file named
<literal>modules/example/lib/Auth/Source/Example.php</literal>. <literal>modules/example/lib/Auth/Source/Example.php</literal>.</para>
</para>
</glossdef> </glossdef>
</glossentry> </glossentry>
...@@ -130,11 +140,11 @@ ...@@ -130,11 +140,11 @@
<glossdef> <glossdef>
<para>These are module-specific templates. To use one of these <para>These are module-specific templates. To use one of these
templates, specify templates, specify <literal>&lt;module name&gt;:&lt;template
<literal>&lt;module name&gt;:&lt;template file&gt;.php</literal> as file&gt;.php</literal> as the template file in the constructor of
the template file in the constructor of
<literal>SimpleSAML_XHTML_Template</literal>. For example, <literal>SimpleSAML_XHTML_Template</literal>. For example,
<literal>example:login-form.php</literal> is translated to the file <literal>example:login-form.php</literal> is translated to the
file
<literal>modules/example/templates/default/login-form.php</literal>. <literal>modules/example/templates/default/login-form.php</literal>.
Note that <literal>default</literal> in the previous example is Note that <literal>default</literal> in the previous example is
defined by the <literal>theme.use</literal> configuration defined by the <literal>theme.use</literal> configuration
...@@ -165,8 +175,7 @@ ...@@ -165,8 +175,7 @@
while the template while the template
<literal>modules/core/templates/default/loginuserpass.php</literal> <literal>modules/core/templates/default/loginuserpass.php</literal>
will be overridden by will be overridden by
<literal>modules/example/themes/blue/core/loginuserpass.php</literal>. <literal>modules/example/themes/blue/core/loginuserpass.php</literal>.</para>
</para>
</glossdef> </glossdef>
</glossentry> </glossentry>
...@@ -175,34 +184,37 @@ ...@@ -175,34 +184,37 @@
<glossdef> <glossdef>
<para>All files stored in this directory will be available by <para>All files stored in this directory will be available by
accessing the URL <literal>https://.../simplesamlphp/module.php/&lt;module name&gt;/&lt;file name&gt;</literal>. accessing the URL
For example, if a script named <literal>login.php</literal> is <literal>https://.../simplesamlphp/module.php/&lt;module
stored in <literal>modules/example/www/</literal>, it can be name&gt;/&lt;file name&gt;</literal>. For example, if a script
accessed by the URL <literal>https://.../simplesamlphp/module.php/example/login.php</literal>.</para> named <literal>login.php</literal> is stored in
<literal>modules/example/www/</literal>, it can be accessed by the
URL
<literal>https://.../simplesamlphp/module.php/example/login.php</literal>.</para>
<para>To retrieve this URL, the <para>To retrieve this URL, the
<literal>SimpleSAML_Module::getModuleURL($resource)</literal>-function <literal>SimpleSAML_Module::getModuleURL($resource)</literal>-function
can be used. This function takes in a resource on the form can be used. This function takes in a resource on the form
<literal>&lt;module&gt;/&lt;file&gt;</literal>. This function will <literal>&lt;module&gt;/&lt;file&gt;</literal>. This function will
then return an URL to the given file in the then return an URL to the given file in the
<literal>www</literal>-directory of <literal>module</literal>.</para> <literal>www</literal>-directory of
<literal>module</literal>.</para>
</glossdef> </glossdef>
</glossentry> </glossentry>
</glosslist> </glosslist></para>
</para>
</section> </section>
<section> <section>
<title>Authentication sources</title> <title>Authentication sources</title>
<para>An authentication source is used to authenticate a user and receive a <para>An authentication source is used to authenticate a user and receive
set of attributes belonging to this user. In a single-signon setup, the a set of attributes belonging to this user. In a single-signon setup, the
authentication source will only be called once, and the attributes authentication source will only be called once, and the attributes
belonging to the user will be cached until the user logs out.</para> belonging to the user will be cached until the user logs out.</para>
<para>Authentication sources are defined in <para>Authentication sources are defined in
<filename>config/authsources.php</filename>. This file contains an array of <filename>config/authsources.php</filename>. This file contains an array
<literal>name =&gt; configuration</literal> pairs. The name is used to of <literal>name =&gt; configuration</literal> pairs. The name is used to
refer to the authentication source in metadata. When configuring an IdP to refer to the authentication source in metadata. When configuring an IdP to
authenticate against an authentication source, the <literal>auth</literal> authenticate against an authentication source, the <literal>auth</literal>
option should be set to this name. The configuration for an authentication option should be set to this name. The configuration for an authentication
...@@ -210,8 +222,8 @@ ...@@ -210,8 +222,8 @@
which implements the authentication source. The remaining elements in the which implements the authentication source. The remaining elements in the
array are configuration entries for the authentication source.</para> array are configuration entries for the authentication source.</para>
<para>A typical configuration entry for an authentication source looks like <para>A typical configuration entry for an authentication source looks
this:</para> like this:</para>
<programlisting>'example-static' =&gt; array( <programlisting>'example-static' =&gt; array(
/* This maps to modules/exampleauth/lib/Auth/Source/Static.php */ /* This maps to modules/exampleauth/lib/Auth/Source/Static.php */
...@@ -223,7 +235,9 @@ ...@@ -223,7 +235,9 @@
'cn' =&gt; array('Test User'), 'cn' =&gt; array('Test User'),
),</programlisting> ),</programlisting>
<para>To use this authentication source in a SAML 2.0 IdP, set the <literal>auth</literal>-option of the IdP to <literal>'example-static'</literal>:</para> <para>To use this authentication source in a SAML 2.0 IdP, set the
<literal>auth</literal>-option of the IdP to
<literal>'example-static'</literal>:</para>
<programlisting>'__DYNAMIC:1__' =&gt; array( <programlisting>'__DYNAMIC:1__' =&gt; array(
'host' =&gt; '__DEFAULT__', 'host' =&gt; '__DEFAULT__',
...@@ -238,9 +252,9 @@ ...@@ -238,9 +252,9 @@
<para>Authentication sources are implemented by creating a class which <para>Authentication sources are implemented by creating a class which
is a subclass of the <literal>SimpleSAML_Auth_Source</literal>-class. is a subclass of the <literal>SimpleSAML_Auth_Source</literal>-class.
They must implement at least one function - They must implement at least one function -
<literal>authenticate</literal>. This function may can either update <literal>authenticate</literal>. This function may can either update the
the <literal>$state</literal>-array it receives with the attributes <literal>$state</literal>-array it receives with the attributes of the
of the user and return, or it may save the state and redirect the user to user and return, or it may save the state and redirect the user to
another page for authentication. It redirects, it should later retrieve another page for authentication. It redirects, it should later retrieve
the state array, update it with the attributes and call the state array, update it with the attributes and call
<literal>SimpleSAML_Source_Auth::completeAuth($state)</literal>.</para> <literal>SimpleSAML_Source_Auth::completeAuth($state)</literal>.</para>
...@@ -271,10 +285,10 @@ ...@@ -271,10 +285,10 @@
</listitem> </listitem>
<listitem> <listitem>
<para>The <literal>authenticate(&$state)</literal>-function must be <para>The <literal>authenticate(&amp;$state)</literal>-function must
implemented. If this function completes, it is assumed that the user be implemented. If this function completes, it is assumed that the
is authenticated, and that the $state array has been updated with the user is authenticated, and that the $state array has been updated
user's attributes.</para> with the user's attributes.</para>
</listitem> </listitem>
<listitem> <listitem>
...@@ -295,17 +309,17 @@ ...@@ -295,17 +309,17 @@
<listitem> <listitem>
<para>No state information about any authentication should be stored <para>No state information about any authentication should be stored
in the authentication source object. It must instead be stored in the in the authentication source object. It must instead be stored in
state array. Any changes to variables in the authentication source the state array. Any changes to variables in the authentication
object may be lost.</para> source object may be lost.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>The authentication source object must be serializable. It may <para>The authentication source object must be serializable. It may
be serializes between being constructed and the call to the be serializes between being constructed and the call to the
<literal>authenticate</literal>-function. This means that, for <literal>authenticate</literal>-function. This means that, for
example, no database connections should be created in the constructor example, no database connections should be created in the
and later used in the constructor and later used in the
<literal>authenticate</literal>-function.</para> <literal>authenticate</literal>-function.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
...@@ -352,16 +366,16 @@ ...@@ -352,16 +366,16 @@
and run some filters on the SP befoer one filter on the IdP. To achieve and run some filters on the SP befoer one filter on the IdP. To achieve
this, we have the <literal>%priority</literal>-option of filters. The this, we have the <literal>%priority</literal>-option of filters. The
default priority, if no <literal>%priority</literal>-option is added, is default priority, if no <literal>%priority</literal>-option is added, is
50. By giving a filter a higher priority value, you can make it run after 50. By giving a filter a higher priority value, you can make it run
those with a lower priority:</para> after those with a lower priority:</para>
<programlisting>/* saml20-idp-hosted.php */ <programlisting>/* saml20-idp-hosted.php */
'authproc' => array( 'authproc' =&gt; array(
array('consent:Consent', '%priority' =&gt; 60), array('consent:Consent', '%priority' =&gt; 60),
), ),
/* saml20-sp-remote.php */ /* saml20-sp-remote.php */
'authproc' => array( 'authproc' =&gt; array(
array('core:AttributeLimit', 'uid', 'mail', 'cn'), array('core:AttributeLimit', 'uid', 'mail', 'cn'),
array('core:AttributeMap', '%priority' =&gt; 70, 'mail' =&gt; 'email'), array('core:AttributeMap', '%priority' =&gt; 70, 'mail' =&gt; 'email'),
),</programlisting> ),</programlisting>
...@@ -379,21 +393,23 @@ ...@@ -379,21 +393,23 @@
<para>Authentication processing filters are created by creating a class <para>Authentication processing filters are created by creating a class
under <literal>Auth/Process/</literal> in a module. This class is under <literal>Auth/Process/</literal> in a module. This class is
expected to subclass <literal>SimpleSAML_Auth_ProcessingFilter</literal>. expected to subclass
A filter must implement at lease one function - the <literal>SimpleSAML_Auth_ProcessingFilter</literal>. A filter must
<literal>process(&$request)</literal>-function. This function can access implement at lease one function - the
the <literal>$request</literal>-array add, delete and modify attributes, <literal>process(&amp;$request)</literal>-function. This function can
and can also do more advanced processing based on the SP/IdP metadata access the <literal>$request</literal>-array add, delete and modify
(which is also included in the <literal>$request</literal>-array). When attributes, and can also do more advanced processing based on the SP/IdP
this function returns, it is assumed that the filter has finished metadata (which is also included in the
processing.</para> <literal>$request</literal>-array). When this function returns, it is
assumed that the filter has finished processing.</para>
<para>If a filter for some reason needs to redirect the user, for example
to show a web page, it should save the current request. Upon completion <para>If a filter for some reason needs to redirect the user, for
it should retrieve the request, update it with the changes it is going example to show a web page, it should save the current request. Upon
to make, and call completion it should retrieve the request, update it with the changes it
is going to make, and call
<literal>SimpleSAML_Auth_ProcessingChain::resumeProcessing</literal>. <literal>SimpleSAML_Auth_ProcessingChain::resumeProcessing</literal>.
This function will continue processing the next configured filter.</para> This function will continue processing the next configured
filter.</para>
<para>Requirements for authentication processing filters:</para> <para>Requirements for authentication processing filters:</para>
...@@ -411,15 +427,15 @@ ...@@ -411,15 +427,15 @@
</listitem> </listitem>
<listitem> <listitem>
<para>The <literal>process(&$state)</literal>-function must be <para>The <literal>process(&amp;$state)</literal>-function must be
implemented. If this function completes, it is assumed that implemented. If this function completes, it is assumed that
processing is completed, and that the $request array has been processing is completed, and that the $request array has been
updated.</para> updated.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>If the <literal>process</literal>-function does not <para>If the <literal>process</literal>-function does not return, it
return, it must at a later time call must at a later time call
<literal>SimpleSAML_Auth_ProcessingChain::resumeProcessing</literal> <literal>SimpleSAML_Auth_ProcessingChain::resumeProcessing</literal>
with the new request state. The request state must be an update of with the new request state. The request state must be an update of
the array passed to the <literal>process</literal>-function.</para> the array passed to the <literal>process</literal>-function.</para>
...@@ -442,9 +458,9 @@ ...@@ -442,9 +458,9 @@
<listitem> <listitem>
<para>The filter object must be serializable. It may be serialized <para>The filter object must be serializable. It may be serialized
between being constructed and the call to the between being constructed and the call to the
<literal>process</literal>-function. This means that, for example, no <literal>process</literal>-function. This means that, for example,
database connections should be created in the constructor and later no database connections should be created in the constructor and
used in the <literal>process</literal>-function.</para> later used in the <literal>process</literal>-function.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</section> </section>
...@@ -463,11 +479,13 @@ ...@@ -463,11 +479,13 @@
<literal>module</literal> is the module the template belongs to, and <literal>module</literal> is the module the template belongs to, and
<literal>template</literal> is the template in that module.</para> <literal>template</literal> is the template in that module.</para>
<para>For example, <literal>modules/example/themes/test/core/loginuserpass.php</literal> <para>For example,
replaces <literal>modules/core/templates/default/loginuserpass.php</literal>. <literal>modules/example/themes/test/core/loginuserpass.php</literal>
<literal>modules/example/themes/test/default/frontpage.php</literal> replaces replaces
<literal>templates/default/frontpage.php</literal>. This theme can be <literal>modules/core/templates/default/loginuserpass.php</literal>.
activated by setting <literal>theme.use</literal> to <literal>modules/example/themes/test/default/frontpage.php</literal>
replaces <literal>templates/default/frontpage.php</literal>. This theme
can be activated by setting <literal>theme.use</literal> to
<literal>example:test</literal>.</para> <literal>example:test</literal>.</para>
</section> </section>
</article> </article>
\ No newline at end of file
...@@ -7,7 +7,7 @@ ...@@ -7,7 +7,7 @@
<articleinfo> <articleinfo>
<date>2007-10-15</date> <date>2007-10-15</date>
<pubdate>Thu Jun 19 08:35:05 2008</pubdate> <pubdate>Thu Aug 21 10:32:42 2008</pubdate>
<author> <author>
<firstname>Andreas Åkre</firstname> <firstname>Andreas Åkre</firstname>
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment