From ff826567e4d1a51e833a87dd0cbece14e33e49e6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andreas=20=C3=85kre=20Solberg?= <andreas.solberg@uninett.no>
Date: Sun, 11 Jan 2009 13:22:19 +0000
Subject: [PATCH] Adding simplesamlphp modules document as markdown outside
source dir. Updating info about authproc pointing to separate doc.
git-svn-id: https://simplesamlphp.googlecode.com/svn/trunk@1137 44740490-163a-0410-bde0-09ae8108e29a
---
docs/simplesamlphp-authproc.txt | 19 +-
docs/simplesamlphp-modules.txt | 219 +++++++++++
docs/source/simplesamlphp-modules.xml | 523 --------------------------
3 files changed, 236 insertions(+), 525 deletions(-)
create mode 100644 docs/simplesamlphp-modules.txt
delete mode 100644 docs/source/simplesamlphp-modules.xml
diff --git a/docs/simplesamlphp-authproc.txt b/docs/simplesamlphp-authproc.txt
index 59b631f1b..878747012 100644
--- a/docs/simplesamlphp-authproc.txt
+++ b/docs/simplesamlphp-authproc.txt
@@ -11,6 +11,8 @@ Authentication Processing Filters in SimpleSAMLphp
In SimpleSAMLphp, there is an API where you can *do stuff* at the IdP after authentication is complete, and just before you are sent back to the SP. The same API is available on the SP, after you have received a successfull Authentication Response from the IdP and before you are sent back to the SP application.
+Authentication processing filters postprocesses authentication information received from authentication sources. It is possible to use this for additional authentication checks, requesting the users consent before delivering attributes to the user, modifying the users attributes, and other things which should be performed before returning the user to the service provider he came from.
+
Examples of neat things to do using Authentication Processing Filters:
* Filter out a subset of available attributes that are sent to a SP.
@@ -385,7 +387,20 @@ Here you can see that the LanguageAdaptor runs with priority 30. At this point t
Writing your own Auth Proc Filter
---------------------------------
-For now look at the included *Auth Proc Filters* as examples. Copy the classes into your own module and start playing around.
+Look at the included *Auth Proc Filters* as examples. Copy the classes into your own module and start playing around.
-Don't hestitate to ask on the simpleSAMLphp mailinglist if you have problems or questions, or want to share your *Auth Proc Filter* with others.
+Authentication processing filters are created by creating a class under `Auth/Process/` in a module. This class is expected to subclass `SimpleSAML_Auth_ProcessingFilter`. A filter must implement at lease one function - the `process(&$request)`-function. This function can access the `$request`-array add, delete and modify attributes, and can also do more advanced processing based on the SP/IdP metadata (which is also included in the `$request`-array). When this function returns, it is assumed that the filter has finished processing.
+
+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 it should retrieve the request, update it with the changes it is going to make, and call `SimpleSAML_Auth_ProcessingChain::resumeProcessing`. This function will continue processing the next configured filter.
+Requirements for authentication processing filters:
+
+ - Must be derived from the `SimpleSAML_Auth_ProcessingFilter`-class.
+ - If a constructor is implemented, it must first call the parent constructor, passing along all parameters, before accessing any of the parameters. In general, only the $config parameter should be accessed.
+ - The `process(&$state)`-function must be implemented. If this function completes, it is assumed that processing is completed, and that the $request array has been updated.
+ - If the `process`-function does not return, it must at a later time call `SimpleSAML_Auth_ProcessingChain::resumeProcessing` with the new request state. The request state must be an update of the array passed to the `process`-function.
+ - No pages may be shown to the user from the `process`-function. Instead, the request state should be saved, and the user should be redirected to a new page. This must be done to prevent unpredictable events if the user for example reloads the page.
+ - No state information should be stored in the filter object. It must instead be stored in the request state array. Any changes to variables in the filter object may be lost.
+ - The filter object must be serializable. It may be serialized between being constructed and the call to the `process`-function. This means that, for example, no database connections should be created in the constructor and later used in the `process`-function.
+
+Don't hestitate to ask on the simpleSAMLphp mailinglist if you have problems or questions, or want to share your *Auth Proc Filter* with others.
diff --git a/docs/simplesamlphp-modules.txt b/docs/simplesamlphp-modules.txt
new file mode 100644
index 000000000..1db15e89b
--- /dev/null
+++ b/docs/simplesamlphp-modules.txt
@@ -0,0 +1,219 @@
+simpleSAMLphp modules
+==================================================
+
+<!--
+ 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
+-->
+
+ * Version: `$Id: simplesamlphp-authproc.txt 1132 2009-01-11 12:46:19Z andreassolberg@gmail.com $`
+
+
+This document describes how the module system in simpleSAMLphp
+works. It descibes what types of modules there are, how they are
+configured, and how to write new modules.
+
+Overview
+--------
+
+There are currently three parts of simpleSAMLphp which can be stored in modules - authentication sources, authentication processing filters and themes. There is also support for defining hooks - functions run at specific times. More than one thing can be stored in a single module. There is also support for storing supporting files, such as templates and dictionaries, in modules.
+
+The different functionalities which can be created as modules will be described in more detail in the following sections; what follows is a short introduction to what you can du with them:
+
+ - Authentication sources implement different methods for authenticating users, for example simple login forms which authenticate against a database backend, or login methods which use client-side certificates.
+ - Authentication processing filters perform various tasks after the user is authenticated and has a set of attributes. They can add, remove and modify attributes, do additional authentication checks, ask questions of the user, +++.
+ - Themes allow you to package custom templates for multiple modules into a single module.
+
+
+## Module layout
+
+Each simpleSAMLphp module is stored in a directory under the the
+`modules`-directory. The module directory contains the following
+directories and files:
+
+default-disable
+: The presence of this file indicates that the module is disabled
+ by default. This module can be enabled by creating a file named
+ `enable` in the same directory.
+
+default-enable
+: The presence of this file indicates that the module is enabled
+ by default. This module can be disabled by creating a file named
+ `disable` in the same directory.
+
+dictionaries
+: This directory contains dictionaries which belong to this
+ module. To use a dictionary stored in a module, the extended tag
+ names can be used:
+ `{<module name>:<dictionary name>:<tag name>}` For
+ example, `{example:login:hello}` will look up `hello` in
+ `modules/example/dictionaries/login.php`.
+
+: It is also possible to specify
+ `<module name>:<dictionary name>` as the default
+ dictionary when instantiating the `SimpleSAML_XHTML_Template`
+ class.
+
+hooks
+: This directory contains hook functions for this module. Each
+ file in this directory represents a single function. See the
+ hook-section in the documentation for more information.
+
+lib
+: This directory contains classes which belong to this module.
+ All classes must be named in the following pattern:
+ `sspmod_<module name>_<class name>` When looking up the filename of
+ a class, simpleSAMLphp will search for `<class name>` in the `lib`
+ directory. Underscores in the class name will be translated into
+ slashes.
+
+: Thus, if simpleSAMLphp needs to load a class named
+ `sspmod_example_Auth_Source_Example`, it will load the file named
+ `modules/example/lib/Auth/Source/Example.php`.
+
+templates
+: These are module-specific templates. To use one of these
+ templates, specify `<module name>:<template file>.php`
+ as the template file in the constructor of
+ `SimpleSAML_XHTML_Template`. For example, `example:login-form.php`
+ is translated to the file
+ `modules/example/templates/default/login-form.php`. Note that
+ `default` in the previous example is defined by the `theme.use`
+ configuration option.
+
+themes
+: This directory contains themes the module defines. A single
+ module can define multiple themes, and these themes may override
+ all templates in all modules. Each subdirectory of `themes` defines
+ a theme. The theme directory contains a subdirectory for each
+ module. The templates stored under `simplesamlphp/templates` can be
+ overridden by a directory named `default`.
+
+: To use a theme provided by a module, the `theme.use`
+ configuration option should be set to
+ `<module name>:<theme name>`.
+
+: When using the theme `example:blue`, the template
+ `templates/default/login.php` will be overridden by
+ `modules/example/themes/blue/default/login.php`, while the template
+ `modules/core/templates/default/loginuserpass.php` will be
+ overridden by
+ `modules/example/themes/blue/core/loginuserpass.php`.
+
+www
+: All files stored in this directory will be available by
+ accessing the URL
+ `https://.../simplesamlphp/module.php/<module name>/<file name>`.
+ For example, if a script named `login.php` is stored in
+ `modules/example/www/`, it can be accessed by the URL
+ `https://.../simplesamlphp/module.php/example/login.php`.
+
+: To retrieve this URL, the
+ `SimpleSAML_Module::getModuleURL($resource)`-function can be used.
+ This function takes in a resource on the form `<module>/<file>`.
+ This function will then return an URL to the given file in the
+ `www`-directory of `module`.
+
+
+## Authentication sources
+
+An authentication source is used to authenticate a user and receive a set of attributes belonging to this user. In a single-signon setup, the authentication source will only be called once, and the attributes belonging to the user will be cached until the user logs out.
+
+Authentication sources are defined in `config/authsources.php`. This file contains an array of `name => configuration` pairs. The name is used to refer to the authentication source in metadata. When configuring an IdP to authenticate against an authentication source, the `auth` option should be set to this name. The configuration for an authentication source is an array. The first element in the array identifies the class which implements the authentication source. The remaining elements in the array are configuration entries for the authentication source.
+
+A typical configuration entry for an authentication source looks like this:
+
+ 'example-static' => array(
+ /* This maps to modules/exampleauth/lib/Auth/Source/Static.php */
+ 'exampleauth:Static',
+
+ /* The following is configuration which is passed on to the exampleauth:Static authentication source. */
+ 'uid' => 'testuser',
+ 'eduPersonAffiliation' => array('member', 'employee'),
+ 'cn' => array('Test User'),
+ ),
+
+To use this authentication source in a SAML 2.0 IdP, set the
+`auth`-option of the IdP to `'example-static'`:
+
+ '__DYNAMIC:1__' => array(
+ 'host' => '__DEFAULT__',
+ 'privatekey' => 'server.pem',
+ 'certificate' => 'server.crt',
+ 'auth' => 'example-static',
+ ),
+
+### Creating authentication sources
+
+Authentication sources are implemented by creating a class which is a subclass of the `SimpleSAML_Auth_Source`-class. They must implement at least one function - `authenticate`. This function may can either update the `$state`-array it receives with the attributes of the user and return, or it may save the state and redirect the user to another page for authentication. It redirects, it should later retrieve the state array, update it with the attributes and call `SimpleSAML_Source_Auth::completeAuth($state)`.
+
+There is also a simpler way to implement many authentication sources. If the authentication source only needs a username and password from the user, it may subclass `sspmod_core_Auth_UserPassBase`, and implement a single function - `login($username, $password)`. This function receives the username and password the user gives, and should return an associative array with the attributes of the user. If the username or password is incorrect, it should throw an exception: `SimpleSAML_Error_Error('WRONGUSERPASS')`
+
+Requirements for an authentication source:
+
+- Must be derived from the `SimpleSAML_Auth_Source`-class.
+
+-
+ If a constructor is implemented, it must first call the parent
+ constructor, passing along all parameters, before accessing any of
+ the parameters. In general, only the $config parameter should be
+ accessed.
+
+-
+ The `authenticate(&$state)`-function must be implemented. If this
+ function completes, it is assumed that the user is authenticated,
+ and that the $state array has been updated with the user's
+ attributes.
+
+-
+ If the `authenticate`-function does not return, it must at a later
+ time call `SimpleSAML_Auth_Source::completeAuth` with the new
+ state. The state must be an update of the array passed to the
+ `authenticate`-function.
+
+-
+ No pages may be shown to the user from the `authenticate`-function.
+ Instead, the state should be saved, and the user should be
+ redirected to a new page. This must be done to prevent
+ unpredictable events if the user for example reloads the page.
+
+-
+ No state information about any authentication should be stored in
+ the authentication source object. It must instead be stored in the
+ state array. Any changes to variables in the authentication source
+ object may be lost.
+
+-
+ The authentication source object must be serializable. It may be
+ serializes between being constructed and the call to the
+ `authenticate`-function. This means that, for example, no database
+ connections should be created in the constructor and later used in
+ the `authenticate`-function.
+
+
+Authentication processing filters
+---------------------------------
+
+*Authentication processing filters* is explained in a separate document:
+
+ * [Authentication processing filters](http://rnd.feide.no/content/authentication-processing-filters-simplesamlphp)
+
+
+
+## Themes
+
+This feature allows you to collect all your custom templates in one place. The directory structure is like this: `modules/<thememodule>/themes/<theme>/<module>/<template>` `thememodule` is the module where you store your theme, while `theme` is the name of the theme. A theme is activated by setting the `theme.use` configuration option to `<thememodule>:<theme>`. `module` is the module the template belongs to, and `template` is the template in that module.
+
+For example, `modules/example/themes/test/core/loginuserpass.php` replaces `modules/core/templates/default/loginuserpass.php`. `modules/example/themes/test/default/frontpage.php` replaces `templates/default/frontpage.php`. This theme can be activated by setting `theme.use` to `example:test`.
+
+## Hook interface
+
+The hook interface allows you to call a hook function in all enabled modules which define that hook. Hook functions are stored in a directory called 'hooks' in each module directory. Each hook is stored in a file named `hook_<hook name>.php`, and each file defines a function named `<module name>_hook_<hook name>`.
+
+Each hook function accepts a single argument. This argument will be passed by reference, which allows each hook to update that argument.
+
+There is currently a single user of the hook interface - the front page. The front page defines a hook named `frontpage`, which allows modules to add things to the different sections on the front page. For an example of this, see `modules/modinfo/hooks/hook_frontpage.php`.
+
+
+
diff --git a/docs/source/simplesamlphp-modules.xml b/docs/source/simplesamlphp-modules.xml
deleted file mode 100644
index 2e1c8da97..000000000
--- a/docs/source/simplesamlphp-modules.xml
+++ /dev/null
@@ -1,523 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<article>
- <title>simpleSAMLphp modules</title>
-
- <articleinfo>
- <date>2008-08-21</date>
-
- <pubdate>Thu Aug 28 16:26:12 2008</pubdate>
-
- <author>
- <firstname>Olav</firstname>
-
- <surname>Morken</surname>
- </author>
- </articleinfo>
-
- <section>
- <title>simpleSAMLphp documentation</title>
-
- <para>This document is part of the simpleSAMLphp documentation
- suite.</para>
-
- <itemizedlist>
- <listitem>
- <para><ulink url="http://rnd.feide.no/view/simplesamlphpdocs">List of
- all simpleSAMLphp documentation</ulink></para>
- </listitem>
- </itemizedlist>
-
- <para>This document describes how the module system in simpleSAMLphp
- works. It descibes what types of modules there are, how they are
- configured, and how to write new modules.</para>
- </section>
-
- <section>
- <title>Overview</title>
-
- <para>There are currently three parts of simpleSAMLphp which can be stored
- in modules - authentication sources, authentication processing filters and
- themes. There is also support for defining hooks - functions run at
- specific times. More than one thing can be stored in a single module.
- There is also support for storing supporting files, such as templates and
- dictionaries, in modules.</para>
-
- <para>The different functionalities which can be created as modules will
- be described in more detail in the following sections; what follows is a
- short introduction to what you can du with them:</para>
-
- <itemizedlist>
- <listitem>
- <para>Authentication sources implement different methods for
- authenticating users, for example simple login forms which
- authenticate against a database backend, or login methods which use
- client-side certificates.</para>
- </listitem>
-
- <listitem>
- <para>Authentication processing filters perform various tasks after
- the user is authenticated and has a set of attributes. They can add,
- remove and modify attributes, do additional authentication checks, ask
- questions of the user, +++.</para>
- </listitem>
-
- <listitem>
- <para>Themes allow you to package custom templates for multiple
- modules into a single module.</para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Module layout</title>
-
- <para>Each simpleSAMLphp module is stored in a directory under the the
- <filename>modules</filename>-directory. The module directory contains the
- following directories and files:</para>
-
- <para><glosslist>
- <glossentry>
- <glossterm>default-disable</glossterm>
-
- <glossdef>
- <para>The presence of this file indicates that the module is
- disabled by default. This module can be enabled by creating a file
- named <filename>enable</filename> in the same directory.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>default-enable</glossterm>
-
- <glossdef>
- <para>The presence of this file indicates that the module is
- enabled by default. This module can be disabled by creating a file
- named <filename>disable</filename> in the same directory.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>dictionaries</glossterm>
-
- <glossdef>
- <para>This directory contains dictionaries which belong to this
- module. To use a dictionary stored in a module, the extended tag
- names can be used: <literal>{<module name>:<dictionary
- name>:<tag name>}</literal> For example,
- <literal>{example:login:hello}</literal> will look up
- <literal>hello</literal> in
- <literal>modules/example/dictionaries/login.php</literal>.</para>
-
- <para>It is also possible to specify <literal><module
- name>:<dictionary name></literal> as the default
- dictionary when instantiating the
- <literal>SimpleSAML_XHTML_Template</literal> class.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>hooks</glossterm>
-
- <glossdef>
- <para>This directory contains hook functions for this module. Each
- file in this directory represents a single function. See the
- hook-section in the documentation for more information.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>lib</glossterm>
-
- <glossdef>
- <para>This directory contains classes which belong to this module.
- All classes must be named in the following pattern:
- <literal>sspmod_<module name>_<class name></literal>
- When looking up the filename of a class, simpleSAMLphp will search
- for <literal><class name></literal> in the
- <literal>lib</literal> directory. Underscores in the class name
- will be translated into slashes.</para>
-
- <para>Thus, if simpleSAMLphp needs to load a class named
- <literal>sspmod_example_Auth_Source_Example</literal>, it will
- load the file named
- <literal>modules/example/lib/Auth/Source/Example.php</literal>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>templates</glossterm>
-
- <glossdef>
- <para>These are module-specific templates. To use one of these
- templates, specify <literal><module name>:<template
- file>.php</literal> as the template file in the constructor of
- <literal>SimpleSAML_XHTML_Template</literal>. For example,
- <literal>example:login-form.php</literal> is translated to the
- file
- <literal>modules/example/templates/default/login-form.php</literal>.
- Note that <literal>default</literal> in the previous example is
- defined by the <literal>theme.use</literal> configuration
- option.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>themes</glossterm>
-
- <glossdef>
- <para>This directory contains themes the module defines. A single
- module can define multiple themes, and these themes may override
- all templates in all modules. Each subdirectory of
- <literal>themes</literal> defines a theme. The theme directory
- contains a subdirectory for each module. The templates stored
- under <literal>simplesamlphp/templates</literal> can be overridden
- by a directory named <literal>default</literal>.</para>
-
- <para>To use a theme provided by a module, the
- <literal>theme.use</literal> configuration option should be set to
- <literal><module name>:<theme name></literal>.</para>
-
- <para>When using the theme <literal>example:blue</literal>, the
- template <literal>templates/default/login.php</literal> will be
- overridden by
- <literal>modules/example/themes/blue/default/login.php</literal>,
- while the template
- <literal>modules/core/templates/default/loginuserpass.php</literal>
- will be overridden by
- <literal>modules/example/themes/blue/core/loginuserpass.php</literal>.</para>
- </glossdef>
- </glossentry>
-
- <glossentry>
- <glossterm>www</glossterm>
-
- <glossdef>
- <para>All files stored in this directory will be available by
- accessing the URL
- <literal>https://.../simplesamlphp/module.php/<module
- name>/<file name></literal>. For example, if a script
- 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
- <literal>SimpleSAML_Module::getModuleURL($resource)</literal>-function
- can be used. This function takes in a resource on the form
- <literal><module>/<file></literal>. This function will
- then return an URL to the given file in the
- <literal>www</literal>-directory of
- <literal>module</literal>.</para>
- </glossdef>
- </glossentry>
- </glosslist></para>
- </section>
-
- <section>
- <title>Authentication sources</title>
-
- <para>An authentication source is used to authenticate a user and receive
- a set of attributes belonging to this user. In a single-signon setup, the
- authentication source will only be called once, and the attributes
- belonging to the user will be cached until the user logs out.</para>
-
- <para>Authentication sources are defined in
- <filename>config/authsources.php</filename>. This file contains an array
- of <literal>name => configuration</literal> pairs. The name is used to
- refer to the authentication source in metadata. When configuring an IdP to
- authenticate against an authentication source, the <literal>auth</literal>
- option should be set to this name. The configuration for an authentication
- source is an array. The first element in the array identifies the class
- which implements the authentication source. The remaining elements in the
- array are configuration entries for the authentication source.</para>
-
- <para>A typical configuration entry for an authentication source looks
- like this:</para>
-
- <programlisting>'example-static' => array(
- /* This maps to modules/exampleauth/lib/Auth/Source/Static.php */
- 'exampleauth:Static',
-
- /* The following is configuration which is passed on to the exampleauth:Static authentication source. */
- 'uid' => 'testuser',
- 'eduPersonAffiliation' => array('member', 'employee'),
- 'cn' => array('Test User'),
-),</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>
-
- <programlisting>'__DYNAMIC:1__' => array(
- 'host' => '__DEFAULT__',
- 'privatekey' => 'server.pem',
- 'certificate' => 'server.crt',
- <emphasis>'auth' => 'example-static',</emphasis>
-),</programlisting>
-
- <section>
- <title>Creating authentication sources</title>
-
- <para>Authentication sources are implemented by creating a class which
- is a subclass of the <literal>SimpleSAML_Auth_Source</literal>-class.
- They must implement at least one function -
- <literal>authenticate</literal>. This function may can either update the
- <literal>$state</literal>-array it receives with the attributes of the
- user and return, or it may save the state and redirect the user to
- another page for authentication. It redirects, it should later retrieve
- the state array, update it with the attributes and call
- <literal>SimpleSAML_Source_Auth::completeAuth($state)</literal>.</para>
-
- <para>There is also a simpler way to implement many authentication
- sources. If the authentication source only needs a username and password
- from the user, it may subclass
- <literal>sspmod_core_Auth_UserPassBase</literal>, and implement a single
- function - <literal>login($username, $password)</literal>. This function
- receives the username and password the user gives, and should return an
- associative array with the attributes of the user. If the username or
- password is incorrect, it should throw an exception:
- <literal>SimpleSAML_Error_Error('WRONGUSERPASS')</literal></para>
-
- <para>Requirements for an authentication source:</para>
-
- <itemizedlist>
- <listitem>
- <para>Must be derived from the
- <literal>SimpleSAML_Auth_Source</literal>-class.</para>
- </listitem>
-
- <listitem>
- <para>If a constructor is implemented, it must first call the parent
- constructor, passing along all parameters, before accessing any of
- the parameters. In general, only the $config parameter should be
- accessed.</para>
- </listitem>
-
- <listitem>
- <para>The <literal>authenticate(&$state)</literal>-function must
- be implemented. If this function completes, it is assumed that the
- user is authenticated, and that the $state array has been updated
- with the user's attributes.</para>
- </listitem>
-
- <listitem>
- <para>If the <literal>authenticate</literal>-function does not
- return, it must at a later time call
- <literal>SimpleSAML_Auth_Source::completeAuth</literal> with the new
- state. The state must be an update of the array passed to the
- <literal>authenticate</literal>-function.</para>
- </listitem>
-
- <listitem>
- <para>No pages may be shown to the user from the
- <literal>authenticate</literal>-function. Instead, the state should
- be saved, and the user should be redirected to a new page. This must
- be done to prevent unpredictable events if the user for example
- reloads the page.</para>
- </listitem>
-
- <listitem>
- <para>No state information about any authentication should be stored
- in the authentication source object. It must instead be stored in
- the state array. Any changes to variables in the authentication
- source object may be lost.</para>
- </listitem>
-
- <listitem>
- <para>The authentication source object must be serializable. It may
- be serializes between being constructed and the call to the
- <literal>authenticate</literal>-function. This means that, for
- example, no database connections should be created in the
- constructor and later used in the
- <literal>authenticate</literal>-function.</para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
-
- <section>
- <title>Authentication processing filters</title>
-
- <para>Authentication processing filters postprocesses authentication
- information received from authentication sources. It is possible to use
- this for additional authentication checks, requesting the users consent
- before delivering attributes to the user, modifying the users attributes,
- and other things which should be performed before returning the user to
- the service provider he came from.</para>
-
- <para>Authentication processing filters are added to IdPs by setting the
- <literal>authproc</literal> option in the <literal>idp-hosted</literal>-
- and <literal>sp-remote</literal>-metadata. This is an array of filters,
- where the filters will typically run first to last. Each filter is either
- specified as a single string (if there is no configuration) or as an array
- (if there is configuration for the filter).</para>
-
- <para>Example:</para>
-
- <programlisting>'authproc' => array(
- 'example:Test',
- array('core:AttributeLimit', 'uid', 'mail', 'cn'),
- array('core:AttributeMap', 'mail' => 'email'),
-),</programlisting>
-
- <para>Filternames are on the form
- <literal><module>:<name></literal>, and map to
- <literal>modules/<module>/lib/Auth/Process/<name>.php</literal>,
- which is expected to be a subclass of
- <literal>SimpleSAML_Auth_ProcessingFilter</literal>.</para>
-
- <section>
- <title>Priority and merging of SP/IdP <literal>authproc</literal> filter
- lists</title>
-
- <para>By default, the filters defined in the IdP are run before those
- defined in the SP. However, sometimes one may want to change the order,
- 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
- 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 those with a lower priority:</para>
-
- <programlisting>/* saml20-idp-hosted.php */
-'authproc' => array(
- array('consent:Consent', '%priority' => 60),
-),
-
-/* saml20-sp-remote.php */
-'authproc' => array(
- array('core:AttributeLimit', 'uid', 'mail', 'cn'),
- array('core:AttributeMap', '%priority' => 70, 'mail' => 'email'),
-),</programlisting>
-
- <para>In this example, the <literal>core:AttributeLimit</literal>-filter
- will be run before the <literal>consent:Consent</literal>-filter. The
- <literal>core:AttributeMap</literal>-filter will be run last (after the
- <literal>consent:Consent</literal>-filter). Filters with the same
- priority value will be ordered in the order they appear in the
- configuration, with IdP filters preceeding SP filters.</para>
- </section>
-
- <section>
- <title>Creating authentication processing filters</title>
-
- <para>Authentication processing filters are created by creating a class
- under <literal>Auth/Process/</literal> in a module. This class is
- expected to subclass
- <literal>SimpleSAML_Auth_ProcessingFilter</literal>. A filter must
- implement at lease one function - the
- <literal>process(&$request)</literal>-function. This function can
- access the <literal>$request</literal>-array add, delete and modify
- attributes, and can also do more advanced processing based on the SP/IdP
- metadata (which is also included in the
- <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 it should retrieve the request, update it with the changes it
- is going to make, and call
- <literal>SimpleSAML_Auth_ProcessingChain::resumeProcessing</literal>.
- This function will continue processing the next configured
- filter.</para>
-
- <para>Requirements for authentication processing filters:</para>
-
- <itemizedlist>
- <listitem>
- <para>Must be derived from the
- <literal>SimpleSAML_Auth_ProcessingFilter</literal>-class.</para>
- </listitem>
-
- <listitem>
- <para>If a constructor is implemented, it must first call the parent
- constructor, passing along all parameters, before accessing any of
- the parameters. In general, only the $config parameter should be
- accessed.</para>
- </listitem>
-
- <listitem>
- <para>The <literal>process(&$state)</literal>-function must be
- implemented. If this function completes, it is assumed that
- processing is completed, and that the $request array has been
- updated.</para>
- </listitem>
-
- <listitem>
- <para>If the <literal>process</literal>-function does not return, it
- must at a later time call
- <literal>SimpleSAML_Auth_ProcessingChain::resumeProcessing</literal>
- with the new request state. The request state must be an update of
- the array passed to the <literal>process</literal>-function.</para>
- </listitem>
-
- <listitem>
- <para>No pages may be shown to the user from the
- <literal>process</literal>-function. Instead, the request state
- should be saved, and the user should be redirected to a new page.
- This must be done to prevent unpredictable events if the user for
- example reloads the page.</para>
- </listitem>
-
- <listitem>
- <para>No state information should be stored in the filter object. It
- must instead be stored in the request state array. Any changes to
- variables in the filter object may be lost.</para>
- </listitem>
-
- <listitem>
- <para>The filter object must be serializable. It may be serialized
- between being constructed and the call to the
- <literal>process</literal>-function. This means that, for example,
- no database connections should be created in the constructor and
- later used in the <literal>process</literal>-function.</para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
-
- <section>
- <title>Themes</title>
-
- <para>This feature allows you to collect all your custom templates in one
- place. The directory structure is like this:
- <literal>modules/<thememodule>/themes/<theme>/<module>/<template></literal>
- <literal>thememodule</literal> is the module where you store your theme,
- while <literal>theme</literal> is the name of the theme. A theme is
- activated by setting the <literal>theme.use</literal> configuration option
- to <literal><thememodule>:<theme></literal>.
- <literal>module</literal> is the module the template belongs to, and
- <literal>template</literal> is the template in that module.</para>
-
- <para>For example,
- <literal>modules/example/themes/test/core/loginuserpass.php</literal>
- replaces
- <literal>modules/core/templates/default/loginuserpass.php</literal>.
- <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>
- </section>
-
- <section>
- <title>Hook interface</title>
-
- <para>The hook interface allows you to call a hook function in all enabled
- modules which define that hook. Hook functions are stored in a directory
- called 'hooks' in each module directory. Each hook is stored in a file
- named <literal>hook_<hook name>.php</literal>, and each file defines
- a function named
- <literal><module name>_hook_<hook name></literal>.</para>
-
- <para>Each hook function accepts a single argument. This argument will be
- passed by reference, which allows each hook to update that
- argument.</para>
-
- <para>There is currently a single user of the hook interface - the front
- page. The front page defines a hook named <literal>frontpage</literal>,
- which allows modules to add things to the different sections on the front
- page. For an example of this, see
- <filename>modules/modinfo/hooks/hook_frontpage.php</filename>.</para>
- </section>
-</article>
\ No newline at end of file
--
GitLab