-
Olav Morken authored
git-svn-id: https://simplesamlphp.googlecode.com/svn/trunk@613 44740490-163a-0410-bde0-09ae8108e29a
13b7d188
Code owners
Assign users and groups as approvers for specific file changes. Learn more.
<?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>Using simpleSAMLphp as an identity provider</title>
<articleinfo>
<date>2007-10-15</date>
<pubdate>Mon Apr 28 11:48:30 2008</pubdate>
<author>
<firstname>Andreas Åkre</firstname>
<surname>Solberg</surname>
<email>andreas.solberg@uninett.no</email>
</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 assumes that you already have a installation of
simpleSAMLphp. Before you continue, make sure all the required entries in
the check list at the bottom is showing green light.</para>
</section>
<section>
<title>Enabling the Identity Provider functionality</title>
<para>Edit <filename>config.php</filename>, and enable either the SAML 2.0
IdP or the Shib 1.3 IdP, depending on your needs. By default, SAML 2.0 SP
IdP functionality is enabled. 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>
<para>In the <filename>www/auth</filename> directory, each file represents
an authentication module. The IdP hosted metadata configuration specifies
which authentication module to use for that specific IdP. You can
implement your own authentication module, see <xref
linkend="sect.customauth" />.</para>
<para>These authentication modules are included:</para>
<para><glosslist>
<glossentry>
<glossterm>auth/login.php</glossterm>
<glossdef>
<para>This is the standard LDAP backend authentication module. It
uses LDAP configuration from the <filename>config.php</filename> file.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>auth/login-ldapmulti.php</glossterm>
<glossdef>
<para>This authentication module lets you connect to multiple
LDAPs depending on the home organization selected by the
user.</para>
</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>
<glossdef>
<para>This authentication module will authenticate users against
an RADIUS server instead of LDAP.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>auth/login-auto.php</glossterm>
<glossdef>
<para>This module will automatically login the user with some test
details. You can use this to test the IdP functionality if you do
not have</para>
<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, followed by attribute lookup in
LDAP.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>auth/login-tlsclient.php</glossterm>
<glossdef>
<para>Authentication via client certificates. (using the apache
SSL module)</para>
</glossdef>
</glossentry>
</glosslist></para>
<section>
<title>Configuring the LDAP authentication module</title>
<para>The LDAP module is found in
<filename>auth/login.php</filename>.</para>
<para>If you want to perform local authentication using this server, using the LDAP authentication plugin, the following parameters should be
configured in <filename>config/ldap.php</filename>:</para>
<itemizedlist>
<listitem>
<para><literal>auth.ldap.dnpattern</literal>: Which DN to bind to.
<literal>%username%</literal> is replaced with the user name typed
in.</para>
</listitem>
<listitem>
<para><literal>auth.ldap.hostname</literal>: Host name of the LDAP
server</para>
</listitem>
<listitem>
<para><literal>auth.ldap.attributes</literal>: Search parameter to
LDAP. List of attributes to be extracted. Set this option to
<literal>null</literal> to retrieve all attributes available.</para>
</listitem>
<listitem>
<para><literal>auth.ldap.enable_tls</literal>: Will perform
<code>ldap_start_tls()</code> after creation the connectino to the
LDAP server.</para>
</listitem>
</itemizedlist>
<section>
<title>Searching for the user's DN</title>
<para>It is possible to search for the DN of the user by matching the
username provided by the user against one or more attributes. This
feature is configured by the following options in
<filename>config/ldap.php</filename>:</para>
<itemizedlist>
<listitem>
<para><literal>auth.ldap.search.enable</literal>: Whether
searching for the user's DN should be enabled. Set this to
<literal>TRUE</literal> to enable searching.</para>
</listitem>
<listitem>
<para><literal>auth.ldap.search.base</literal>: The DN we should
search for the user in.</para>
</listitem>
<listitem>
<para><literal>auth.ldap.search.attributes</literal>: The
attributes we shoule match the username against. This can be a
single attribute, in which case it should be a string, or multiple
attributes, in which case it should be an array of strings.</para>
<para>If this is multiple attributes, they will be joined into a
search query with the following form:
<literal>(|(<attr1>=<username>)(<attr2>=<username>)...)</literal>
</para>
</listitem>
<listitem>
<para><literal>auth.ldap.search.username</literal>: The user we
should authenticate to the LDAP server as before searching.
Leave this as <literal>NULL</literal> if it isn't necessary to
authenticate to the server before searching.</para>
</listitem>
<listitem>
<para><literal>auth.ldap.search.password</literal>: The password
for the user selected with the <literal>auth.ldap.search.username</literal> option.</para>
</listitem>
</itemizedlist>
<example>
<title>Configuring LDAP for searching</title>
<programlisting>$config = array (
'auth.ldap.hostname' => 'ldap.example.org',
'auth.ldap.attributes' => NULL,
'auth.ldap.enable_tls' => FALSE,
/* Enable searching. */
'auth.ldap.search.enable' => TRUE,
/* The base DN for the search. */
'auth.ldap.search.base' => 'cn=users,dc=example,dc=org',
/* The user can authenticate using the uid or the email address. */
'auth.ldap.search.attributes' => array('uid', 'mail'),
'auth.ldap.search.username' => 'uid=authsearch,cn=server,dc=example,dc=org',
'auth.ldap.search.password' => 'secret',
);</programlisting>
</example>
</section>
</section>
<section>
<title>Configure the tlsclient authenticaiton module</title>
<para>Configure apache like this:</para>
<programlisting> SSLEngine On
SSLCertificateFile /etc/ssl/private/bridge.pem
SSLCertificateKeyFile /etc/ssl/private/bridge.key
SSLCertificateChainFile /etc/ssl/certs/sureserverEDU.pem
SSLOptions +StdEnvVars +ExportCertData
KeepAliveTimeout 60
SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL
SSLCACertificateFile "/etc/ssl/private/tlsclienttest-ca.crt"
SSLVerifyClient optional
SSLVerifyDepth 1</programlisting>
<para>And, then configure the identity provider to use the
authentication module:
<filename>auth/login-tlsclient.php</filename>.</para>
</section>
<section>
<title>Configuring the multi-LDAP authenticaiton module</title>
<para>The module is found in
<filename>auth/login-ldapmulti.php</filename>.</para>
<note>
<para>Documentation will be added later. For now, contact the
author.</para>
</note>
</section>
</section>
<section>
<title>Setting up a SSL signing certificate</title>
<para>For test purposes, you can skip this section, and use the
certificate included in the simpleSAMLphp distribution.</para>
<para>For a production system, you must generate a new certificate for your IdP.</para>
<warning>
<para>The certificate that follows the simpleSAMLphp distribution must
<emphasis>NEVER</emphasis> be used in production, as the private key is
also included in the package and can be downloaded by anyone.</para>
</warning>
<para>Here is an examples of openssl commands to generate a new key and a
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
openssl req -new -key server2.key -out server2.csr
openssl x509 -req -days 60 -in server2.csr -signkey server2.key -out server2.crt</screen>
<para>The certificate above will be valid for 60 days.</para>
<note>
<para>simpleSAMLphp will only work with RSA and not DSA
certificates.</para>
</note>
</section>
<section>
<title>Configuring metadata for an SAML 2.0 IdP</title>
<para>To setup a SAML 2.0 IdP you must configure two metadata files:
<filename>saml20-idp-hosted.php</filename> and
<filename>saml20-sp-remote.php</filename>.</para>
<section>
<title>Configuring SAML 2.0 IdP Hosted metadata</title>
<para>This is the configuration of the IdP itself. Here is some example
config:</para>
<programlisting>// The SAML entity ID is the index of this config.
'idp.example.org' => array(
// The hostname of the server (VHOST) that this SAML entity will use.
'host' => 'sp.example.org',
// X.509 key and certificate. Relative to the cert directory.
'privatekey' => 'server.pem',
'certificate' => 'server.crt',
// Authentication plugin to use. login.php is the default one that uses LDAP.
'auth' => 'auth/login.php',
'authority' => 'login',
),</programlisting>
<para>Parameter details:</para>
<section>
<title>Mandatory metadata fields</title>
<glosslist>
<glossentry>
<glossterm>index in the <code>$metadata</code> array</glossterm>
<glossdef>
<para>The entity ID of the IdP. In this example:
<literal>idp.example.org</literal>.</para>
<para>simpleSAMLphp supports dynamic entityIDs that matches a
URL where simpleSAMLphp automatically generates metadata for the
hosted entity. To enable this functionality, set the index to be
<literal>__DYNAMIC:1__</literal>. The index needs to be unique,
so when you have multiple entries, increase the integer after the colon. When the index <literal>__DYNAMIC:1__</literal> is
used, the resulting generated entity becomes something
like:</para>
<literallayout>https://sp.example.org/simplesaml/saml2/idp/metadata.php</literallayout>
</glossdef>
</glossentry>
<glossentry>
<glossterm>host</glossterm>
<glossdef>
<para>Host name of the server running this IdP. One of your
metadata entries can have the value
<literal>__DEFAULT__</literal>. A default entry will be used
when no other entry matches the current hostname.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>privatekey</glossterm>
<glossdef>
<para>Name of private key file in PEM format, in the
<filename>certs</filename> directory.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>certificate</glossterm>
<glossdef>
<para>Name of certificate file in PEM format, in the
<filename>certs</filename> directory.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>auth</glossterm>
<glossdef>
<para>Which authentication module to use. Default:
<filename>auth/login.php, </filename>the LDAP authentication
module.</para>
</glossdef>
</glossentry>
</glosslist>
</section>
<section>
<title>Optional metadata fields</title>
<glosslist>
<glossentry>
<glossterm>privatekey_pass</glossterm>
<glossdef>
<para>Passphrase for the private key.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>requireconsent</glossterm>
<glossdef>
<para>Set to true if you want to require user's consent each
time attributes are sent to an SP.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>authority</glossterm>
<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. Specifying this
parameter is highly recommended.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>attributemap</glossterm>
<glossdef>
<para>Mapping table for translating attribute names. For further
information, see the <emphasis>Advances Features</emphasis>
document.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>attributealter</glossterm>
<glossdef>
<para>Table of custom functions that injects or modifies
attributes. For further information, see the <emphasis>Advances
Features</emphasis> document.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>userid.attribute</glossterm>
<glossdef>
<para>The attribute name of an attribute which uniquely
identifies the user. This attribute is used if simpleSAMLphp
needs to generate a persistent unique identifier for the user.
This option can be set in both the IdP-hosted and the SP-remote
metadata. The value in the sp-remote metadata has the highest
priority. The default value is
<literal>eduPersonPrincipalName</literal>.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>AttributeNameFormat</glossterm>
<glossdef>
<para>What value will be set in the Format field of attribute
statements. This parameter can be configured multiple places,
and the actual value used is fetched from metadata by the
following priority:</para>
<orderedlist>
<listitem>
<para>SP Remote Metadata</para>
</listitem>
<listitem>
<para>IdP Hosted Metadata</para>
</listitem>
<listitem>
<para>Default value:
<literal>urn:oasis:names:tc:SAML:2.0:attrname-format:basic</literal></para>
</listitem>
</orderedlist>
<para>Some examples of values specified in the SAML 2.0 Core Specification:</para>
<itemizedlist>
<listitem>
<para><literal>urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified</literal></para>
</listitem>
<listitem>
<para><literal>urn:oasis:names:tc:SAML:2.0:attrname-format:uri</literal>
(Used as default in Shibboleth 2.0)</para>
</listitem>
<listitem>
<para><literal>urn:oasis:names:tc:SAML:2.0:attrname-format:basic</literal>
(Used as default in Sun Access Manager)</para>
</listitem>
<listitem>
<para>You can define your own value.</para>
</listitem>
</itemizedlist>
</glossdef>
</glossentry>
<glossentry>
<glossterm>SingleSignOnService</glossterm>
<glossdef>
<para>Override the default URL for the SingleSignOnService for
this IdP. This is an absolute URL. The default value is
<literal><simpleSAMLphp-root>/saml2/idp/SSOService.php</literal></para>
<para>Note that this only changes the values in the generated
metadata and in the messages sent to others. You must also
configure your webserver to deliver this URL to the correct PHP
page.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>SingleLogoutService</glossterm>
<glossdef>
<para>Override the default URL for the SingleLogoutService for
this IdP. This is an absolute URL. The default value is
<literal><simpleSAMLphp-root>/saml2/idp/SingleLogoutService.php</literal></para>
<para>Note that this only changes the values in the generated
metadata and in the messages sent to others. You must also
configure your webserver to deliver this URL to the correct PHP
page.</para>
</glossdef>
</glossentry>
</glosslist>
</section>
<section>
<title>Fields for signing authentication requests</title>
<para>By default, simpleSAMLphp will not sign the HTTP-REDIRECT
LogoutRequest. To activate signing, set the
<literal>request.signing</literal> parameter to
<literal>true</literal>. The signing will use the same
privatekey/certificate as used for signing the AuthnResponse.</para>
<glosslist>
<glossentry>
<glossterm>request.signing</glossterm>
<glossdef> <para>Boolean, default <literal>false</literal>.</para>
</glossdef>
</glossentry>
</glosslist>
<example>
<title>Example of configured signed requests</title>
<programlisting> 'request.signing' => true,</programlisting>
</example>
</section>
</section>
<section>
<title>Configuring SAML 2.0 SP Remote metadata</title>
<para>In the file <filename>saml20-sp-remote.php</filename>, you
configure all SPs that you trust. Here is an example:</para>
<programlisting>/*
* Example simpleSAMLphp SAML 2.0 SP
*/
'saml2sp.example.org' => array(
'AssertionConsumerService' => 'https://saml2sp.example.org/simplesaml/saml2/sp/AssertionConsumerService.php',
'SingleLogoutService' => 'https://saml2sp.example.org/simplesaml/saml2/sp/SingleLogoutService.php',
'attributes' => array('email', 'eduPersonPrincipalName'),
'name' => 'Example service provider',
),</programlisting>
<para>Parameter details:</para>
<section>
<title>Mandatory metadata fields</title>
<glosslist>
<glossentry>
<glossterm>index in the <code>$metadata</code> array</glossterm>
<glossdef>
<para>Entity ID of the given SP. Here:
<literal>saml2sp.example.org</literal>.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>AssertionConsumerService</glossterm>
<glossdef>
<para>URL of this SAML 2.0 endpoint. Ask the SP if you are
uncertain. You may find the endpoint URL in SAML 2.0 metadata
received from the SP.</para>
</glossdef>
</glossentry>
</glosslist>
</section>
<section>
<title>Optional metadata fields</title>
<glosslist>
<glossentry>
<glossterm>SingleLogoutService</glossterm>
<glossdef>
<para>URL of this SAML 2.0 endpoint. Ask the SP if you are
uncertain. You may find the endpoint URL in SAML 2.0 metadata
received from the SP.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>NameIDFormat</glossterm>
<glossdef>
<para>Set it to the default:
<literal>transient</literal>.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>SPNameQualifier</glossterm>
<glossdef>
<para>SP NameQualifier for this SP. If not set, the IdP will set
the SPNameQualifier to be the SP entity ID.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>AttributeNameFormat</glossterm>
<glossdef>
<para>What value will be set in the Format field of attribute
statements. This parameter can be configured multiple places,
and the actual value used is fetched from metadata by the
following priority:</para>
<orderedlist>
<listitem>
<para>SP Remote Metadata</para>
</listitem>
<listitem>
<para>IdP Hosted Metadata</para>
</listitem>
<listitem>
<para>Default value:
<literal>urn:oasis:names:tc:SAML:2.0:attrname-format:basic</literal></para>
</listitem>
</orderedlist>
<para>Some examples of values specified in the SAML 2.0 Core
Specification:</para>
<itemizedlist>
<listitem>
<para><literal>urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified</literal></para>
</listitem>
<listitem>
<para><literal>urn:oasis:names:tc:SAML:2.0:attrname-format:uri</literal>
(Used as default in Shibboleth 2.0)</para>
</listitem>
<listitem>
<para><literal>urn:oasis:names:tc:SAML:2.0:attrname-format:basic</literal>
(Used as default in Sun Access Manager)</para>
</listitem>
<listitem>
<para>You can define your own value.</para>
</listitem>
</itemizedlist>
</glossdef>
</glossentry>
<glossentry>
<glossterm>base64attributes</glossterm>
<glossdef>
<para>Boolean, default <literal>false</literal>: Perform base64
encoding of attributes sent to this SP. This parameter must be
set according to what the SP expects.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>simplesaml.nameidattribute</glossterm>
<glossdef>
<para>If the <code>NameIDFormat</code> is set to
<literal>email</literal>, then the email address is extracted
from the attribute with this name. E.g. if
<code>simplesaml.nameidattribute</code> is set to uid, and the
authentcation module provides an attribute named
<code>uid</code>, this attribute value is set as the
NameID.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>attributemap</glossterm>
<glossdef>
<para>Mapping table for translating attribute names. For further
information, see the <emphasis>Advances Features</emphasis>
document.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>attributealter</glossterm>
<glossdef>
<para>Table of custom functions that injects or modifies
attributes. For further information, see the <emphasis>Advances
Features</emphasis> document.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>attributes</glossterm>
<glossdef>
<para>Array of attributes sent to the SP. If this field is not
set, the SP receives all attributes available at the IdP.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>simplesaml.attributes</glossterm>
<glossdef>
<para>Boolean, default <literal>true</literal>: Send an
attribute statement to the SP.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>name</glossterm>
<glossdef>
<para>A descriptive name of the SP. (Used in the consent
module)</para>
</glossdef>
</glossentry>
<glossentry> <glossterm>description</glossterm>
<glossdef>
<para>A longer description of the SP. (Not used)</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>request.signing</glossterm>
<glossdef>
<para>Boolean, default <literal>false</literal>. Defines whether
this IdP should require signed requests from this SP.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>certificate</glossterm>
<glossdef>
<para>Name of certificate file for verifying the signature when
<literal>request.signing</literal> is set to
<literal>true</literal>.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>ForceAuthn</glossterm>
<glossdef>
<para>Set this <literal>true</literal> to force authentication
when receiving authentication requests from this SP. The default
is <literal>false</literal>.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>assertion.enctyption</glossterm>
<glossdef>
<para>Boolean, default <literal>false</literal>. Defines whether
this IdP shoul encrypt assertions to this SP.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>sharedkey</glossterm>
<glossdef>
<para>Used for optional symmetric encryption of assertions.
Currently the algorithm is hardcoded to AES128_CBC/RIJNDAEL_128
which uses up to 128 bit for the passphrase/key. If you want to
use a sessionkey which is encrypted by this idp's private key do
not specify a sharedkey.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>userid.attribute</glossterm>
<glossdef>
<para>The attribute name of an attribute which uniquely
identifies the user. This attribute is used if simpleSAMLphp
needs to generate a persistent unique identifier for the user.
This option can be set in both the IdP-hosted and the SP-remote
metadata. The value in the sp-remote metadata has the highest
priority. The default value is
<literal>eduPersonPrincipalName</literal>.</para>
</glossdef>
</glossentry> </glosslist>
</section>
</section>
</section>
<section>
<title>Configuring metadata for a Shibboleth 1.3 IdP</title>
<para>In the file <filename>shib13-idp-hosted.php</filename>, you
configure metadata for the Shibboleth 1.3 IdP. In the file
<filename>shib13-sp-remote.php</filename>, you configurethe list of
trusted SPs using the Shibboleth 1.3 protocol. This configuration is very
similar to configuring SAML 2.0 metadata; please find information in the
previous chapter.</para>
</section>
<section>
<title>Test IdP</title>
<para>To test the IdP, it is best to configure two hosts with
simpleSAMLphp, and use the SP demo example to test the IdP.</para>
<tip>
<para>To make the initial test up and running with minimal hassle, use
the login-auto if you do not want to setup a user storage, and use the
included certificate so you do not need to create a new one.</para>
</tip>
</section>
<section>
<title>Support</title>
<para>If you need help to make this work, or want to discuss simpleSAMLphp
with other users of the software, you are fortunate: Around simpleSAMLphp
there is a great Open source community, and you are welcome to join! The
forums are open for you to ask questions, contribute answers other further
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>
<appendix>
<title id="sect.customauth">Writing your own authentication module</title>
<para>You can write your own authentication module. Just copy one of the
files in the www/auth directory and play with it, then configure an IdP to
use that module with the auth parameter in the metadata. The file must
support incoming URL parameters, massage the session object with login state information and return to the RelayState, and that is all you need
to do!</para>
<tip>
<para>Instead of changing the code of the builtin authentication module,
copy it into a new file and edit that. That way, your module will not be
replaced or in conflict when you upgrade simpleSAMLphp to a newer
version.</para>
</tip>
<section>
<title>Authentication API</title>
<para>The authentication plugin should be placed in the
<filename>auth</filename> directory.</para>
<para>The following parameters must be accepted in the incomming
URL:</para>
<itemizedlist>
<listitem>
<para><literal>RelayState</literal>: URL where the user is sent
after authentication within the plugin.</para>
</listitem>
<listitem>
<para><literal>RequestID</literal>: ID of an incomming
request.</para>
</listitem>
</itemizedlist>
<para>The initSSO.php takes in addition the following parameters:</para>
<itemizedlist>
<listitem>
<para><literal>idpentityid</literal>: This is the entityid of the
IdP to authenticate with. This parameter is optional, if not set the
default for this host will be used.</para>
</listitem>
<listitem>
<para><literal>spentityid</literal>: This is which SP config to use.
This parameter is optional, if not set the default for this host
will be used.</para>
</listitem>
</itemizedlist>
<para>In hosted IdP metadata there is a config parameter auth that will
tell simpleSAML which authentication plugin that can be used.</para>
<tip>
<para>The authentication API is pretty basic. The easiest way to
understand how it works is to look at one of the existing plugins that
is located in the auth directory of your installation.</para>
</tip>
</section>
</appendix>
</article>