<?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'  =&gt; false,
'enable.saml20-idp' =&gt; true,
'enable.shib13-sp'  =&gt; false,
'enable.shib13-idp' =&gt; 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>(|(&lt;attr1&gt;=&lt;username&gt;)(&lt;attr2&gt;=&lt;username&gt;)...)</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' =&gt; 'ldap.example.org',
  'auth.ldap.attributes' =&gt; NULL,
  'auth.ldap.enable_tls' =&gt; FALSE,

  /* Enable searching. */
  'auth.ldap.search.enable' =&gt; TRUE,

  /* The base DN for the search. */
  'auth.ldap.search.base' =&gt; 'cn=users,dc=example,dc=org',

  /* The user can authenticate using the uid or the email address. */
  'auth.ldap.search.attributes' =&gt; array('uid', 'mail'),

  'auth.ldap.search.username' =&gt; 'uid=authsearch,cn=server,dc=example,dc=org',
  'auth.ldap.search.password' =&gt; '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' =&gt; array(

 // The hostname of the server (VHOST) that this SAML entity will use.
 'host'            =&gt; 'sp.example.org',
 
 // X.509 key and certificate. Relative to the cert directory.
 'privatekey'      =&gt; 'server.pem',
 'certificate'     =&gt; 'server.crt',
 
 // Authentication plugin to use. login.php is the default one that uses LDAP.
 'auth'             =&gt; 'auth/login.php',
 'authority'        =&gt; '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>&lt;simpleSAMLphp-root&gt;/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>&lt;simpleSAMLphp-root&gt;/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' =&gt; 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' =&gt; array(
 'AssertionConsumerService' =&gt; 'https://saml2sp.example.org/simplesaml/saml2/sp/AssertionConsumerService.php', 
 'SingleLogoutService'      =&gt; 'https://saml2sp.example.org/simplesaml/saml2/sp/SingleLogoutService.php',
 
 'attributes'               =&gt; array('email', 'eduPersonPrincipalName'),
 'name'                     =&gt; '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>